NAV Navbar
curl html

Introduction

Welcome to the Astra API! You can use our platform to process interbank transfers, create automated routines, or manage virtual bank accounts for your users.

Our API is organized around the REST framework. It accepts and returns JSON-encoded messages and uses standard HTTP response codes.

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 integration related questions, as this will enable us to quickly investigate and provide you with answers.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Feel free to submit any questions about Astra's developer program to [email protected]

Authorization

To send any API request on behalf of an existing User successfully, the header must include an access_token. This section outlines the endpoints and authorization process for a User and your Client application.

The access_token is returned to your Client when you submit a temporary authorization_code to our OAuth server. It should then be included in the Authorization Header (Type: Bearer Token) for requests to the API.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authorization will also fail.

The basic sequence for generating an access_token:

  1. Create a User (if the User doesn't already exist)
  2. Present the User with Astra's OAuth module, which returns an authorization_code
  3. Exchange the authorization_code for an access_token using the token endpoint
  4. Use the access_token in your Authorization Header for API requests for that User

Authorization Endpoints

POST /v1/oauth/token

Authorize a User

Request:

curl -X POST 'https://api.astra.finance/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u your_client_id:your_client_secret \
  -d 'grant_type=authorization_code' \
  -d 'code=your_user_authorization_code' \
  -d 'redirect_uri=your_redirect_uri'

Response:

[
  {
    "access_token": "bsySsXFz0A609jvnJXFmNmT5ntYmGS3YiwEPbuMOTZ",
    "expires_in": 7200,
    "refresh_token": "QdP2qTYLjg42WG9WgLOF6kBZYweY3bKk8L0Cj3xzGkgxTz5J",
    "token_type": "Bearer"
  }
]

Authorize a User and retrieve an access_token.

Endpoint

POST /v1/oauth/token

Parameters

Parameter Data Type Description
client_id string Your Developer Client ID
client_secret string Your Developer Client Secret
grant_type string authorization_code
code string The authorization code your Client received after the User authorized your application
redirect_uri string The redirect URI you want to send Authenticated Users to on success (this must match your Developer Account settings)

Refresh Authorization

Request:

curl -X POST 'https://api.astra.finance/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u your_client_id:your_client_secret \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=your_user_refresh_token' \
  -d 'redirect_uri=your_redirect_uri'

Response:

[
  {
    "access_token": "xkE2kPpwFgJJhfYsXCjgGCoEPdVTua0EulfjX1WJ2i",
    "expires_in": 864000,
    "refresh_token": "TWmOiLImeyPpW7Eda6EKKk2voLGNcqD95neUZmBfcCo5pRza",
    "token_type": "Bearer"
  }
]

Refresh the access_token for a User.

Endpoint

POST /v1/oauth/token

Parameters

Parameter Data Type Description
client_id string Your Developer Client ID
client_secret string Your Developer Client Secret
grant_type string refresh_token
refresh_token string The refresh_token granted with the associated access_token
redirect_uri string The redirect URI for your Client (this must match your Developer Account settings)

Astra's OAuth module handles a variety of authorization flows. In addition to gathering an auth_code, the OAuth module can guide the User through additional verification steps or help the User connect or reconnect a bank account. You may also use optional query strings in the URL to customize the User experience.

OAuth Module URLs

Below is a table outlining all OAuth Module URLs relative to the Object (i.e. UserIntent), the Status of the Object (i.e Approved), and the relevant Action each URL performs (i.e. Collect Authorization). Each URL contains placeholder query string parameters that must be substituted with real values, all of which are located in your Client Developer Dashboard.

Object Status Action OAuth URL
UserIntent Approved Collect Authorization https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id
UserIntent Document Submit Photo ID https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri&user_intent_id=your_user_intent_id
UserIntent Retry Verify Profile https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri&user_intent_id=your_user_intent_id
User Approved Collect Authorization https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code
User Document Submit Photo ID https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri
User Retry Verify Profile https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
User (Business) * Verify Profile https://app.astra.finance/verify/business?client_id=your_client_id&redirect_uri=your_redirect_uri
Account * Link Account https://app.astra.finance/institutions/connect?client_id=your_client_id&redirect_uri=your_redirect_uri
Account Error Reconnect Account https://app.astra.finance/institutions/connect?client_id=your_client_id&redirect_uri=your_redirect_uri
Card * Link Card https://app.astra.finance/cards/connect?client_id=your_client_id&redirect_uri=your_redirect_uri

Request Authorization

https://app.astra.finance/login/oauth/authorize

Example with Query Strings

https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id&phone=5557771234&phone_read_only=true

Parameters

Parameter Required Description
client_id required Your Developer Client ID
redirect_uri required The redirect URI for your Client (this must match your Developer Account settings)
response_type required The type of response after successful authorization (must be code)
user_intent_id optional The ID of the User Intent (when included the User can bypass manually entering profile details)
phone optional The User's phone number, to prefill the phone number field (10 digit format 5557771234)
phone_read_only optional Optionally lock the phone number field (only include if set to true)
state optional A custom query string. Could be used as a parameter to pass through to a redirect URI to better control the UX navigation.
bypass_connect optional Optionally skip the connect accounts screen (only include if set to true)
debit_direct optional Optionally skip the Connect New Debit Card screen and go right to the Enter Your Card Details form. This parameter permits users to enter one debit card. After submitting the card details, the user is immediately navigated to the next screen. For debit enabled clients only. (only include if set to true)

Business Account Verification Flow

Consumer-to-Business and Business-to-Business clients will need to modify their OAuth flow to verify Businesses. Authorizing a business with Astra requires a different set of information from what is required for an individual. Depending on the type of business, additional information will be required. To trigger the business verification flow, you'll need to include the following parameter in your OAuth link: business=true

https://app.astra.finance/verify/business

Example with Query Strings

https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&business=true

Parameters

Parameter Required Description
client_id required Your Developer Client ID
redirect_uri required The redirect URI for your Client (this must match your Developer Account settings)
response_type required The type of response after successful authorization (must be code)
business optional A boolean value. If true, the end-user will be sent through the Business Account Verification flow

User

A User is the data model for the end user of your application.

Users are strongly linked to the Authorization endpoints. Once created, all subsequent requests must include the access_token for the authenticated User.

If an end-user does not have a User profile yet, there are two ways to create a User:

  1. Send the end-user to the OAuth Link found in the developer dashboard
  2. Create the User in the background through our API using a User Intent and then send the end-user to the OAuth Link

For the first option, the Astra OAuth module will collect all necessary profile information and handle the status of the User. This is the simplest integration and does not require your application to send any data via API beforehand.

For the second option, the end-user will only have to verify their email address and authorize your application through the OAuth Link. The URL must include User Intent ID and email as parameters. This option can reduce the number of steps your end-user must take before creating a Routine or Transfer.

User Endpoints

GET /v1/user

GET /v1/user_intent/:id

POST /v1/user_intent

POST /v1/documents/create_upload_url

POST /v1/documents/confirm_upload

POST /v1/request_user_phone_number_update

The User Object

The User Object:

[
  {
    "id": "0239decedaaa5cefa4d173ee839ca37599165219",
    "email": "[email protected]",
    "phone": "+15557771234",
    "first_name": "Edmund",
    "last_name": "Hillary",
    "preferred_first_name": "Ed",
    "preferred_last_name": "Hill",
    "preferred_pronouns": "He/Him",
    "status": "approved"
  }
]
Parameter Data Type Description
id string The unique ID of the User
email string The email address associated with the User profile
phone string The phone number associated with the User profile
first_name string The User's first name
last_name string The User's first name
preferred_first_name string The User's preferred first name
preferred_last_name string The User's preferred last name
status string The User's status on the platform (see statuses)

Get a User profile

Request:

curl 'https://api.astra.finance/v1/user' \
  -H "Content-Type: application/json" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "email": "[email protected]",
  "phone": "+15557771234",
  "first_name": "Edmund",
  "last_name": "Hillary",
  "preferred_first_name": "Ed",
  "preferred_last_name": "Hill",
  "preferred_pronouns": "He/Him",
  "status": "approved"
}

This endpoint retrieves the profile information for a User.

Endpoint

GET /v1/user

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Get a User Intent

Request:

curl 'https://api.astra.finance/v1/user_intent/your_user_intent_id' \
  -u your_client_id:your_client_secret \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Response:

{
  "id": "1a908838d703473ab52e6884c001e447",
  "user_id": "40e61a9e48384c00173ab528d7038847",
  "email": "[email protected]",
  "phone": "+15557771234",
  "first_name": "Edmund",
  "last_name": "Hillary",
  "preferred_first_name": "Ed",
  "preferred_last_name": "Hill",
  "preferred_pronouns": "He/Him",
  "status": "approved"
}

A User Intent manages the lifecycle of the creation of a User, before that User has been fully created. This endpoint retrieves the User Intent details.

Endpoint

GET /v1/user_intent/:id

Parameters

Parameter Data Type Description
client_id string Your Developer Client ID
client_secret string Your Developer Client Secret

Create a UserIntent

Request:

