Account Service
API reference for managing accounts and transactions.
The first account is automatically created for business entities upon successful KYB verification and for personal entities upon successful KYC verification. Additional accounts can be created using the Create Account endpoint.
1. Create Account
Creates a new banking account for a business entity after the first account has been automatically created.
Subject: svc.account.<partner_id>.create
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | The unique identifier of the entity to create an account for |
Response
| Field | Type | Description |
|---|---|---|
account_id | string | UUID of the newly created account |
entity_id | string | UUID of the entity |
account_number | string | Generated account number |
country | string | Account country code (e.g., "ZAF", "KEN") |
created_at | string | ISO 8601 timestamp |
Notes
- The entity must have completed KYB (Know Your Business) verification for business entities
- Account numbers are automatically allocated from the available pool
- The country is determined from the entity's registered country or the configured default
Possible Errors
400 Bad Request: Invalid request data404 Not Found: Entity not found
2. Get Accounts by Entity ID
Retrieves all accounts for a specific entity.
Subject: svc.account.<partner_id>.get_by_entity
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | The unique identifier of the entity |
Response
Notes
- Accounts are sorted by
created_atin ascending order (oldest → newest) - To get the most recently created account, use the last item in the array
- Empty array returned if entity has no accounts
Possible Errors
400 Bad Request: Invalid request data404 Not Found: Entity not found
3. Get Account Details
Retrieves detailed information for a specific account.
Subject: svc.account.<partner_id>.get_details
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | The unique identifier of the account |
Response
Possible Errors
400 Bad Request: Invalid request data404 Not Found: Account not found
4. Get Transactions
Retrieves all transactions for a specific account.
Subject: svc.account.<partner_id>.list
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | The unique identifier of the account |
Response
| Field | Type | Description |
|---|---|---|
tx_id | string | UUID of the transaction |
parent_tx_id | string | For a Reversal, the tx_id of the original transaction. Otherwise the zero UUID |
date | string | When the transaction was created (RFC 3339) |
amount | string | Formatted amount with currency, e.g. "R120.50". Negative for money out, e.g. "-R500.00" |
ref | string | Transaction reference. For money in (Credit), this is the payer's reference: the reference the payer entered when they paid you. For payments you send, your own reference (own_ref), not the reference shown to the recipient. For card transactions, the merchant descriptor |
status | string | One of Pending, Successful or Failed. See Transaction Status |
tx_sha | string | Short hash identifying the transaction |
user_id | string | UUID of the user who made the transaction. The zero UUID when no user is linked, e.g. for incoming credits |
added_by | string | Name of that user. Blank when no user is linked |
tx_type | string | What kind of transaction this is: EFT, RTC, Internal, Card, Credit or Reversal. See Transaction Type |
fee | string | Fee charged on the transaction, e.g. "R0.00" |
recipient_name | string | For payments, the beneficiary. For credits and reversals, the account holder, not the payer |
credit | string | Amount in. R0.00 for money out |
debit | string | Amount out. R0.00 for money in |
running_balance | string | Account balance after this transaction, including fees. Only Successful transactions change it |
verified | boolean | Whether the transaction has been verified |
metadata | object | Card and merchant details. Only present for card transactions. See Card Metadata |
Fields with no value are left out of the response, so not every transaction carries every field. Transactions are returned newest first, and Failed transactions drop out of the list 25 hours after they were created.
Card transactions
Card transactions come back in this same list, with an extra metadata block (highlighted above) that identifies the card and merchant: card_id, merchant_name, merchant_id, mcc and transaction_type. To show a single card's activity, filter on metadata.card_id. See Card Metadata for when the block appears.
Card transaction example
An account with card activity returns card transactions alongside its other transactions. Below, a refund to the card and an ATM withdrawal:
The refund has tx_type: "Credit" but still carries metadata, because the block depends on the transaction having a card, not on tx_type.
Possible Errors
400 Bad Request: Invalid request data404 Not Found: Account not found
5. Get Transaction by ID
Retrieves a single transaction by its ID.
Subject: svc.account.<partner_id>.get_transaction
Request
| Field | Type | Required | Description |
|---|---|---|---|
tx_id | string | required | The unique identifier of the transaction |
Response
The transaction has the same fields as in Get Transactions, including card metadata, with one exception: running_balance is not returned here. Use the list endpoint if you need the balance after each transaction. For a card transaction, the response looks like one entry from the card transaction example, wrapped in transaction and without running_balance.
Possible Errors
400 Bad Request: Invalid request data404 Not Found: Transaction not found or partner doesn't own it
6. Transaction Field Reference
Transaction Status (status)
Indicates the current state of the transaction.
| Value | Description |
|---|---|
Invalid | Invalid transaction |
Pending | Transaction initiated but not yet processed |
Successful | Transaction completed successfully |
Failed | Transaction failed to complete |
Transaction Type (tx_type)
Says what kind of transaction it is. Use it together with credit and debit (or the sign of amount) to tell money in from money out.
| Value | Direction | Description |
|---|---|---|
EFT | Out | EFT payment to an account at another bank |
RTC | Out | Real-time clearing (RTC) payment to an account at another bank |
Internal | Out | Payment to another SAVA account. An EFT or RTC payment becomes Internal when the beneficiary account is held at SAVA |
Card | Out | Card purchase or ATM cash withdrawal. See Card Metadata |
Credit | In | Money received: incoming payments, transfers from other SAVA accounts, and card refunds |
Reversal | In | Funds returned when an outgoing payment is reversed. parent_tx_id points at the original payment |
A card refund is a Credit, not a Card, but still carries card metadata. Fees are not separate transactions: they are shown in the fee field of the transaction they belong to. Treat any other value as reserved and handle it without failing.
Card Metadata (metadata)
Identifies the card and merchant behind a card transaction. The block is included only when the transaction is linked to a card (it has a valid card_id), whatever its tx_type. Transactions without a card leave it out entirely.
| Field | Type | Description |
|---|---|---|
card_id | string | UUID of the card used. Matches the card_id returned by the Card Service. |
merchant_name | string | Merchant name and location as reported by the card network. Omitted if not stored on the transaction. |
merchant_id | string | Merchant or terminal identifier from the card network. Omitted if not stored on the transaction. |
mcc | string | Merchant Category Code, a 4-digit ISO 18245 code (e.g., "5411" for grocery stores, "6011" for ATM cash). Omitted if not stored on the transaction. |
transaction_type | string | Card transaction type code. See Card Transaction Type below. Omitted if not stored on the transaction. |
Card Transaction Type (metadata.transaction_type)
| Value | Description |
|---|---|
PUR | Purchase at a merchant |
CWD | Cash withdrawal at an ATM |
REF | Refund from a merchant back to the card |