curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/balance \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "50.00",
"action": "LOAD"
}
'{
"success": true,
"availableBalance": 100,
"transactionId": "txn_3c9a7e1d",
"message": "Card loaded successfully"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"code": "IDEMPOTENT_REQUEST_IN_PROGRESS",
"message": "A request with this Idempotency-Key is already in progress"
}Load or unload card balance
Moves money between the account and its card balance: LOAD adds funds to the card, UNLOAD moves them back to the account. The back office uses this to fund managed (program-funded) cards and to make manual balance corrections.
Only available on programs whose card provider holds a separate card balance. The operation is account-scoped: it moves the account’s balance at the card provider, which exists from account provisioning and can hold funds with no cards issued. There is no card id in the path because there is nothing for one to identify.
curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/balance \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "50.00",
"action": "LOAD"
}
'{
"success": true,
"availableBalance": 100,
"transactionId": "txn_3c9a7e1d",
"message": "Card loaded successfully"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be processed. Check the request parameters and body and try again."
}
}{
"success": false,
"code": "IDEMPOTENT_REQUEST_IN_PROGRESS",
"message": "A request with this Idempotency-Key is already in progress"
}Authorizations
The back-office user's id_token — the ID token, not the access_token. The API rejects access tokens.
Headers
Optional. Makes the movement retry-safe: the key is claimed before the card provider is called, so a retry with the same key returns the original result instead of moving the funds again. Must be a UUID (a non-UUID is a 400), and is scoped to the customer the account belongs to. An idempotencyKey body field is accepted; a header value wins.
Failures split on whether the money could have moved. Rejected before the provider is called (validation, inactive account, insufficient balance) releases the key, so it is immediately reusable. Any other failure — a timeout, a dropped connection, a provider rejection, or an error we do not recognise — pins the claim: every retry returns 409 IDEMPOTENT_REQUEST_IN_PROGRESS, and on that path it is NOT transient. This code is also returned while a first attempt is still running and the two are identical on the wire, so retry with backoff past the 30-second server timeout, then treat the key as pinned; it persists until the movement is reconciled or the key expires (best-effort, at least 48h). Never rotate to a fresh key; that bypasses the protection and loads the card twice.
Path Parameters
The customer's ID.
The account's ID.
Query Parameters
The program the customer/account belongs to. Required on every request.