curl -X POST 'https://api.astra.finance/v1/user_intent' \
  -u your_client_id:your_client_secret \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "email": "[email protected]",
    "phone": "+15557771234",
    "first_name": "Edmund",
    "last_name": "Hillary",
    "preferred_first_name": "Ed",
    "preferred_last_name": "Hill",
    "preferred_pronouns": "He/Him",
    "address1": "123 Astra Ave",
    "address2": "Apt 456",
    "city": "Palo Alto",
    "state": "CA",
    "postal_code": "94304",
    "date_of_birth": "1919-07-20",
    "ssn": "9999",
    "ip_address": "your_ip_address"
  }'

Response:

{
  "id": "1a908838d703473ab52e6884c001e447"
}

A User Intent manages the lifecycle of the creation of a User, before that User has been fully created. This endpoint creates a User Intent, starting the process of verifying the end-user's identity in the background.

For managing UserIntents, Astra recommends that once a UserIntent is created, you should store that UserIntent ID with the User record. The UserIntent ID can then be sent as a query string parameter to the Astra OAuth flow. Once your application receives the authorization_code, you can make a call to the GET /v1/user endpoint which will give you a user_id.

Endpoint

POST /v1/user_intent

Parameters

Parameter Data Type Required Example
email string true "[email protected]"
phone string true "+15557771234"
first_name string true "Edmund"
last_name string true "Hillary"
preferred_first_name string false "Ed"
preferred_last_name string false "Hill"
preferred_pronouns string false "He/Him"
address1 string true "123 Astra Ave"
address2 string false "Apt 456" (PO Boxes are not allowed.)
city string true "Palo Alto"
state string true "CA"
postal_code string true "94304"
date_of_birth string true "1919-07-20"
ssn string true "9999" (This can be the full 9-digit SSN or the last four digits. Dashes are not allowed.)
ip_address string true "your_ip_address" (The IP address of the user.)

User Statuses

When retrieving a UserIntent or User, Astra will return a status field to describe the current state.

Status Description
approved The User/UserIntent is in good standing. Only an approved end-user can initiate Routines.
pending The User/UserIntent KYC check is processing. The pending status will typically complete within a few seconds before updating to either approved, retry, document, or rejected.
retry Send the end-user into the Auth flow to provide additional profile details. This is triggered when profile information such as DOB and/or SSN are incorrect. End-users will be sent into retry only once before they are updated to either approved, rejected, or sent into the document flow.
document Send the end-user into the Auth flow to provide a photo ID. This is triggered when profile information such as DOB and/or SSN are incorrect. An end-user will remain in document until their identify can be verified.
suspended The User/UserIntent failed our KYC check or is in breach of our terms of use.
rejected The User/UserIntent failed our KYC check and the end-user has been rejected from registering in our system. If an end-user is rejected before they are converted_to_user, they'll be able to authenticate, but will be unable to authorize. If an end-user is rejected after they are converted_to_user, they'll be able to authorize and connect their bank accounts, but will be unable to initiate Routines.
converted_to_user (UserIntent only) The end-user has finished signing up on Astra and is now converted to a User. It's important to note that once an end-user authenticates, their UserIntent will be converted to a User regardless of their status.

Create Document Upload URL

Request:

curl -X POST `https://api.astra.finance/v1/documents/create_upload_url` \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "document_type": "license",
    "extension": "jpg"
  }'

Response:

[
 {
    "filename": "65867371-5b23-4312-bb7c-872d54119df5.jpg",
    "method": "PUT",
    "id": "0af1d2a5-d7e4-41b8-9ed4-a32750490608",
    "url": "https://storage.googleapis.com/astra.finance/docs/65867371-5b23-4312-bb7c-872d54119df5.jpg?GoogleAccessId=unique_access_id"
  }
]

This endpoint handles the upload of a government-issued ID for users who have the document status and must upload additional documentation to verify their identity. There are three types of acceptable documents: license, ID card, or passport. There are three types of acceptable document extensions: jpg, jpeg, or png. The document must be in color.

Endpoint

POST /v1/documents/create_upload_url

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
document_type string The type of document (license, idCard, passport)
extension string The type of image (jpg,jpeg,png)

Confirm Upload

Request:

curl -X POST `https://api.astra.finance/v1/documents/confirm_upload` \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
   "filename": "65867371-5b23-4312-bb7c-872d54119df5.jpg"
  }'

After successfully uploading the file, you should post a confirmation to this endpoint using the filename id from v1/documents/create_upload_url. If successfully confirmed, Astra will return a successful response (HTTP 200)

Endpoint

POST /v1/documents/confirm_upload

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
filename string The name of the document including the extension type

Request User Phone Number Update

Request:

curl -X POST `https://api.astra.finance/v1/request_user_phone_number_update` \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
   "proposed_phone": "+15558675309"
  }'

This endpoint gives Astra's customers the ability to submit a phone number change request on behalf of a User to Astra, which will be sent through security checks on our end. This ensures that we can safely and securely update a User's phone number and verify that they are the owner.

Endpoint

POST /v1/request_user_phone_number_update

Parameters

Parameter Data Type Description Example
access_token string The authorization token for the User
proposed_phone string The new phone number you would like to associate with the Astra User's profile "+15558675309"

Accounts

Accounts are real world bank accounts connected to Astra by a User.

Account Endpoints

GET /v1/accounts

GET /v1/accounts/:id

POST /v1/accounts

DELETE /v1/accounts/:id

The Account Object

The Account Object:

{
  "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "official_name": "Online Savings",
  "name": "My Savings Account",
  "nickname": "Rainy Day Savings",
  "mask": "9999",
  "institution_name": "Marcus by Goldman Sachs",
  "institution_logo": "base64image",
  "type": "depository",
  "subtype": "savings",
  "current_balance": 1000,
  "available_balance": 1200,
  "last_balance_update_on": "2020-05-15T15:12:04.746260",
  "connection_status": "connected",
}
Parameter Data Type Description
id string The unique ID of the Account
official_name string The official name of the Account from the Institution
name string The name of the Account from the Institution
nickname string The name of the Account defined by the User
mask string The last four digits of the Account number
institution_name string The name of the Institution where the Account is held
institution_logo string The Institution logo in base64 format
type string The category of the Account type (ie. depository)
subtype string The sub category of the Account type (ie. checking)
current_balance float The value of the current balance for the Account
available_balance float The value of the available balance for the Account
last_balance_update_on date The last update for the Account object from the Institution
connection_status string The current status of the account (connected or error)

List Accounts for a User

Request:

curl 'https://api.astra.finance/v1/accounts' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "count": 2,
  "accounts": [
    {
      "id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd",
      "official_name": null,
      "name": "Total Checking",
      "nickname": null,
      "mask": "8899",
      "institution_name": "Chase",
      "institution_logo": "base64image",
      "type": "depository",
      "subtype": "checking",
      "current_balance": 2415.63,
      "available_balance": 2215.25,
      "last_balance_update_on": "2020-09-15T15:12:04.746260",
      "connection_status": "connected",
    },
    {
      "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
      "official_name": "Online Savings",
      "name": "My Savings Account",
      "nickname": "Rainy Day Savings",
      "mask": "9999",
      "institution_name": "Marcus by Goldman Sachs",
      "institution_logo": "base64image",
      "type": "depository",
      "subtype": "savings",
      "current_balance": 1000,
      "available_balance": 1200,
      "last_balance_update_on": "2020-09-14T15:12:04.746260",
      "connection_status": "connected",
    }
  ]
}

Retrieve all Accounts for a User.

Endpoint

GET /v1/accounts

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Get a Specific Account for a User

Request:

curl 'https://api.astra.finance/v1/accounts/your_accout_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "official_name": "Online Savings",
  "name": "My Savings Account",
  "nickname": "Rainy Day Savings",
  "mask": "9999",
  "institution_name": "Marcus by Goldman Sachs",
  "institution_logo": "base64image",
  "type": "depository",
  "subtype": "savings",
  "current_balance": 1000,
  "available_balance": 1200,
  "last_balance_update_on": "2020-09-14T15:12:04.746260",
  "connection_status": "connected",
}

This endpoint retrieves a specific Account for a User based on the Account ID.

Endpoint

GET /v1/accounts/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the Account

Create Account by Account and Routing

Request:

curl -X POST 'https://secure.api.astra.finance/v1/accounts/create' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "institution_id": "your_institution_id",
    "name": "Your Bank",
    "bank_account_type": "checking",
    "account_number": "your_bank_account_number",
    "routing_number": "your_bank_routing_number"
  }'

Response:

{
  "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "official_name": "Online Savings",
  "name": "My Savings Account",
  "mask": "9999",
  "institution_name": "Marcus by Goldman Sachs",
  "institution_logo": "base64image",
  "type": "depository",
  "subtype": "checking",
  "connection_status": "connected",
}

This endpoint will create an Account for a User based on an account and routing number.

Endpoint

POST /v1/accounts/create

Parameters

Parameter Data Type Description
institution_id string The Institution ID given to you by Astra
name string The name for the Account
bank_account_type string The type of bank account (checking or savings)
account_number string The bank account number
routing_number string The bank routing number

Create Account by Account and Routing (deprecated)

Request:

curl -X POST 'https://api.astra.finance/v1/accounts' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "institution_id": "your_institution_id",
    "name": "Your Bank",
    "bank_account_type": "checking",
    "account_number": "your_bank_account_number",
    "routing_number": "your_bank_routing_number"
  }'

Response:

{
  "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "official_name": "Online Savings",
  "name": "My Savings Account",
  "mask": "9999",
  "institution_name": "Marcus by Goldman Sachs",
  "institution_logo": "base64image",
  "type": "depository",
  "subtype": "checking",
  "connection_status": "connected",
}

This endpoint will create an Account for a User based on an account and routing number.

Endpoint

POST /v1/accounts

Parameters

Parameter Data Type Description
institution_id string The Institution ID given to you by Astra
name string The name for the Account
bank_account_type string The type of bank account (checking or savings)
account_number string The bank account number
routing_number string The bank routing number

Create Account by Plaid Processor Token

Request:

curl -X POST 'https://api.astra.finance/v1/accounts/processor_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "processor_token": "your_processor_token"
  }'

Response:

{
  "id": "eq76ZiP4eqw7Tqk8nox5dBSe993dEBqGulDln",
  "institution_id": "your_plaid_access_token_institution_id"
}

Astra and Plaid have partnered to enable you to use your existing Plaid integration to connect bank accounts and leverage Astra's transfer automation capabilities.

To get started, follow the guide from Plaid's API docs. Completing the process will result in the creation of a processor_token.

Sending the processor_token to this endpoint will create an Account for a User within the Astra platform. You can then easily use the resulting account id as the source or destination of a transfer Routine.

Endpoint

POST /v1/accounts

Parameters

Parameter Data Type Description
processor_token string The processor_token received when exchanged for an access_token via Plaid's API
institution_id string The institution_id for your Plaid access_token used for a fallback association to the correct institution (optional).

Delete a Specific Account for a User

Request:

curl -X DELETE 'https://api.astra.finance/v1/accounts/your_account_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \

This endpoint deletes a specific account for a User based on the account ID. The Response will only include a Response Code.

Endpoint

DELETE /v1/accounts/:id

Parameters

Parameter Data Type Description
id string The ID of the specific account to delete.

For Plaid Integrations: If a Plaid access_token is in an error state and the End-User removes the account connection entirely, you'll need to create a new access_token to enable the End-User to connect their account again. This will require you to hit our DELETE /v1/accounts/:id endpoint for the old access_token then re-add the account through our processor token endpoint.

Balance Update Webhook and Endpoint

The Balance Update Endpoint is required for sending outbound ACH transfers from your client, as it enables Astra to fetch the balance of the end-user's account created through account number and routing number via the POST /v1/accounts/create endpoint.

The balance_update webhook type tells Astra to update the balance of this account created through account number and routing number (where there is not a Plaid connection to leverage). This also allows your application to utilize more advanced Routines like the refill type, but is not required for one-time Routines.

Data Lifecycle Overview

  1. An event triggers a change in the balance for your User's account
  2. Your application fires a balance_updated webhook
  3. Astra GETs the balance data from your application by Account ID
  4. If the balance data of the account is the trigger of a Routine or your User's account is the source, Astra will initiate a transfer

Data Lifecycle Details

Step 2: Your application fires a balance_updated webhook

{
  "institution_id": "astra_ins_001", //your institution id  
  "resource_id": "astra_account_id_goes_here",  
  "event_type": "balance_update"
}

Step 3: Astra GETs the balance data from your application by account ID

https://yourapp.com/astra/balance

Astra will need an endpoint to call to get the balance of an account after receiving a balance_update webhook. We recommend the following: * The endpoint should be secure and utilize authentication. Usually a combination of basic auth and JWT (with an expiration) * The endpoint should accept an account_id parameter * The endpoint should return a JSON response with the following payload:

{
  "available_balance": 12345,  
  "current_balance": 12345
}

Notes: * Both available_balance and current_balance are required * Balances should be integers (cents)

Virtual Accounts

Virtual Accounts are virtual partitions (similar to an app container) of an Account. Each Virtual Account is connected to a User's real world bank accounts.

More information on Astra's Virtual Accounts can be found here.

Virtual Account Endpoints

GET /v1/accounts/virtual BETA

GET /v1/accounts/:id/virtual BETA

GET /v1/accounts/virtual/:id BETA

POST /v1/accounts/virtual BETA

PUT /v1/accounts/virtual/:id BETA

DELETE /v1/accounts/virtual/:id BETA

The Virtual Account Object

The Virtual Account Object:

[
  {
    "id": "6958bc62-5c05-4d3f-8258-5ec76a236891",
    "name": "Trip to Hawaii",
    "balance": 1200,
    "goal": "5634387206995968",
    "goal_amount": 2000,
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
  }
]
Parameter Data Type Description
id string The unique ID of the Virtual Account
name string The name given by User of the Virtual Account
balance float The current balance of the Virtual Account
goal string The ID of a Goal associated with the Virtual Account (null if generic partition)
goal_amount float The amount of a Goal associated with the Virtual Account (null if generic partition)
account_id string The ID of the parent Account associated with the Virtual Account

List Virtual Accounts for a User

Request:

curl 'https://api.astra.finance/v1/accounts/virtual' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

[
  {
    "id": "1",
    "name": "Rainy Day",
    "balance": 500,
    "goal": null,
    "goal_amount": null,
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
  },
  {
    "id": "2",
    "name": "Trip to Hawaii",
    "balance": 1200,
    "goal": "5634387206995968",
    "goal_amount": 2000,
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
  },
  {
    "id": "3",
    "name": "Rent",
    "balance": 1200,
    "goal": "3435687206968959",
    "goal_amount": 1350,
    "account_id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd"
  }
]

Retrieve all Virtual Accounts for a User.

Endpoint

GET /v1/accounts/virtual BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

List Virtual Accounts for a User by the parent Account

Request:

curl 'https://api.astra.finance/v1/accounts/your_account_id/virtual' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

[
  {
    "id": "1",
    "name": "Rainy Day",
    "balance": 500,
    "goal": null,
    "goal_amount": null,
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
  },
  {
    "id": "2",
    "name": "Trip to Hawaii",
    "balance": 1200,
    "goal": "5634387206995968",
    "goal_amount": 2000,
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
  }
]

Retrieve all Virtual Accounts for a User linked to a specific parent Account.

Endpoint

GET /v1/accounts/:id/virtual BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the parent Account

Get a Specific Virtual Account for a User

Request:

curl 'https://api.astra.finance/v1/accounts/virtual/your_virtual_account_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

{
  "id": "6958bc62-5c05-4d3f-8258-5ec76a236891",
  "name": "Trip to Hawaii",
  "balance": 1200,
  "goal": "5634387206995968",
  "goal_amount": 2000,
  "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}

This endpoint retrieves a specific Account for a User based on the Virtual Account ID.

Endpoint

GET /v1/accounts/virtual/:id BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the Virtual Account

Create a new Virtual Account

Request:

curl -X POST 'https://api.astra.finance/v1/accounts/virtual' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
    "name": "Trip to Los Angeles",
    "goal_amount": 1600
  }'

Response:

{
  "id": "6958bc62-5c05-4d3f-8258-5ec76a236891",
  "name": "Trip to Los Angeles",
  "balance": 0,
  "goal": "5634387206995968",
  "goal_amount": 1600,
  "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}

This endpoint creates a Virtual Account.

Endpoint

POST /v1/accounts/virtual BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
account_id string The unique ID of the parent Account
name null The name given by User of the Virtual Account

Optional Parameters

Parameter Default Description
goal_amount null The amount of a Goal associated with the Virtual Account

Update a Virtual Account for a User

Request:

curl -X POST 'https://api.astra.finance/v1/accounts/virtual/your_virtual_account_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "name": "Trip to Hawaii",
    "goal_id": "5634387206995968",
    "goal_amount": 1800
  }'

Response:

{
  "id": "6958bc62-5c05-4d3f-8258-5ec76a236891",
  "name": "Trip to Hawaii",
  "balance": 1200,
  "goal": "5634387206995968",
  "goal_amount": 1800,
  "account_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}

This endpoint updates a specific Virtual Account for a User.

Endpoint

PUT /v1/accounts/virtual/:id BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the Virtual Account

Optional Parameters

Parameter Default Description
name null The name given by User of the Virtual Account
goal null The ID of a Goal associated with the Virtual Account (required if updating goal_amount)
goal_amount null The amount of a Goal associated with the Virtual Account

Delete a Virtual Account for a User

Request:

curl -X DELETE 'https://api.astra.finance/v1/accounts/virtual/your_virtual_account_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

This endpoint removes a specific Routine for a User based on the Routine ID. The Response will only include a Response Code.

This endpoint deletes a specific Virtual Account for a User.

Endpoint

DELETE /v1/accounts/virtual/:id BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the Virtual Account

Cards

Cards are real world bank debit cards connected to Astra by a User. There are two ways to create cards in the Astra system: through the OAuth Module (Connect New Debit Card) or directly through our API. Astra is the only API that offers direct card-to-card transfers.

Card Endpoints

POST /v1/cards

GET /v1/cards

GET /v1/cards/:id

DELETE /v1/cards/:id

The Card Object

The Card Object:

[
  {
    "card_number": "4242424242424242",
    "card_security_code": "123",
    "expiration_date": "02/24",
    "first_name": "Sally",
    "last_name": "Smith"
  }
]
Parameter Data Type Description
card_number string The card number
card_security_code string The card security code
expiration_date string The card expiration date
first_name string The card owner's first name
last_name string The card owner's last name
zip code string The zip code associated with the card
added_by_user boolean Set to false for client-issued debit cards. Set to true for externally linked debit cards. Defaults to false if not provided

Create a Card for a User

Request:

curl -X POST 'https://secure.api.astra.finance/v1/cards' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "card_number": "4242424242424242",
    "card_security_code": "123",
    "expiration_date": "02/24",
    "first_name": "Sally",
    "last_name": "Smith"
  }'

Response:

{
    "card_company": "Visa",
    "expiration_date": "02/24",
    "id": "0e241f30-b951-41e3-a89f-31c3a3ed5b2b",
    "last_four_digits": "4242"
}

Cards can be created directly through the API using this PCI-compliant endpoint if the card is issued from your company.

Endpoint

POST /v1/cards

Parameters

Parameter Data Type Description
card_number string The card number the User
card_security_code string The card security code
expiration_date string The card expiration date
first_name string The card owner's first name
last_name string The card owner's last name
zip_code string The zip code associated with the card

Cards can also be created through the OAuth Module by selecting the Connect New Debit Card button. If the card being created is not issued from your company, it must be created through the OAuth module, which is Payment Card Industry (PCI) compliant. Astra is PCI certified.

For Unit customers, please reference their technical documentation below to learn more about enabling card to card payments. Enabling Card to Card Payments with Unit & Astra

URL (OAuth Module)

Production: https://secure.app.astra.finance/cards/connect Sandbox: https://secure.api-sandbox.astra.finance/v1/cards/connect

List Cards for a User

Request:

curl 'https://api.astra.finance/v1/cards' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \

Response:

[
  {
      "cards": [
          {
              "card_company": "Visa",
              "expiration_date": "12/25",
              "id": "0af1d2a5-d7e4-41b8-9ed4-a32750490608",
              "last_four_digits": "1111"
          },
          {
              "card_company": "Visa",
              "expiration_date": "12/25",
              "id": "9c98cafa-be73-4bc8-b5c2-d18726270212",
              "last_four_digits": "5556"
          }
      ],
      "count": 2
  }
]

Retrieve all Debit Cards for a user.

Endpoint

GET /v1/cards

Parameters

Parameter Data Type Description
access_token string The authorization token for the user

URL (OAuth Module)

https://app.astra.finance/cards

Get a Card by an ID

Request:

curl 'https://api.astra.finance/v1/cards/:id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \

Response:

[
  {
    "card_company": "Visa",
    "expiration_date": "12/25",
    "id": "0af1d2a5-d7e4-41b8-9ed4-a32750490608",
    "last_four_digits": "4242"
  }
]

This endpoint retrieves a specific Debit Card for a User based on the unique Card ID.

Endpoint

GET /v1/cards/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the user
id string The unique ID of the Card

Routines and Transfers between Cards

Set up routines and transfers between debit cards, just as you would with ACH Accounts. When transferring between debit cards, the payment_type parameter in the transfer object must be set to debit or else the request will fail. For example, if the payment_type between two debits is set to ach, the transfer will fail. Inversely, if the payment_type between two ACH accounts is set to debit, the transfer will also fail.

Please see the section on The Transfer Object to learn more.

Delete a Card

Request:

curl -X DELETE 'https://api.astra.finance/v1/cards/:id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "id": "your_card_id"
  }'

This endpoint deletes a debit card by way of a card's unique ID. If the card is successfully deleted, you'll receive an HTTP 200 OK response.

Endpoint

DELETE /v1/cards/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the user
id string The ID of the card to delete

Routines

Routines are the logical elements that automatically result in Transfers between Accounts.

More information on Astra's Routine types can be found here.

Routine Endpoints

GET /v1/routines

GET /v1/routines/:id

POST /v1/routines

PUT /v1/routines/:id

DELETE /v1/routines/:id

The Routine Object

The Routine Object:

{
  "id": "5690342099648512",
  "type": "sweep",
  "name": "My Sweep",
  "payment_type": "ach",
  "source_id": "zZ5mrEdWBXtDleJ37zR8i3g8R59WdNioxLW6D",
  "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
  "destination_user_id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "threshold": 1200,
  "start_date": "2020-01-20",
  "preferred_settlement_speed": "T+2",
  "frequency": "monthly",
  "client_correlation_id": "your_unique_id",
  "active": True,
  "status": "active",
  "created": "2020-01-15T15:12:04.746260"
}
Parameter Data Type Description
id string The unique ID of the Routine
type string The type of Routine (one-time, recurring, sweep, etc.)
name string The name given for the Routine
payment_type string The type of payment (ach, debit, ledger)
source_id string The ID of the Source Account
destination_id string The ID of the Destination Account
destination_user_id string The ID of the receiving User (when using a peer to peer transfer)
amount float The amount of the transfer (when explicitly defined like one-time or recurring)
start_date date Optional. The date the Routine should start processing. If not supplied, the start_date will default to the current day (in the Pacific Timezone). Debit start dates cannot be in the future.
preferred_settlement_speed string The requested settlement speed for resulting transfers
frequency string The frequency a repeating Routine should process
threshold float The value for triggering threshold-based Routine (like sweep)
spending string The ID of the Spending Account (for the round-up Routine)
amount_start float The starting amount for incrementing Routines (like 52-week)
amount_increment float The amount to increment each time the Routine runs (like 52-week)
minimum_transaction_threshold float The value for triggering a deposit-based Routine (like percentage-based)
percent_of_transaction float The value for calculating the transfer amount when triggered (like percentage-based)
percent_of_balance float The value for calculating the transfer amount when triggered (like percentage-balance)
client_correlation_id string An optional correlation id that will be added to ACH or Debit Addenda. This will also be included in the Transfer response.
created date The date the Routine was created
status string The Routine's status on the platform (see statuses)
customer_debit_fee_percent_override float Optional parameter for applying a fee to a debit transfer through either an addition on the pull or a subtraction on the push. Contact your Astra admin to configure your clients to have this percentage fee be either additive or subtractive. For debit transfers only. Example amount: 1.25 = 1.25%

List Routines for a User

Request:

curl 'https://api.astra.finance/v1/routines' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "count": 2,
  "routines": [
    {
      "id": "1",
      "type": "recurring",
      "name": "My Recurring Routine",
      "payment_type": "ach",
      "source_id": "source_account_id",
      "destination_id": "destination_account_id",
      "amount": 155.22,
      "start_date": "2020-09-18",
      "preferred_settlement_speed": "T+2",
      "frequency": "bi-weekly",
      "active": True,
      "status": "active",
      "created": "2020-09-15T15:12:04.746260"
    },
    {
      "id": "2",
      "type": "sweep",
      "name": "My Sweep",
      "payment_type": "ach",
      "source_id": "source_account_id",
      "destination_id": "destination_account_id",
      "threshold": 1200,
      "start_date": "2020-09-20",
      "frequency": "monthly",
      "active": True,
      "status": "active",
      "created": "2020-09-15T15:12:04.746260"
    }
  ]
}

Retrieve all Routines for a User.

Endpoint

GET /v1/routines

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Get a Specific Routine for a User

Request:

curl 'https://api.astra.finance/v1/routines/your_routine_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "id": "2",
  "type": "sweep",
  "name": "my_sweep_name",
  "payment_type": "ach",
  "source_id": "source_account_id",
  "destination_id": "destination_account_id",
  "threshold": 1200,
  "start_date": "2020-09-20",
  "preferred_settlement_speed": "T+4",
  "frequency": "monthly",
  "active": True,
  "status": "active",
  "created": "2020-09-15T15:12:04.746260"
}

This endpoint retrieves a specific Routine for a User based on the Routine ID.

Endpoint

GET /v1/routines/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of Routine

Create a new Routine

Request:

curl -X POST 'https://api.astra.finance/v1/routines' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "type": "recurring",
    "name": "My Routine via API",
    "payment_type": "ach",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 20,
    "client_correlation_id": "your_unique_id",
    "start_date": "2020-11-28",
    "frequency": "weekly"
  }'

Response:

{
  "id": "2",
  "type": "recurring",
  "name": "My Routine via API",
  "payment_type": "ach",
  "source_id": "source_account_id",
  "destination_id": "destination_account_id",
  "amount": 20,
  "client_correlation_id": "your_unique_id",
  "start_date": "2020-11-28",
  "preferred_settlement_speed": "T+2",
  "frequency": "weekly",
  "active": True,
  "status": "active",
  "created": "2020-11-28T15:12:04.746260"
}

This endpoint creates a new Routine for a User.

Endpoint

POST /v1/routines

Parameters

Parameter Data Type Description
id string The unique ID of the Routine
type string The type of Routine (one-time, recurring, sweep, etc.)
name string The name given for the Routine
payment_type string The type of payment (ach, debit, ledger)
source_id string The ID of the Source Account
destination_id string The ID of the Destination Account
destination_user_id string The ID of the receiving User (when using a peer to peer transfer)
amount float The amount of the transfer (when explicitly defined like one-time or recurring)
start_date date Optional. The date the Routine should start processing. If not supplied, the start_date will default to the current day (in the Pacific Timezone). Debit start dates cannot be in the future.
preferred_settlement_speed string The requested settlement speed for resulting transfers
frequency string The frequency a repeating Routine should process
threshold float The value for triggering threshold-based Routine (like sweep)
spending string The ID of the Spending Account (for the round-up Routine)
amount_start float The starting amount for incrementing Routines (like 52-week)
amount_increment float The amount to increment each time the Routine runs (like 52-week)
minimum_transaction_threshold float The value for triggering a deposit-based Routine (like percentage-based)
percent_of_transaction float The value for calculating the transfer amount when triggered (like percentage-based)
percent_of_balance float The value for calculating the transfer amount when triggered (like percentage-balance)
client_correlation_id string An optional correlation id that will be added to ACH or Debit Addenda. This will also be included in the Transfer response.
created date The date the Routine was created
status string The Routine's status on the platform (see statuses)
customer_debit_fee_percent_override float Optional parameter for applying a fee to a debit transfer through either an addition on the pull or a subtraction on the push. Contact your Astra admin to configure your clients to have this percentage fee be either additive or subtractive. For debit transfers only. Example amount: 1.25 = 1.25%

Routine Preview

Request:

curl -X POST 'https://api.astra.finance/v1/routines/preview' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "type": "one-time",
    "name": "My Instant Debit Transfer",
    "payment_type": "debit",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 100,
    "customer_debit_fee_percent_override": 1.25,
    "start_date": "2022-06-09"
  }'

Response:

{
    "astra_fee": 0.0,
    "created": "2022-06-09T23:10:09.324930+00:00",
    "customer_fee": 0.0,
    "destination": "036a5fbe-bf1b-40ca-afa9-34ff2f3e5e75",
    "estimated_settlement": "instant",
    "id": "d99bef73-aa85-49e8-b404-5a31d587ffd5",
    "payment_type": "debit",
    "pull_amount": 100.0,
    "push_amount": 100.0,
    "routine_type": "one-time",
    "source": "b0485b34-ac6e-4b78-9606-9e48d237cec6"
}

This endpoint returns a fee structure payload as a response, which provides a preview of what the fee structure will be upon submitting a routine with the same parameters.

Endpoint

POST /v1/routines/preview

Parameters

Parameter Data Type Description
id string The unique ID of the Routine
type string The type of Routine (one-time)
name string The name given for the Routine
payment_type string The type of payment (debit)
source_id string The ID of the Source Account
destination_id string The ID of the Destination Account
amount float The amount of the transfer (when explicitly defined like one-time)
start_date date Optional. The date the Routine should start processing. If not supplied, the start_date will default to the current day (in the Pacific Timezone). Debit start dates cannot be in the future.
customer_debit_fee_percent_override float Optional parameter for applying a fee to a debit transfer through either an addition on the pull or a subtraction on the push. Contact your Astra admin to configure your clients to have this percentage fee be either additive or subtractive. For debit transfers only. Example amount: 1.25 = 1.25%

Update an existing Routine

Request:

curl -X PUT 'https://api.astra.finance/v1/routines/your_routine_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token' \
  --data-raw '{
    "id": "2",
    "name": "My Edited Routine via API",
    "destination_id": "your_destination_id",
    "amount": 21,
    "frequency": "bi-weekly"
  }'

Response:

{
  "id": "2",
  "type": "recurring",
  "name": "My Edited Routine via API",
  "payment_type": "ach",
  "source_id": "source_account_id",
  "destination_id": "new_destination_account_id",
  "amount": 21,
  "start_date": "2020-11-28",
  "frequency": "bi-weekly",
  "active": True,
  "status": "active",
  "created": "2020-11-28T15:12:04.746260"
}

This endpoint updates an existing Routine for a User.

Routine types may not be changed. Any of the non-required parameters below may be updated with this endpoint, provided they are included in the model for that Routine type.

Endpoint

PUT /v1/routines/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of Routine
Parameter Data Type Description
name string The name given for the Routine
payment_type string The type of payment (ach, debit, ledger)
active boolean Whether the routine is active (True) or paused (False). Defaults to True.
source_id string The ID of the Source Account
destination_id string The ID of the Destination Account
amount float The amount of the transfer (when explicitly defined like one-time or recurring)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
preferred_settlement_speed string The requested settlement speed for resulting transfers (optional, can be T+1, T+2, or T+4)
frequency string The frequency a repeating Routine should process
client_correlation_id string An optional correlation id that will be added to ACH Addenda. This will also be included in the Transfer response.
threshold float The value for triggering threshold-based Routine (like sweep)
spending string The ID of the Spending Account (for the round-up Routine)
amount_start float The starting amount for incrementing Routines (like 52-week)
amount_increment float The starting amount for incrementing Routines (like 52-week)
minimum_transaction_threshold float The value for triggering a deposit-based Routine (like percentage-based)
percent_of_transaction float The value for caclulating the transfer amount when using a percent (like percentage-based)
percent_of_balance float The value for calculating the transfer amount when triggered (like percentage-balance)

Delete a Routine for a User

Request:

curl -X DELETE 'https://api.astra.finance/v1/routines/your_routine_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

This endpoint removes a specific Routine for a User based on the Routine ID. The Response will only include a Response Code.

Endpoint

DELETE /v1/routines/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Routine Statuses

When creating/retrieving a Routine, Astra will return a status field to describe the current state.

Status Description
requires_user_verification The user is either in pending, retry, or document state. In order for the routine to run, the user needs to be in approved state.
pending_account_authorization The source or destination bank account has not been authorized for use with transfers yet.
user_suspended User has been suspended. The routine will be blocked from becoming active.
active The routine will run when triggered.
inactive The routine has been paused.
cancelled The routine was cancelled by the user or Astra admin. (only one-time routines)
failed The associated transfer failed, resulting in a failed routine. (only one-time routines)
completed The full scope of the routine has been completed and will not run. (only applies to one-time and fifty-two-week routines)

Transfers

A Transfer is a simple, universal description of the routing of funds between Accounts.

Transfers abstract the complexity of this routing, and may contain one or more children elements that compose the full path between accounts. Transfers are the result of a triggered and successfully processed Routine.

Transfer Endpoints

GET /v1/transfers

GET /v1/transfers/:id

GET /v1/transfers/projected

The Transfer Object

The Transfer Object:

[
  {
    "id": "c25f9148-8c33-4112-a6cd-0263ef428c64",
    "routine_type": "percentage-based",
    "routine_name": "Operating 30",
    "routine_id": "5140799817777152",
    "source_id": "zZ5mrEdWBXtDleJ37zR8i3g8R59WdNioxLW6D",
    "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
    "amount": 1250,
    "payment_type": "ach",
    "initiated": "2020-09-15T15:12:04.746260",
    "updated": "2020-09-16T17:12:02.114524",
    "estimated_clearing_date": "2020-09-17T15:12:04.746260",
    "status": "processed"
  }
]
Parameter Data Type Description
id string The unique ID of the Transfer
routine_type string The type of parent Routine (one-time, recurring, sweep, etc.)
routine_name string The name given for the parent Routine
routine_id string The unique ID for the parent Routine
source_id string The ID of the Source Account
destination_id string The ID of the Destination Account
amount float The amount of the Transfer
payment_type string The type of payment (ach, debit, ledger)
initiated date The date the Transfer started processing
updated date The date the Transfer status was last updated
estimated_clearing_date date The date the Transfer is estimated to clear to the destination account (at the time it is initiated)
status string The status of the Transfer (pending, cancelled, processed, failed)

List Transfers for a User

Request:

curl 'https://api.astra.finance/v1/transfers' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "count": 2,
  "transfers": [
    {
      "id": "1",
      "routine_type": "recurring",
      "routine_name": "Every Friday",
      "routine_id": "5140799817777152",
      "client_correlation_id": "your_routine_client_correlation_id",
      "source_id": "3lzMBjog76t9BDGdVmMehagM3WW9pVcqgL3LB",
      "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
      "amount": 40,
      "payment_type": "ach",
      "initiated": "2020-09-15T15:12:04.746260",
      "updated": "2020-09-16T17:12:02.114524",
      "estimated_clearing_date": "2020-09-17T15:12:04.746260",
      "status": "processed"
    },
    {
      "id": "2",
      "routine_type": "percentage-based",
      "routine_name": "Operating 30",
      "routine_id": "5140799817777157",
      "client_correlation_id": "your_routine_client_correlation_id",
      "source_id": "zZ5mrEdWBXtDleJ37zR8i3g8R59WdNioxLW6D",
      "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
      "amount": 1250,
      "payment_type": "ach",
      "initiated": "2020-09-15T15:14:09.153764",
      "updated": "2020-09-16T17:12:04.845153",
      "estimated_clearing_date": "2020-09-17T15:12:04.746260",
      "status": "pending"
    }
  ]
}

Retrieve all Transfers for a User.

Endpoint

GET /v1/transfers

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
status string Optional. The status of the Transfer (pending, cancelled, processed, failed)
source_id string Optional. The ID of the source account

Get a Specific Transfer for a User

Request:

curl 'https://api.astra.finance/v1/transfers/your_transfer_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "id": "2",
  "routine_type": "percentage-based",
  "routine_name": "Operating 30",
  "routine_id": "5140799817777152",
  "client_correlation_id": "your_routine_client_correlation_id",
  "source_id": "zZ5mrEdWBXtDleJ37zR8i3g8R59WdNioxLW6D",
  "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
  "amount": 1250,
  "payment_type": "ach",
  "initiated": "2020-09-15T15:12:04.746260",
  "updated": "2020-09-16T17:12:02.114524",
  "estimated_clearing_date": "2020-09-17T15:12:04.746260",
  "status": "pending"
}

This endpoint retrieves a specific Transfer for a User based on the Transfer ID.

Endpoint

GET /v1/transfers/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

List Upcoming Transfers for a User

Request:

curl 'https://api.astra.finance/v1/transfers/projected' \
  -H "Content-Type: application/json" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

{
  "count": 3,
  "transfers": [
    {
      "id": "997",
      "routine_type": "recurring",
      "routine_name": "Every Friday",
      "routine_id": "5140799817777152",
      "client_correlation_id": "your_routine_client_correlation_id",
      "source_id": "3lzMBjog76t9BDGdVmMehagM3WW9pVcqgL3LB",
      "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
      "amount": 40,
      "payment_type": "ach",
      "date": "2020-09-12",
    },
      {
      "id": "998",
      "routine_type": "round-up",
      "routine_name": "Save Extra",
      "routine_id": "5140799817778453",
      "client_correlation_id": "your_routine_client_correlation_id",
      "source_id": "3lzMBjog76t9BDGdVmMehagM3WW9pVcqgL3LB",
      "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
      "amount": null,
      "payment_type": "ach",
      "date": "2020-09-14",
    },
    {
      "id": "999",
      "routine_type": "recurring",
      "routine_name": "Every Friday",
      "routine_id": "5140799817777152",
      "client_correlation_id": "your_routine_client_correlation_id",
      "source_id": "3lzMBjog76t9BDGdVmMehagM3WW9pVcqgL3LB",
      "destination_id": "GL8J39APl7iwEza9ANBqTwdNvJQjRyT1blBy8",
      "amount": 40,
      "payment_type": "ach",
      "date": "2020-09-19",
    }
  ]
}

Retrieve all upcoming projected Transfers for a User over the next 30 days. If the parent routine includes a calculation (ie. it is not explicitly defined), the amount paramter will be null.

Endpoint

GET /v1/transfers/projected BETA

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Cancel a Transfer

Request:

curl -X POST 'https://api.astra.finance/v1/transfers/your_transfer_id/cancel`\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \

Response:

{
"id": "476ad10b-6836-ec11-8139-dab70b2f4ba0",
"routine_type": "one-time",
"routine_name": "cancel transfer demo",
"routine_id": "6022238440521728",
"client_correlation_id": "your_routine_client_correlation_id",
"source_id": "1GrZ4mRMK7ixP4bVa5Vvfm8xXA3qn4t5AZPNL",
"destination_id": "LWGl4okNnxs7R8rAdxAwHAX1karVB7iPVlWqA",
"amount": 15.00,
"payment_type": "ach",
"initiated": "2021-10-26T14:21:46.391826",
"updated": "2021-10-26T14:22:44.436261",
"estimated_clearing_date": "2021-10-28T14:21:46.391826",
"status": "cancelled",
}

Cancel a transfer for a user. To cancel a transfer, you must provide the ID of the transfer in the Endpoint URL. When a transfer is successfully canceled, Astra will return a successful response (HTTP 200) and the status of the transfer in the Transfer table will update to "canceled".

Endpoint

POST /v1/transfers/:id/cancel

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The ID of the transfer to cancel

Instant Transfers

Instant Transfers allow Astra customers to immediately transfers funds between two of a User's Debit Cards Accounts.

Push to Debit Endpoints

GET /v1/push-to-debit/accounts

POST /v1/push-to-debit/accounts

GET /v1/push-to-debit/accounts/:id

PUT /v1/push-to-debit/accounts/:id

DELETE /v1/push-to-debit/accounts/:id

List Available Debit Card Accounts for a User

Request:

curl 'https://api.astra.finance/v1/push-to-debit/accounts' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

[
  {
    "id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd",
    "official_name": null,
    "name": "Total Checking",
    "nickname": null,
    "mask": "8899",
    "institution": "Chase",
    "type": "depository",
    "subtype": "checking",
    "current_balance": 2415.63,
    "available_balance": 2215.25,
    "last_balance_update_on": "2020-09-15T15:12:04.746260",
    "routine_ids": ["4881351522123776", "4923506357698560", "5127980636438528"],
    "virtual_account_ids": ["8683462175585486", "5698526709284864"]
  },
  {
    "id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
    "official_name": "Online Savings",
    "name": "My Savings Account",
    "nickname": "Rainy Day Savings",
    "mask": "9999",
    "institution": "Marcus by Goldman Sachs",
    "type": "depository",
    "subtype": "savings",
    "current_balance": 1000,
    "available_balance": 1200,
    "last_balance_update_on": "2020-09-14T15:12:04.746260",
    "routine_ids": ["4881351522123776", "4923506357698560"],
    "virtual_account_ids": ["4883462175588352", "5698526709284864"]
  }
]

Retrieve all available Debit Card Accounts for a User.

Endpoint

GET /v1/push-to-debit/accounts

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Get a Specific Debit Card Account for a User

Request:

curl 'https://api.astra.finance/v1/push-to-debit/accounts/your_account_id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

Response:

[
  {
    "id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd",
    "official_name": null,
    "name": "Total Checking",
    "nickname": null,
    "mask": "8899",
    "institution": "Chase",
    "type": "depository",
    "subtype": "checking",
    "current_balance": 2415.63,
    "available_balance": 2215.25,
    "last_balance_update_on": "2020-09-15T15:12:04.746260",
    "routine_ids": ["4881351522123776", "4923506357698560", "5127980636438528"],
    "virtual_account_ids": ["8683462175585486", "5698526709284864"]
  }
]

This endpoint retrieves a specific Debit Card Account for a User based on the Account ID.

Endpoint

GET /v1/push-to-debit/accounts/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User
id string The unique ID of the Push to Debit Account

Create a new Debit Card Account

Request:

curl -X POST 'https://api.astra.finance/v1/push-to-debit/accounts' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token' \
  --data-raw '{
    "token": "push_to_debit_token_here"
  }'

Response:

{
  "id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd",
  "official_name": null,
  "name": "Total Checking",
  "nickname": null,
  "mask": "8899",
  "institution": "Chase",
  "type": "depository",
  "subtype": "checking",
  "current_balance": 2415.63,
  "available_balance": 2215.25,
  "last_balance_update_on": "2020-09-15T15:12:04.746260",
  "routine_ids": ["4881351522123776", "4923506357698560", "5127980636438528"],
  "virtual_account_ids": ["8683462175585486", "5698526709284864"]
}

This endpoint creates a new Debit Card Account for a User.

Endpoint

POST /v1/push-to-debit/accounts

Parameters

Parameter Data Type Description
token string The Push to Debit token

Delete a Debit Card Account for a User

Request:

curl -X DELETE 'https://api.astra.finance/v1/push-to-debit/accounts/push-to-debit-account-id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_user_access_token'

This endpoint removes a specific Debit Card Account for a User based on the Push to Debit Account ID. The Response will only include a Response Code.

Endpoint

DELETE /v1/push-to-debit/accounts/:id

Parameters

Parameter Data Type Description
access_token string The authorization token for the User

Transactions

Transactions are records of money moving in and out of an Account.

It typically takes about one to five business days for a transaction to move from pending to posted. The pending and posted versions of a transaction may not necessarily share the same details: their name and amount may change.

It's up to the client to store last retrieval date and date ranges already requested. Since transfers may take up to 5 days to post, we recommend setting the start date 5 days earlier than the last retrieval date when requesting transactions.

The Transaction Object

The Transaction Object:

{
  "id": "1bEkPW7wmpSmE1K18X78H8gJ3l3PvpuQNARwK",
  "account_id": "Eb6ARgQlRpUQk7EDx5jbsQRRrwJyzWSX1XGAd",
  "name": "General Quarters Store",
  "merchant_name": "General Quarters",
  "amount": -89.4,
  "date": "2021-05-05",
  "category": "Clothing Store",
  "category_id": "19013000",
  "location_address": "153 S. La Brea Ave.",
  "location_city": "Los Angeles",
  "location_state": "CA",
  "location_store_number": "1",
  "location_zip": "90036",
  "pending": false,
  "pending_transaction_id": "2bEkPW7wmpSmE1K18X78H8gJ3l3PvpuQNARwK"
}
Parameter Data Type Description
id string The unique ID of the Transaction.
account_id string The unique ID of the Transaction's Account.
name string The merchant name or transaction description.
merchant_name string The merchant name extracted from the name field.
amount float The settled value of the transaction. Negative values when money moves out of the account; positive values when money moves in.
date date For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ).
category string The category the Transaction belongs to.
category_id string The category ID the Transaction belongs to.
location_address string The street address where the Transaction occurred.
location_city string The city where the Transaction occurred.
location_state string The state where the Transaction occurred.
location_store_number string The store number where the Transaction occurred.
location_zip string The zip code where the Transaction occurred.
pending boolean When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id string The ID of a posted transaction's associated pending transaction, where applicable.

List Transactions for a User

Retrieve all Transactions for a User.

Request:

curl 'https://api.astra.finance/v1/transactions?date_start=2021-05-28&date_end=2021-06-08' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your_access_token'

Response:

{
  "cursor": "Cs4BChEKBGRhdGUSCQiAwO3Hm4TxAhK0AWoVbX5hc3RyYS1kZWx0YS10ZXN0aW5ncpoBCxIEVXNlciIgMzAwZjA5ZjRjMGQ0NGE1NjgzZTc1ZWIyYTNlODliNzUMCxIKUGxhaWRUb2tlbiIlbmxLZ3c3OTczemlvWGd2RHZrUm1TR1gxWnZybWQ2ZjZ4SkVNZQwLEhBQbGFpZFRyYW5zYWN0aW9uIiVlQW83MUJEQjg1dWVselZ2VldFOGlvTUw0MXJwWlhITUpEeWpnDBgAIAA=",
  "more": true,
  "transactions": [
    {
      "account_id": "enqpPJ5QmlCNkqwbLNWgIdzgLezmemCMJyvlR",
      "amount": 4.22,
      "category": "Credit",
      "date": "2021-05-05",
      "id": "qkm3bjxp8PHgZ4kqlgdRIeaKVKLP4mSJQ5VDv",
      "name": "INTRST PYMNT",
      "pending": false
    },
    {
      "account_id": "DbMpVkGk95f9VZ4m4N3wsvonxegQKXizdZ4Gx",
      "amount": 4.22,
      "category": "Credit",
      "date": "2021-05-05",
      "id": "agM49qGqL5tXp1V3VLZMtokn65z1EvSRnXkVa",
      "name": "INTRST PYMNT",
      "pending": false
    },
    {
      "account_id": "7kJKaVE397HKmBpN1KqjH9jl1EjWEWiN64bKV",
      "amount": -89.4,
      "category": "Restaurants",
      "date": "2021-05-06",
      "id": "kBelxmqj83tVgAzbjVKZfQj5w5MDBefxm38Vv",
      "name": "SparkFun",
      "pending": false
    }
  ]
}

Endpoint

GET /v1/transactions

Parameters

Parameter Data Type Required Description
access_token string true The authorization token for the User
date_start date true The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.
date_end date true The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.
cursor string false Include the cursor returned from the previous response to retrieve the next set of Transactions. The more field in the response will be true if more Transactions are available to pull.
batch_size number false The number of Transactions to be returned. The default is 50.
account_id string false Filter transactions by Account ID.

Errors

The Astra API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Common Errors Responses

Below, you'll find explanations for some common error responses you may encounter while integrating in our Sandbox:

Invalid client_id

This means the client_id for the given API request is incorrect. It’s possible that you or a team member have created more than one Sandbox client and are using the wrong client_id. Alternatively, you may have entered your client_id incorrectly, or you may be using the wrong string altogether. To locate your client_id, visit https://dashboard-sandbox.astra.finance/ and navigate to the Dashboard tab. Your client_id will be located in the Keys section.

The specified user has not authorized this OAuth Client

This occurs when the end-user confirms their SMS code, but they haven’t completed the OAuth flow. Either the User confirmed the SMS code and then abandoned, or they clicked Authorize but the app did not successfully exchange the auth_code for an access_token via API.

P2P transfer not allowed for this source and destination

This means your Sandbox Client is not configured for Peer-to-Peer transfers. Please contact Astra to have this configuration enabled.

Account Already Exists

This means the processor_token for the given account is already registered in our system. In the sandbox environment, processor_tokens all have the same account and routing numbers so you can only connect one checking and one savings if you're using the default plaid configurations. One alternative is to create custom connection profiles in Plaid: https://plaid.com/docs/sandbox/user-custom/

Webhooks

Astra uses webhooks to send programmatic updates about your user's automations. To enable webhooks, please contact an Astra representative.

The webhook URL must be https and have valid SSL certificate. If there is a non-200 response or no response, Astra will retry sending the webhook.

Webhook Verification

Python example of HMAC verification of the Astra-Verification header:

import base64
import hashlib
import hmac
import os


astra_verification_header = webhook_request.headers.get("Astra-Verification")
decoded_astra_verification_header = base64.b64decode(astra_verification_header)

payload = webhook_request.get_data()
client_secret = os.environ.get("ASTRA_CLIENT_SECRET")
hmac_obj = hmac.new(client_secret, json.dumps(payload), digestmod=hashlib.sha256)
hmac_digest = hmac_obj.digest()

if hmac.compare_digest(decoded_astra_verification_header, hmac_digest) is True:
    print("Astra Webhook Verified")
else:
    raise Exception("Astra Webhook not verified!")

All webhooks from the Astra platform include the Astra-Verification header that can be used to verify the validity of a wehook. This header provides a Base64 encoded HMAC hash of the CLIENT_SECRET and the webhook payload using the HMAC-SHA256 hash function.

To verify the authenticity of a webhook, decode the Base64 encoded string and compare this to the HMAC hash computed on your backend server.

User Webhooks

Astra sends webhooks whenever there is a status update for a User or UserIntent.

User Intent Updated

Fired when the status of a UserIntent has changed.

UserIntent Updated Webhook:

{
  "webhook_type": "user_intent_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}
Parameter Data Type Description
webhook_type string user_intent_updated
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User Intent
resource_id string The unique ID of the Resource (UserIntent ID)

User Updated

Fired when the status of a User has changed.

User Updated Webhook:

{
  "webhook_type": "user_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}
Parameter Data Type Description
webhook_type string user_updated
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (User ID)

Routine Webhooks

Astra sends webhooks whenever there is a status update for a Routine.

Routine Updated

Fired when the status of a Routine has changed.

Routine Updated Webhook:

{
  "webhook_type": "routine_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "0239decedaaa5cefa4d173ee839ca37599165219"
}
Parameter Data Type Description
webhook_type string routine_updated
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Routine ID)

Transfer Webhooks

Astra sends webhooks whenever a Transfer is created or the status is updated.

Transfer Created

Fired when the Transfer is created.

Transfer Created Webhook:

{
  "webhook_type": "transfer_created",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "0239decedaaa5cefa4d173ee839ca37599165219"
}
Parameter Data Type Description
webhook_type string transfer_created
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Transfer ID)

Transfer Updated

Fired when the status of a Transfer has changed.

Transfer Updated Webhook:

{
  "webhook_type": "transfer_updated",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "resource_id": "0239decedaaa5cefa4d173ee839ca37599165219"
}
Parameter Data Type Description
webhook_type string transfer_updated
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Transfer ID)

Transaction Webhooks

Astra sends webhooks whenever there are new or removed transactions associated with an account.

Transactions Initial Update

Fired when an accounts initial transaction pull is completed. This will include the most recent 30 days of transactions for a particular account.

Transactions Initial Update Webhook:

{
  "webhook_type": "transactions_initial_update",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}
Parameter Data Type Description
webhook_type string transactions_initial_update
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Account ID)

Transactions Historical Update

Fired when an accounts historical transaction pull is completed. This may include up to 2 years of transactions for a particular account.

Transactions Historical Update Webhook:

{
  "webhook_type": "transactions_historical_update",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}
Parameter Data Type Description
webhook_type string transactions_historical_update
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Account ID)

Transactions Default Update

Fired when new transaction data is available for an Account.

Transactions Default Update Webhook:

{
  "webhook_type": "transactions_default_update",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA"
}
Parameter Data Type Description
webhook_type string transactions_default_update
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Account ID)

Transactions Removed Update

Fired when transaction(s) for an Account are deleted.

Transactions Removed Webhook:

{
  "webhook_type": "transactions_removed",
  "webhook_id": "364f57aa-47dd-461b-8df4-d6388fb2d05e",
  "user_id": "0239decedaaa5cefa4d173ee839ca37599165219",
  "resource_id": "WV9Zwexqw7Tqk8nox5dBSe993dEBqGulDlnNA",
  "removed_transactions": [
    "1bEkPW7wmpSmE1K18X78H8gJ3l3PvpuQNARwK",
    "3yA7QJkvdgTPAplpr4NrHrQ1yDKgV5FwQd6jo"
  ]
}
Parameter Data Type Description
webhook_type string transactions_removed
webhook_id string The unique ID of the webhook event
user_id string The unique ID of the User
resource_id string The unique ID of the Resource (Account ID)
removed_transactions array The list of removed Transaction IDs

Guide: Getting Started

This guide will walk you through the steps to make your first requests to the sandbox API. Calling endpoints in production will follow a similar process but use different URLs.

Overview

Getting started with the Astra API follows a simple, five-step process:

  1. Create your developer account
  2. Get your API keys and OAuth URL
  3. Create a test user profile or use our generic test user profile
  4. Authorize your client with the test user
  5. Make a request to the API with an access_token

