Skip to content

Read the Prepaid Balance

GET
/balance
curl --request GET \
--url https://api.voltpay.space/v1/balance \
--header 'Authorization: Bearer <token>'

Test mode is free and has no Prepaid Balance, so a gw_test_ key reads state as not_billed.

The Prepaid Balance, the Available Balance and the state.

Media typeapplication/json
object
mode
required
string
Allowed values: live test
state
required

ok covers new Checkouts. low is below the Merchant’s threshold. empty means new live Checkouts are refused. not_billed is Test mode, which is free and has no Prepaid Balance.

string
Allowed values: ok low empty not_billed
prepaid_balance
required

The Merchant’s credit, to one micro-USD. It can go slightly negative, and the next Recharge covers that.

string
/^-?[0-9]+(\.[0-9]+)?$/
held_amount
required

The part of the Prepaid Balance set aside for open Checkouts.

available_balance
required

The Prepaid Balance minus every Hold, so it can be negative. A new live Checkout needs enough of it.

string
/^-?[0-9]+(\.[0-9]+)?$/
low_balance_threshold
required

The Available Balance below which balance.low is sent.

Example

{
"mode": "live",
"state": "ok",
"prepaid_balance": "120.500000",
"held_amount": "0.850000",
"available_balance": "119.650000",
"low_balance_threshold": "20.000000"
}

INVALID_API_KEY: the key is missing, wrong or revoked.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "INVALID_API_KEY",
"message": "The API key is missing, wrong or revoked.",
"request_id": "req_01J9…"
}
}

MERCHANT_SUSPENDED: Staff have suspended the Merchant.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "MERCHANT_SUSPENDED",
"message": "This account is suspended. Contact support.",
"request_id": "req_01J9…"
}
}

RATE_LIMITED: back off, per Retry-After.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Wait for the time in Retry-After, then try again.",
"request_id": "req_01J9…"
}
}
Retry-After
integer
>= 1

Seconds to wait before trying again.

INTERNAL: an unexpected failure. Quote request_id when reporting it.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "INTERNAL",
"message": "Something went wrong on our side. Quote the request id if this continues.",
"request_id": "req_01J9…"
}
}

TRY_AGAIN: a time limit cut the request short and nothing was committed.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "TRY_AGAIN",
"message": "Nothing was committed. Try the request again.",
"request_id": "req_01J9…"
}
}
Retry-After
integer
>= 1

Seconds to wait before trying again.