API Reference

Balance Update Webhook and Endpoint

Balance Update Webhook and Endpoint

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

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

📘

We recommend authenticating the endpoint using two keys (one private (provided by you), one public (provided by Astra) and encoding the keys using HMAC-SHA256 (hex). Astra will provide the public key and the HMAC-generated key signature in the request headers like so (--header "Astra-Key-Signature: < encoded key signature >" --header "Astra-Public-Key: < a custom public key provided by Astra >"). You should provide the “Astra-Private-Key” and an account ID for testing in sandbox.

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

Sandbox: https://api-sandbox.astra.finance/v1/webhook/customer_event
Production: https://api.astra.finance/v1/webhook/customer_event

Webhook Payload:

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

📘

  • Both available_balance and current_balance are required
  • Balances should be integers (cents)
{
  "available_balance": 12345,  
  "current_balance": 12345
}