Recommendations for a Robust Integration
The following is a list of strongly recommended implementations and best practices for creating a robust integration with Astra. This guide offers a series of recommendations to create the most minimal and seamless user experience possible for your user base, given the payment solution you're implementing. These recommendations will also significantly improve your team’s developer experience.
- Persist Authorization
- Manual Re-authorization
- Trusted Authentication
- Calculate Aggregate Inbound Transfer Volumes
Instant Funding & Instant Disbursements:
- Own the Debit Card Form UI (via VGS or similar)
- Delete Debit Cards
- Block Routine Requests for Frozen Client-Issued Debit Cards
- Cancel Transfers
- Delete Routines
- Store Request IDs
- Review Guide to Astra’s SDK
- Register Checking Accounts
- Status Updates
- Managing UserIntents
- Create UserIntents When Users Select an Astra Funding Option
- Create One-Off UserIntents
- Managing UserIntents
- Ingest Astra Webhooks
- Ingest Plaid Webhooks
- Balance Endpoint
- Managing Failed Transfers
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
refresh_tokenin your backend database. First, you need the
refresh_tokento refresh the authorization. Second, if you are not storing and updating these data items, you may encounter an issue where the wrong
access_tokenis being utilized, but it in fact has expired or been revoked.
- After the first
access_tokenis generated, we recommend that you attempt to refresh the
access_tokenbefore 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_tokenfor all of your existing tokens by way of a weekly recurring Task or cron job within the ten day lifespan of the
- Store both the
- By persisting a User’s authorization, it means that they’ll only ever have to explicitly authorize with Astra once during the initial onboarding process. In addition, your team will have continuous access to their User profile, which includes all historical data such as the routines and transfers they’ve made, the cards they’ve connected, and more.
- Please read our guide on managing the lifecycle of User’s authorization to learn more.
- 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
- 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-authorize 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
- As part of Astra’s onboarding flow, end-users need to authenticate by entering a US based phone number and a corresponding security code sent via SMS.
- To create the best experience possible, we recommend that you use the
phone_read_onlyparameters. The phone parameter will pre-populate the phone number from the end-user’s UserIntent in the authentication step. The
phone_read_onlyparameter will lock the phone number, making it uneditable. Together these two parameters save the end-user time, and potentially save them from entering in an incorrect phone number.
- Please reference the Request Authorization section to learn more about the
- Are you a Unit Customer? If so, you have the ability to completely bypass our authentication flow using an Astra<>Unit joint solution called “Trusted Authentication”. Contact your Astra representative to learn more.
Calculate Aggregate Inbound Transfer Volumes:
- We recommend that you implement logic which blocks routine requests to Astra if a User’s aggregate inbound daily transfer volume exceeds the daily depository limit with your bank.
- In the event a User exceeds their daily depository limit and creates a transfer via Astra, we will successfully debit (pull) the funds, but we will be unable to credit (push) the funds to the destination account or card. This applies to our Instant Funding and Accelerated ACH solution.
- Note: Astra will not reverse the funds to the source card or account. Astra will attempt to reprocess the credit to the destination card or account the following day when the limit has been reset.
Instant Funding & Instant Disbursements
- Astra provides an out of the box, PCI compliant solution for your business to collect and register external debit cards on behalf of your users.
- We recommend using the
debit_directparameter, as this will immediately direct users to the “Enter Your Card Details” form in Astra’s SDK. This parameter permits users to enter one debit card. After submitting the card details, the user is immediately navigated to the next screen. This is for debit enabled clients only.
- If you do not choose to use the
debit_directparameter, end-users will have the ability to add multiple cards within the same flow.
- Please reference the Request Authorization section to learn more about the
Own the Debit Card Form UI:
- If your business is PCI certified or has a direct integration with a vendor such as VGS or similar, making you PCI compliant, you have the ability to own the UI/UX for connecting an external debit card.
- You’ll need to register your end-users’ cards in Astra’s ecosystem using the POST v1/Cards endpoint and the parameter
added_by_userwill need to be set to true for externally linked debit cards. This parameter defaults to false if not provided.
- Please reference the Cards chapter to learn more about the
Delete Debit Cards:
- We recommend that you enable your users to delete their externally added cards via 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 the issuing bank or not associated with their Astra profile.
Block Routine Requests for Frozen Client-Issued Debit Cards:
- For client-issued debit cards, we recommend that you verify that the card is not frozen prior to sending a Routine request to Astra for an Instant Funding Transfer.
- If the client-issued debit card is determined to be frozen, block the Routine request from being made.
- If the client-issued debit card is frozen and a Routine request is made, the funds will be successfully debited (pulled) from the source card, but they'll be unable to be credited (pushed) to the destination card.
- Note: Astra will not reverse the funds to the source card. Astra will attempt to reprocess the credit to the destination card when it has been determined that the card is no longer frozen.
- 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.
- 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.
- All API requests include a
request-idin 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.
Register Checking Accounts:
- We highly recommend that client-issued checking accounts are registered with Astra via our Create Account by Account and Routing Number endpoint
- By registering end-user checking accounts with Astra, you help us gather more data points that result in better transfer performance, better transfer healing capabilities, and makes it easier to add additional capabilities to your client.
- Please subscribe to our production and sandbox status pages below to keep up to date with status updates:
- Production Status Page: Astra, Inc status
- Sandbox Status Page: Astra, Inc status
- 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 has 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.
Create UserIntents When Users Select an Astra Funding Option:
- We recommend that you implement logic that creates a UserIntent for a User, if one does not already exist, when they explicitly select to use an Astra funding option for the first time.
- That way if the UserIntent had not been created yet for some reason, your system will try to create one when the User is in your application.
- This process can be used for creating UserIntents for new or non-active users who may not have been included in the initial cohort of eligible users when launching an Astra funding option.
Create One-Off UserIntents:
- Occasionally, the need to create a one-off UserIntent will arise. This can occur when you submit a UserIntent to Astra with outdated information, such as phone number, physical address, and or email address.
- For security purposes, it’s recommended that your team submit a new UserIntent with updated information for Users who haven’t authenticated and authorized yet.
Ingest Astra Webhooks:
- We highly recommend that your team listens for and ingest Astra’s Webhooks for Users, Transfers, Routines, and Chargebacks (if applicable). Your team will be notified the moment the status of any of the four 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_tokenis 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_tokenremains 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.
- 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.
Managing 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.
Updated 3 months ago