Balances

The /balances endpoint allows you to retrieve account balance details for a particular user or business. You can retrieve balance details for either the general purpose account (GPA) or for merchant-specific accounts (MSAs).

Every user/business, by default, owns a GPA. Users/businesses can also own MSAs if you choose to create them. GPA funds can be spent anywhere, while MSA funds can be spent only at specific merchants.

You can also retrieve transaction and balance information for the program reserve account by way of the /programreserve/balances and /programreserve/transactions endpoints.

Retrieve GPA balances

Action: GET
Endpoint: /balances/{token}

Use this endpoint to return the following general purpose account (GPA) balances for a user or business:

  • Ledger balance – When using standard funding, the funds that are available to spend immediately. When using Just-in-Time (JIT) Funding, authorized funds that are currently on hold, but not yet cleared.
  • Available balance – The ledger balance minus any authorized (but not yet cleared) transactions. Also known as the card holder's purchasing power. If you are using JIT Funding, this balance is usually equal to $0.00.
  • Credit balance – Not currently used.
  • Pending credits – ACH loads that have been accepted, but for which the funding time has not yet elapsed.

The return object includes a link to balances of existing merchant-specific accounts (MSAs).

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The token identifying the user/business whose GPA balances you want to retrieve. Existing user/business token.

Issue GET to /users or /businesses to retrieve user/business tokens.

Sample response body

{
"gpa": {
"currency_code": "USD",
"ledger_balance": 1000,
"available_balance": 990,
"credit_balance": 0,
"pending_credits": 0,
"balances": {
"USD": {
"currency_code": "USD",
"ledger_balance": 1000,
"available_balance": 990,
"credit_balance": 0,
"pending_credits": 0
}
}
},
"links": [
{
"rel": "msas",
"method": "GET",
"href": "/v3/balances/my_user_01/msas"
}
]
}


Retrieve MSA balances

Action: GET
Endpoint: /balances/{token}/msas

Use this endpoint to return the merchant-specific account (MSA) balances for a user or business. See "Retrieve GPA balances" for descriptions of each balance.

This endpoint supports sorting and pagination.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The token identifying the user/business whose MSA balances you want to retrieve. Existing user/business token.

Issue GET to /users or /businesses to retrieve existing user/business tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"currency_code": "USD",
"ledger_balance": 100,
"available_balance": 100,
"credit_balance": 0,
"pending_credits": 0,
"name": "My Campaign 01",
"campaign_token": "my_campaign_01"
}
]
}


Retrieve reserve account balances

Action: GET
Endpoint: /programreserve/balances

Use this endpoint to return balances for your program's reserve account. See "Retrieve GPA balances" for descriptions of each balance.

Sample response body

{
"currency_code": "USD",
"ledger_balance": 10100,
"available_balance": 10100,
"credit_balance": 0,
"pending_credits": 0,
"balances": {
"USD": {
"currency_code": "USD",
"ledger_balance": 10100,
"available_balance": 10100,
"credit_balance": 0,
"pending_credits": 0
}
}


List reserve account transactions

Action: GET
Endpoint: /programreserve/transactions

Use this endpoint to return a list of credits and debits to your program's reserve account.

This endpoint supports sorting and pagination.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"created_time": "2017-05-10T21:52:18Z",
"last_modified_time": "2017-05-10T21:52:18Z",
"token": "my_deposit_02",
"amount": 120,
"currency_code": "USD",
"memo": "my_memo",
"tags": "my, tags",
"transaction_token": "154",
"type": "CREDIT"
},
{
"created_time": "2017-05-10T21:51:28Z",
"last_modified_time": "2017-05-10T21:51:28Z",
"token": "my_deposit_01",
"amount": 100,
"currency_code": "USD",
"memo": "my_memo",
"tags": "my, tags",
"transaction_token": "153",
"type": "CREDIT"
}
]
}