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.

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]

.

Authentication

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

Authentication Endpoints

POST /v1/oauth/token

Authenticate 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": 864000,
    "refresh_token": "QdP2qTYLjg42WG9WgLOF6kBZYweY3bKk8L0Cj3xzGkgxTz5J",
    "token_type": "Bearer"
  }
]

Authenticate 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 Authentication

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

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)

Connect / Reconnect a Bank Account

https://app.astra.finance/institutions/connect

Example with Query Strings

https://app.astra.finance/institutions/connect?client_id=your_client_id&redirect_uri=your_redirect_uri

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)

Submit Additional Verification Details

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

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

Submit Photo ID

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

User

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

Users are strongly linked to the Authentication 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 authentication 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",
  "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 User Intent

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.

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"
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.
pending The User/UserIntent is KYC check is processing.
retry Send the end-user into the Auth flow to provide additional profile details.
document Send the end-user into the Auth flow to provide a photo ID.
suspended The User/UserIntent failed our KYC check and the user has been suspended.
rejected The User/UserIntent failed our KYC check and the end-user has been rejected from registering in our system.
converted_to_user (UserIntent only) The end-user has finished signing up on Astra and is now converted to a User.

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, png, tif, or pdf. The document must be in color.

Endpoint

POST /v1/documents/create_upload_url

Parameters

Parameter Data Type Description
access_token string The authentication token for the User
document_type string The type of document (license, ID card, passport)
extension string The type of image (jpg,jpeg,png,tif,pdf)

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

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

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 authentication 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 authentication 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 authentication 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 authentication 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 authentication 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 authentication 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)

https://app.astra.finance/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 authentication 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 authentication 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 succesfully deleted, you'll receive an HTTP 200 OK response.

Endpoint

DELETE /v1/cards/:id

Parameters

Parameter Data Type Description
access_token string The authentication 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 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 authentication 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 authentication 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 authentication 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 authentication 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.
funding_source_not_created 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 authentication token for the User

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

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 up to 15 times.

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 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 integratoin 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 authentication 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 Authentication: 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: Routines

Quick Transfer

Move money between two authorized accounts in just a few clicks.

Request Body:

[
  {
    "type": "one-time",
    "name": "My Quick Transfer",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 20,
    "start_date": "2020-10-29"
  }
]

In Practice:

To create a Quick Transfer, a User needs to select both a Source Account and a Destination Account, as well as define the amount of the Transfer. The amount of the Transfer will be automatically be capped by the User’s transfer limit. This Routine will start immediately, checking the balance of the Source Account before initiating the Transfer to ensure that no accounts are overdrawn.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (one-time)
amount float The amount of the transfer

One Time Transfer

Move money between two authorized accounts on a specific date.

Request Body:

[
  {
    "type": "one-time",
    "name": "My One Time Transfer",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 20,
    "start_date": "2020-10-29"
  }
]

In Practice:

Similar to a Quick Transfer, a User can select a One Time Transfer, specifying the amount that they would like to transfer, where the Transfer should be deposited, and when it should start. Once the scheduled time arrives, the Routine will run, checking the balance of the Source Account before initiating the Transfer to ensure that no accounts are overdrawn.

Like all Routines, it can be Paused (or Activated again) before the resulting Transfer has been initiated. At this point, it can be Deleted as well, where it will never process a Transfer.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (one-time)
amount float The amount of the transfer
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")

Recurring Transfer

Move a specified amount of money from one authorized Account to another authorized Account on a recurring basis starting on a specific date.

Request Body:

[
  {
    "type": "recurring",
    "name": "My Recurring Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 20,
    "start_date": "2020-10-29",
    "frequency": "monthly"
  }
]

In Practice:

When a User creates a Recurring Transfer, they must define the amount that they want to transfer and then the frequency the Routine should run. Once created, the Routine will run at the prescribed interval, checking the balance of the Source Account before initiating the Transfer to ensure that no accounts are overdrawn.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even when the time interval is triggered. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (recurring)
amount float The amount of the transfer
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
frequency string The frequency a repeating Routine should process (weekly, bi-weekly, or monthly)

Sweep Transfer

Send all funds above an established threshold for a given Authorized Account to another Authorized Account on a recurring basis starting on a specific date.

Request Body:

[
  {
    "type": "sweep",
    "name": "My Sweep Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "min_balance": 100,
    "start_date": "2020-10-29",
    "frequency": "bi-weekly"
  }
]

In Practice:

When a User creates a Sweep Transfer, they must define the maximum amount that they want in the Source Account and then the frequency the Routine should run. Once created, the Routine will run at the prescribed interval, checking the balance of the Source Account, calculating the amount that needs to be moved, then initiating a Transfer.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even when the time interval is triggered. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (sweep)
min_balance float The value for triggering threshold-based Routine (like sweep)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
frequency string The frequency a repeating Routine should process (weekly, bi-weekly, or monthly)

Percentage Deposit Transfer

Send a set percentage of funds from one Account into another Account whenever a deposit occurs above a certain minimum threshold.

Request Body:

[
  {
    "type": "percentage-based",
    "name": "My Percentage-based Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "percent_of_transaction": 33,
    "minimum_transaction_threshold": 50,
    "start_date": "2020-10-29"
  }
]

In Practice:

When a User creates a Percentage Deposit Transfer, they must define a Source Account, a Destination Account, and a start date for the Routine. The User also defines the percentage used to calculate the Transfer amount and the deposit minimum amount - the threshold for when the Transfer should be triggered. Once created, the Routine will be active, monitoring the Source Account for qualifying deposits (those above the deposit minimum amount). If a deposit lands in the Source Account above the established minimum, Astra will calculate the amount of the Transfer and notify the user that the Transfer will be initiated the next day.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even between the time the notification is sent and the following day. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (percentage-based)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
minimum_transaction_threshold float The value for triggering a deposit-based transfer
percent_of_transaction float The value for calculating the transfer amount when triggered

Percentage Balance Transfer

Send a set percentage of funds from one Account balance into another Account on a recurring schedule.

Request Body:

[
  {
    "type": "percentage-balance",
    "name": "My Percentage Balance Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "percent_of_balance": 25,
    "start_date": "2020-10-29",
    "frequency": "weekly"
  }
]

In Practice:

When a User creates a Percentage Balance Transfer, they must define a Source Account, a Destination Account, and a start date for the Routine. The User also defines the percentage used to calculate the Transfer amount and the frequency with which it should process. Once created, the Routine will run at the prescribed interval, checking the balance of the Source Account, calculating the amount that needs to be moved, then initiating a Transfer.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even between the time the notification is sent and the following day. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (percentage-balance)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
percent_of_balance float The value for calculating the transfer amount when triggered
frequency string The frequency a repeating Routine should process (weekly, bi-weekly, or monthly)

Refill Transfer

Refill a Destination Account from a Source Account when the Destination Account balance goes below a given threshold.

Request Body:

[
  {
    "type": "refill",
    "name": "My Refill Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount": 100,
    "threshold": 200,
    "start_date": "2020-10-29"
  }
]

In Practice:

When a User creates a Refill Transfer, they must define the balance threshold for the Destination Account and the amount to transfer. They must also define a Source Account, a Destination Account, and a start date for the Routine. Once created, the Routine will monitor the Destination Account and if the value of that Account balance drops below the threshold, it will initiate a Transfer of the given amount.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even when the time interval is triggered. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (refill)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
amount float The amount of the transfer
threshold float The value for triggering the Routine

Round Up Transfer

Round all recent debit transactions for an Account up to the nearest dollar, sum those values, then transfer that amount from a Source Account to a Destination Account.

Request Body:

[
  {
    "type": "round-up",
    "name": "My Round Up Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "spending_id": "your_spending_id",
    "start_date": "2020-10-29"
  }
]

In Practice:

When a User creates a Round Up Transfer, they must define the Spending, Source, and Destination accounts that they would like to use (Spending and Source may be the same Account, but Spending may also be a different Account – even a credit card). They also select the start date for the Routine which will dictate the day of the week on which this Routine will run in the future. For simplicity, the frequency of this Routine is fixed at Weekly and can not be adjusted. Once created, the Routine will run weekly, checking the balance of the Source Account before initiating the Transfer to ensure that no accounts are overdrawn. If the total of the Round Ups for the week is less than $1.00 no automated transfer will occur.

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even when the time interval is triggered. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (round-up)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
spending_id string The ID of the Spending Account

52 Week Challenge

Transfer funds on a weekly basis from one authorized Account to another, increasing the amount of the Transfer by a fixed amount (between $1 and $5) every week for a calendar year.

Request Body:

[
  {
    "type": "fifty-two-week",
    "name": "My 52 Week Routine",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "amount_start": 10,
    "amount_increment": 2,
    "start_date": "2020-10-29"
  }
]

In Practice:

When a User creates a 52 Week Challenge Transfer Routine, they must define the Source and Destination accounts, the start date and the amount that they want that routine to increase by on a weekly basis. Once created, the Routine will initiate a Transfer for the first week using the initial amount. The following week, the routine will create a new Transfer from the Source to the Destination Account for a new amount which is the initial amount plus the amount of the selected increase (week 1 = $5, week 2 = $10, week 3 = $15…).

Like all Routines, it can be Paused (or Activated again). When Paused, it will not create a new Transfer even when the time interval is triggered. It can be Deleted as well, where it will no longer run again and will be removed from the active Routines list.

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (fifty-two-week)
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")
amount_start float The starting amount for the first transfer ($1-$5)
amount_increment float The amount to increment each time the Routine runs ($1-$5)

Peer-to-Peer Transfer

Move money between two authorized accounts, from one authorized User to another.

Request Body:

[
  {
    "type": "one-time",
    "name": "My P2P Transfer",
    "source_id": "your_source_id",
    "destination_id": "your_destination_id",
    "destination_user_id": "your_id_for_the_receiving_user",
    "amount": 20,
    "start_date": "2020-10-29"
  }
]

In Practice:

Transferring funds between two different Users is almost exactly like a One Time Transfer Routine; however, the request body includes an additional parameter that defines the User that will receive the funds. The parameters that differentiate the Sending User and Receiving User are as follows:

Sending User:

Receiving User:

Routine Specific Parameters Required:

Parameter Data Type Description
type string The type of Routine (one-time)
amount float The amount of the transfer
destination_user_id string The ID of the Receiving User
start_date date The date the Routine should start processing (timezone is "America/Los_Angeles")

Guide: Managing Authorization Lifecycle

The following guide presents information on the end-user authorization lifecycle and best practices for how to manage that authorization over time.

Authorization Overview

In order to process transfers through Astra for an end-user in your application, you must collect an authorization. The resulting access_token becomes the authorization you use to make requests to Astra's API. The basic sequence and overview of each component are below.

Sequence

  1. Pre-register the end-user's profile using a UserIntent (optional)
  2. Present the Astra OAuth module for the end-user completed by clicking "Authorize" – this generates and returns a time-sensitive authorization code
  3. Exchange that code for an access_token using the /oauth/token endpoint
  4. Use the access_token as the authentication to make a request to get Accounts, create Routines, etc.

Please refer to the Authentication chapter to learn more.

Below is an overview of the key components to Authenticating a user:

Authorization Code (code):

Access Token (access_token):

Refresh Token (refresh_token):

Best Practices to Persist Authentication

As a best practice, we recommend that you store both the access_token and refresh_token in your backend database. First, you need the refresh_token to refresh the authorization. Second, if you are not storing and updating these data items, you may encounter an issue where the wrong access_token is being utilized, but it in fact has expired or been revoked.

After the first access_token is generated, we recommend that you attempt to refresh the access_token before subsequent API requests. In your backend business logic, we recommend wrapping the request in a try/except method to complete the refresh and catch exceptions.

Additionally, we recommend that you obtain a new refresh_token for all of your existing tokens by way of a weekly recurring Task or cron job within the ten day lifespan of the refresh_token.

Guide: Testing in the Sandbox Environment

This guide demonstrates how to create Accounts and Users / UserIntents with specific states so that you can test a wide range of scenarios that an end-user may encounter.

Connecting a Bank Account via Plaid

If you are using Astra's direct or managed integration with Plaid, you can guide the end-user to connect a bank account through Plaid Link.

After the authorization step, the OAuth module will provide you with a screen for connecting bank accounts. Select the "Connect New Bank" button and continue to select a bank from list of available options. For this example, we'll use Chase. You'll be prompted to enter your account user name and password. Enter the following test credentials:

For additional test cases per institution, including Multi-factor Authentication please refer to Plaid's Sandbox Test Credentials.

Testing User/UserIntent States

When Astra processes a User/UserIntent profile for security and KYC assessment, a resulting User Status for the User/UserIntent will be applied. To test these scenarios, you can use the following options for the User/UserIntent details (phone, first_name, ip_address, etc.)

Phone Number

Scenario 01: Approved

Scenario 02: Approved (but only enabled for T+4 transfers)

Scenario 03: Rejected

First Name

Scenario 01: Approved

Scenario 02: Retry

Scenario 03: Document

IP Address

Scenario 01: Approved

Scenario 02: Rejected

Document Submission

As a part of Astra's KYC process, certain Users / UserIntents may be placed in a document status, requiring the submission of a government-issued ID. Accepted forms of identification include licenses, ID cards, and passports. Below, you'll find example license documents for triggering approved or failed states for document uploads. To learn more about document uploads, please refer to the chapter on Users and reference the Documents section.

Sample Document Approved Image

test-document-upload-success.png

Approved

Sample Document Rejected Image

test-document-upload-fail.png

Failed