Index

For Users

General:

• Persist Authorization
• Manual Re-authorization
• Authentication
• Trusted Authentication
• Calculate Aggregate Inbound Transfer Volumes

Instant Funding & Instant Disbursements:

• debit_direct
• Own the Debit Card Form UI (via VGS or similar)
• Delete Debit Cards
• Block Routine Requests for Frozen Client-Issued Debit Cards
• Messaging for Cards Not Pull or Push Enabled

Accelerated ACH:

• Cancel Transfers
• Delete Routines

For Developers

General:

• Store Request IDs
• Review Guide to Astra’s SDK
• Register Checking Accounts
• Status Updates
• Selectively Block Users From Astra’s Services

UserIntents:

• Managing UserIntents
• Create UserIntents When Users Select an Astra Funding Option
• Create One-Off UserIntents
• Do Not Send Rejected Users to Astra

Webhooks:

• Managing UserIntents
• Ingest Astra Webhooks
• Ingest Plaid Webhooks

Accelerated ACH:

• Balance Endpoint
• Managing Failed Transfers

For Users

General

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.
• 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.

Manual Re-authorization:

• 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-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

Authentication:

• 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 and phone_read_only parameters. The phone parameter will pre-populate the phone number from the end-user’s UserIntent in the authentication step. The phone_read_only parameter 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 phone and phone_read_only parameters.

Trusted Authentication:

• 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

Debit Direct:

• 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_direct parameter, 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_direct parameter, 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 debit_direct parameter.

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_user will 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 debit_direct parameter.

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.

Messaging for Cards Not Pull or Push Enabled:

• Occasionally, Users will connect debit cards with product limitations that have been put in place by the issuing bank, such as disabled pull or push capabilities. This information is returned to Astra by way of the issuing bank via the debit networks once the User has submitted their card details for card authorization. This information is then returned to your client via Astra’s API and through your Astra Dashboard.
• In the event a card is not pull or push enabled, we recommend that you inform the User in your own brand language (prior to the User Initiating a Routine) that the User’s card cannot have funds pulled (debited) or pushed (credited) to it and that they will need connect another debit card in order to send or receive funds.

Accelerated ACH

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.

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.

For Developers

General

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.

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.

Status Pages:

• 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

Selectively Block Users From Astra’s Services:

• If your business determines that a User is misusing or abusing a feature of your product, you should design a means to block that User from continuing to use Astra’s services. Users that misuse or abuse your product may not necessarily qualify for suspension on Astra’s end

UserIntents

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 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.

Do Not Send Rejected Users to Astra:

• If a UserIntent results in a rejected status, it means that the User did not pass our high-resolution security check and as a result, they are prohibited from using our services.
• If your product offers multiple funding or payout methods, we recommend that you guide rejected Users to use alternative payment methods rather than sending them into Astra’s SDK.
• If a rejected User is sent through Astra’s SDK, they will be informed that they are prohibited from using Astra’s services.

Webhooks

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_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.

Accelerated ACH

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.

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.