Create your developer account

You will need an active developer account to use Astra's sandbox API.

Sign up

  1. If you haven't already, browse to our Sandbox Dashboard
  2. Enter your name, email, and company
  3. Agree to our Developer Policy and Terms of Service
  4. When you click Create Account you will then receive an email that includes a link to sign in (this link will expire)
  5. Open the email we sent you, and follow the link included

You now have an active developer account. You can always log into this dashboard again using your email address and following the emailed link.

Get your API keys and OAuth URL

Once you have a developer account, you will need to generate and use the integration details for your client.

  1. In the Dashboard tab, add your application name and select save. This will generate your application credentials (client_id & client_secret), which will be located beneath the Application section
  2. Below the Keys section, you'll be able to add your Redirect URIs
  3. Make note of these details and store them securely

You may always return to the dashboard to access your keys. To rotate your keys or edit your redirect URI please contact us.

Reference: Google Securing your API keys

Create a test user profile

To create the authorization required to make a request to the Astra API on behalf of an end user, you will need a test user profile. You can follow this process to create one.

Creating a new test user

  1. If you haven't already, browse to our Sandbox Application
  2. Enter your phone number
  3. When you click Continue you will then receive an SMS message that includes a one-time use code
  4. Enter the code you received
  5. Enter your name and email
  6. Agree to our Privacy Policy and Terms of Service
  7. Click Continue
  8. Click the button to Connect Bank Account (you will need at least one connection to simulate real world user details. Test credentials will show up on the screen.)

You now have an active user profile. You can always log into the app again using your phone number. Within the app, you can add or edit your bank connections, see your accounts, and check the verification status of your user profile.

Authorize your client with the test user

The majority of the endpoints in the Astra API require Authorization of your client application by the end user. This process generates the Authorization Code you will exchange for an Access Token.

  1. Browse to the OAuth URL listed in the dashboard
  2. Using your test user profile (from above), log in, then click Authorize
  3. On success, the user will be redirected to the URI associated with your developer account
  4. Capture the authorization_code from the URL
  5. Exchange the authorization_code for an access_token via POST /v1/oauth/token endpoint

Make a request to the API with an Access Token

All endpoints that interact with an end user's Accounts or Routines require an Access Token in the API request header.

  1. Capture the access_token from the authorization step above
  2. Add Authorization: Bearer access_token to the header of a request
  3. Make a request to the API (we recommend the GET /v1/accounts endpoint
  4. A successful request will return the appropriate payload
  5. Congratulations, you are now ready to set up automated Routines and Transfers!

Guide to Astra's SDK

The following guide is meant to address questions regarding how to manage Users and UserIntents of varying statuses relative to the different OAuth flows our SDK provides.

Generally, we recommend that once a User is logged into your application, you handle their profile in the following manner:

If you have already created a UserIntent in Astra

  1. If the UserIntent status is approved, pending, retry, or document:
    1. Send them into the Collect Authorization Flow
    2. Include their UserIntent ID as a query string parameter
    3. Example URL: https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id
  2. If the UserIntent status is converted_to_user
    1. Do you have an active access_token for this User?
      1. If No
        1. Send them into the Collect Authorization Flow
        2. Do not include the UserIntent ID
        3. Example URL: https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code
      2. If Yes
        1. Is the User status retry?
          1. Send them into the Retry flow
          2. Example URL: https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
        2. Is the User status document?
          1. Send them into the Document flow
          2. Example URL: https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri

If a UserIntent does not exist

  1. Create a UserIntent using the Astra API
  2. An end-user must pass our security checks and have an approved status in order to use our services and be allowed on the Platform

FAQ

My User doesn’t have an access_token or their access_token has expired

I have a UserIntent with a status of converted_to_user and no access_token (no authorization), what do I do?

  1. Send the end-user into the Collect Authorization flow (see URL below)
  2. Do not include the UserIntent ID in the URL. Our system will detect their profile upon authentication.
  3. Do not include their User ID in the URL, as this isn’t an allowable query string parameter.
  4. Do not substitute the end-users UserIntent ID with their User ID. Our system will be unable to locate the User’s profile since there will be no such UserIntent record with that ID.
  5. Our SDK will handle the status of the User profile and guide the end-user through the appropriate screens (upload document or retry). The end-user will ultimately reach the authorize screen.
  6. After the end-user authorizes, Astra will redirect the end-user back to your app with an authorization_code, which you can then exchange for an access_token and refresh_token.
  7. Collect Authorization URL: https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code

I have a UserIntent with a status that is approved, pending, retry, or document, and there is no User record. I also don’t have an access_token for this User. What do I do?

  1. Send the end-user into the Collect Authorization flow (see URL below)
  2. You must include the UserIntent ID as a query string parameter in the URL
  3. Our SDK will handle the status of the User profile and guide the end-user through the appropriate screens. For example, if the UserIntent status is retry, our SDK will guide the end-user to the retry screen after they authenticate. Provided that they are approved, they will ultimately reach the authorize screen.
  4. After the end-user authorizes, Astra will redirect back to your app with an authorization_code, which you can then exchange for an access_token and refresh_token.
  5. Collect Authorization URL: https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id

My User has an access_token, but they aren’t approved

I have a User with an access_token, but they are in retry status. What do I do?

  1. Send the end-user into the Retry flow, to verify their profile using the link below:
  2. https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
  3. Note - if your User is a “business” user type, you’ll need to send them into the Business Verify flow below:
  4. https://app.astra.finance/verify/business?client_id=your_client_id&redirect_uri=your_redirect_uri

I have a User with an access_token, but they are in document status. What do I do?

  1. Send the end-user into the Document flow, to verify their profile using the link below:
  2. https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri
  3. Note - this is the same URL for both Personal and Business user types.

I have a User with an access_token, but they are in rejected status. What do I do?

If the end-user is rejected, this means that they did not pass Astra’s KYC and security checks. They are prohibited from using our services. If you feel that this was in error, please contact Astra support.

I have a User with an access_token, but they are in suspended status. What do I do?

If the end-user is suspended, this means that Astra explicitly removed the User from the Astra platform for suspicious or fraudulent activity. If you feel that this was in error, please contact Astra support.

Additional Notes

Race Condition with UserIntent Statuses

Depending on when you send Astra a UserIntent and when you send your end-user into our SDK, you may run up against a race condition, where Astra hasn’t yet returned an updated UserIntent status, and the status is still pending. A User will ultimately be guided from our Authentication flow to our Authorization flow. This is one way in which you can end up with end-users who have UserIntent statuses that are converted_to_user, and User statuses that are retry or document.

To avoid running up against a race condition, we recommend sending Astra a UserIntent the moment your application has gathered the necessary information. We also recommend that if you have existing Users, you batch process all their UserIntents at once, so that their statuses are known before the User ever enters the Astra SDK.

Suggested User Experience for Initializing Astra’s SDK

It’s up to your team to determine how Astra’s SDK is initialized in your application. You may choose to implement triggers based on explicit User interactions, such as a User selecting a “Fund My Account” or “Add New Debit Card” button. Alternatively, you could automatically launch our SDK without explicit User interaction. For example, once the User is logged into your application, you could choose to automatically launch the Collect Authorization flow if you detect that the User’s access_token has expired. Or you could automatically send the User into the Retry flow if you detect that their User status is retry.

Guide: UserIntent / User Statuses and OAuth Module Flows

When a UserIntent is sent to Astra by way of the POST /v1/user_intent endpoint, the UserIntent will yield a status. The majority of pending UserIntents will be automatically approved and the end-user will only need to Authenticate and Authorize in the Astra OAuth Module.

For rejected UserIntents, there is no need to send the end-user into the Astra OAuth Module, as they will be unable to use our services.

Sometimes a UserIntent will yield a document or retry status. This occurs if we cannot fully verify the identity of a User. Most of the time this happens due to an end-user accidentally entering their information incorrectly. When this occurs, an end-user will need to go through the corresponding Document or Retry flows in our OAuth Module. In some cases, an end-user will be sent through both flows. To better illustrate all of the possible scenarios, please refer to the diagram below that outlines a UserIntent passing through the various statuses related to our security checks.

UserIntent Status Flows

UserIntent vs. User Object

Once an end-user authenticates, a User object will be created, their UserIntent will become converted_to_user. The newly created User object will inherit the previous UserIntent status. For example, in the event an end-user Authenticates and Authorizes, but their UserIntent was previously in document, the User object will now have the document status applied to it. This means the end-user will either be redirected to the Document flow automatically or sent through the Document Flow the next time they enter the OAuth Module.

The diagram below depicts an end-user authenticating and their associated UserIntent changinng status as a result.

UserIntent to User Object

OAuth Module Flows

All end-users must to go through the Astra OAuth Module to Authorize your application to make money movements on their behalf via Astra. In most cases, end-users will only need to Authenticate and Authorize, but sometimes they'll need to go through the Document and/or Retry Flows. What does each Astra OAuth Module flow look like? Below is an outline of all the OAuth Module screens an end-user may encounter depending on the status of their UserIntent or User object.

OAuth Module Flows