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)

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

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",
  "oauth_token_issued": false,
  "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.

Note that a new UserIntent should only be created if an end-user is starting from scratch or had originally provided incorrect information.

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"

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

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

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/2024",
    "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

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/2024",
    "first_name": "Sally",
    "last_name": "Smith"
  }'

Response:

{
    "card_company": "Visa",
    "expiration_date": "02/2024",
    "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.

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/2025",
              "id": "0af1d2a5-d7e4-41b8-9ed4-a32750490608",
              "last_four_digits": "1111"
          },
          {
              "card_company": "Visa",
              "expiration_date": "12/2025",
              "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/2025",
    "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 The date the Routine should start processing (timezone is "America/Los_Angeles")
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
created date The date the Routine was created
status string The Routine's status on the platform (see statuses)

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
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)
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
destination_user_id string The ID of the receiving User (p2p only)
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
min_balance float The minimum balance for triggering a 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)

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
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",
      "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",
      "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",
  "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",
      "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",
      "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",
      "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",
"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

Balance Update Webhook and Endpoint

The balance_update webhook type tells Astra to update the balance of an account created through account number and routing number (where there is not a Plaid connection to leverage). This allows your application to utilize more advanced Routines like the refill type.

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

https://url.com

{
  "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)

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. Contact us to generate your Client ID, Client Secret, and Redirect URI by emailing [email protected]
  2. Log into the Sandbox Dashboard to retrieve your keys and URLs
  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: 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