Recommendations for a Robust Integration

The following is a list of strongly recommended implementations and best practices for creating a robust integration with Astra. These are not hard requirements. However, they will significantly improve the end-user experience and your team’s overall developer experience. Some recommendations are specific to the solution you are implementing (Accelerated ACH vs. Instant Funding), while others apply to both.

Recommendations & Best Practices

Store Request-Ids: All API requests include a request-id in the header of the response. We strongly recommend logging and/or storing all Request-Ids as they can be used to query the details of specific API calls. Please include Request-Ids in all Sandbox and Production integration related questions, as this will enable us to quickly investigate and provide you with answers. Astra's API Documentation

Review Guide to Astra’s SDK: It’s critical that your team reviews and accounts for all scenarios outlined in our Guide to Astra’s SDK. Not accounting for one of the outlined scenarios could ultimately lead to and prevent an end-user from initiating Routines and Transfers. Please read our Guide to Astra’s SDK.

Phone Read Only: We highly recommend that you use the phone_read_only parameter, which autofills the authentication screen with the UserIntent phone number and locks the number so it cannot be edited. This saves the end-user time since they do not have to re-enter their phone number, and prevents the end-user from entering a different phone number or making a mistake while attempting to enter the correct phone number. Please read our Request Authorization section to learn more.

Persist a User’s Authorization: To create the most seamless user experience with Astra, it’s strongly recommended that you persist an end-user’s authorization so that the end-user only has to authorize once through Astra’s SDK. Persisting an end-user’s authorization consists of three parts:

  • Store both the access_token and refresh_token in your backend database. First, you need the refresh_token to refresh the authorization. Second, if you are not storing and updating these data items, you may encounter an issue where the wrong access_token is being utilized, but it in fact has expired or been revoked.
  • After the first access_token is generated, we recommend that you attempt to refresh the access_token before subsequent API requests. In your backend business logic, we recommend wrapping the request in a try/except method to complete the refresh and catch exceptions.
  • Additionally, we recommend that you obtain a new refresh_token for all of your existing tokens by way of a weekly recurring Task or cron job within the ten day lifespan of the refresh_token.

Let Users Re-authorize via Astra’s SDK: To create the most seamless user experience, most clients persist an end-user’s authorization so that they don’t have to re-authorize via our SDK every time their access_token expires. Whether you are persisting authorization or not, we require that you build a flow that prompts an end-user to re-authorize if you detect that their tokens have expired, to avoid a scenario where an end-user can’t re-authorizing and is blocked from using Astra. If you are persisting authorizing, this is a great failsafe to have in the event that your cron job encounters an error and doesn’t successfully refresh an end-user’s tokens. Authorize a User endpoint, Refresh Authorization endpoint

Ingest Astra Webhooks: We highly recommend that your team listens for and ingest Astra’s Webhooks for Users, Transfers, and Routines. Your team will be notified the moment the status of any of the three objects changes. To enable webhooks, navigate to your Astra Developer Dashboard and go to the webhook section at the bottom of the Dashboard tab. Specify a URL and toggle the webhooks you’d like to receive. Astra’s User Webhooks are especially important because if a User is suspended on our platform for fraudulent activity, your team will be notified and can take immediate action such as closing their account or freezing their card.

Ingest Plaid Webhooks: If you have a direct integration with Plaid and are using Astra for our Accelerated ACH solution, we highly recommend that you listen to and ingest Plaid webhooks, as they communicate the status and health of Plaid Access Tokens. If a Plaid access_token is in an error state, the end-user should be made aware of this and re-authorize their account connection through Plaid Link Update Mode. If a Plaid access_token remains in an error state, the end-user may be prevented from initiating new transfers or will encounter delayed transfers as Access Tokens in an error state impacts Astra’s ability to obtain the available account balance in real-time.

Let Users Delete Cards: If you are leveraging Astra for our Instant Funding solution, we strongly recommend that you implement a delete card option through our Delete Cards endpoint. This endpoint can be used to delete both externally linked debit cards as well as client-issued debit cards. Enabling end-users to delete their cards becomes especially useful when an end-user’s card expires and they need to re-add the same card with an updated expiration date or when the end-user links a card with a physical address that is not on file with their bank or not associated with their Astra profile.

Let Users Cancel Transfers: If you are leveraging Astra for our Accelerated ACH solution, we strongly recommend that you enable your end-users to cancel their transfers. Astra provides a Cancel Transfer endpoint that can be used if an end-user wishes to cancel a transfer within the same ACH window in which the transfer was created. It’s important to note that once the funds leave the account (after the first business day the transfer was created) the end-user will not be able to cancel their transfer. Canceling Transfers is not applicable for Debit Transfers.

Let Users Delete Routines: If your Astra integration is leveraging any of our Recurring Routines as part of your Accelerated ACH solution, your end-users must be able to delete their recurring routines through our Delete Routines endpoint so that scheduled routine requests are no longer sent to Astra.

Manage UserIntents: For managing UserIntents, Astra recommends that once a UserIntent is created, you should store that UserIntent ID with the User record. A New UserIntent should only be created if an end-user is starting from scratch or had originally provided incorrect information. Properly managing UserIntents will reduce duplicate UserIntent data in our system and ultimately provide a smoother onboarding experience for new end-users.

Balance Endpoint: To enable all end-users to have T+1 settlement speeds, have outbound ACH transfers from their Astra account and or to enable Astra to gracefully heal and clawback funds from a transfer that failed due to a return code, Astra will need to know the available balance of the end-user’s generic Astra account (Account Created by Account and Routing Number). Our Balance Endpoint provides Astra with the ability to get a live reading of your end-user’s available account balance and allows us to better heal transfers and provide your end-user’s with greater transfer capabilities.

Failed Transfers: If you are notified that a transfer has failed (via a transfer_updated webhook) and the funds have already landed in the end-user’s account, you should remove the transfer balance from the available balance in your client’s system at that time. When Astra reverses a transfer, the available balance accessed via the Balance Endpoint (see above) should show the full transfer amount available for Astra to deduct. This should indicate that we are confirmed and in the clear to debit the funds.

Status Pages: Please subscribe to our production and sandbox status pages below to keep up to date with status updates: