API References

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

Request
{
  "entity_id": "string"  // Required: UUID format
}
FieldTypeRequiredDescription
entity_idstringrequiredThe unique identifier of the entity to create an account for

Response

{
  "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": "2025-01-15T10:30:00Z"  // ISO 8601 timestamp
}
FieldTypeDescription
account_idstringUUID of the newly created account
entity_idstringUUID of the entity
account_numberstringGenerated account number
countrystringAccount country code (e.g., "ZAF", "KEN")
created_atstringISO 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 data
  • 404 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

Request
{
  "entity_id": "string"  // Required
}
FieldTypeRequiredDescription
entity_idstringrequiredThe unique identifier of the entity

Response

{
  "entity_id": "string",
  "accounts": [
    {
      "account_id": "string",
      "account_number": "string",
      "created_at": "2025-01-15T10:30:00Z",  // ISO 8601 timestamp
      "metadata": {}
    }
  ]
}

Notes

  • Accounts are sorted by created_at in 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 data
  • 404 Not Found: Entity not found

3. Get Account Details

Retrieves detailed information for a specific account.

Subject: svc.account.<partner_id>.get_details

Request

Request
{
  "account_id": "string"  // Required
}
FieldTypeRequiredDescription
account_idstringrequiredThe unique identifier of the account

Response

{
  "account_id": "string",
  "account_number": "string",
  "balance": "string",
  "available_balance": "string",
  "metadata": {}
}

Possible Errors

  • 400 Bad Request: Invalid request data
  • 404 Not Found: Account not found

4. Get Transactions

Retrieves all transactions for a specific account.

Subject: svc.account.<partner_id>.list

Request

Request
{
  "account_id": "string"  // Required
}
FieldTypeRequiredDescription
account_idstringrequiredThe unique identifier of the account

Response

{
  "account_id": "string",
  "transactions": [
    {
      "tx_id": "string",
      "parent_tx_id": "string",
      "date": "string",
      "amount": "string",
      "ref": "string",
      "status": "string",
      "tx_sha": "string",
      "user_id": "string",
      "added_by": "string",
      "tx_type": "string",
      "fee": "string",
      "recipient_name": "string",
      "credit": "string",
      "debit": "string",
      "running_balance": "string",
      "verified": boolean,
      "metadata": {                  // Only present for card transactions
        "card_id": "string",
        "merchant_name": "string",
        "merchant_id": "string",
        "mcc": "string",
        "transaction_type": "string"
      }
    }
  ]
}
FieldTypeDescription
tx_idstringUUID of the transaction
parent_tx_idstringFor a Reversal, the tx_id of the original transaction. Otherwise the zero UUID
datestringWhen the transaction was created (RFC 3339)
amountstringFormatted amount with currency, e.g. "R120.50". Negative for money out, e.g. "-R500.00"
refstringTransaction 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
statusstringOne of Pending, Successful or Failed. See Transaction Status
tx_shastringShort hash identifying the transaction
user_idstringUUID of the user who made the transaction. The zero UUID when no user is linked, e.g. for incoming credits
added_bystringName of that user. Blank when no user is linked
tx_typestringWhat kind of transaction this is: EFT, RTC, Internal, Card, Credit or Reversal. See Transaction Type
feestringFee charged on the transaction, e.g. "R0.00"
recipient_namestringFor payments, the beneficiary. For credits and reversals, the account holder, not the payer
creditstringAmount in. R0.00 for money out
debitstringAmount out. R0.00 for money in
running_balancestringAccount balance after this transaction, including fees. Only Successful transactions change it
verifiedbooleanWhether the transaction has been verified
metadataobjectCard 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:

Card transactions response
{
  "account_id": "87e4c1bf-3716-42c2-a9c2-bea8eace7987",
  "transactions": [
    {
      "tx_id": "2dd0dc3a-afd2-4d8c-9046-41d4ab9bce50",
      "parent_tx_id": "00000000-0000-0000-0000-000000000000",
      "date": "2026-09-03T09:12:44.512304118Z",
      "amount": "R120.50",
      "ref": "GREENLEAF GROCERS      SANDTON       ZAF4410093821",
      "status": "Successful",
      "tx_sha": "617b4dcda",
      "user_id": "00000000-0000-0000-0000-000000000000",
      "added_by": " ",
      "tx_type": "Credit",
      "fee": "R0.00",
      "recipient_name": "Example Business (PTY) Ltd",
      "credit": "R120.50",
      "debit": "R0.00",
      "running_balance": "R10,620.50",
      "verified": true,
      "metadata": {  
        "card_id": "54c42aa4-ca51-4a9d-b761-7915911cf1a1",
        "merchant_name": "GREENLEAF GROCERS      SANDTON       ZAF",
        "merchant_id": "M00482917",
        "mcc": "5411",
        "transaction_type": "REF"
      }
    },
    {
      "tx_id": "9345a3ef-1be0-4a9b-b74a-51fb42a21e5a",
      "parent_tx_id": "00000000-0000-0000-0000-000000000000",
      "date": "2026-09-05T17:30:08.203917455Z",
      "amount": "-R500.00",
      "ref": "EXAMPLE BANK ATM  Rosebank Johannesburg Z020417736512",
      "status": "Successful",
      "tx_sha": "b30938e0f",
      "user_id": "74cc65dd-2e2a-4cba-99c5-ac3d6f93ffeb",
      "added_by": "JANE DOE",
      "tx_type": "Card",
      "fee": "R0.00",
      "credit": "R0.00",
      "debit": "-R500.00",
      "running_balance": "R10,120.50",
      "verified": true,
      "metadata": {  
        "card_id": "54c42aa4-ca51-4a9d-b761-7915911cf1a1",
        "merchant_name": "EXAMPLE BANK ATM  Rosebank Johannesburg ZAF",
        "merchant_id": "ATM00000EXB01",
        "mcc": "6011",
        "transaction_type": "CWD"
      }
    }
  ]
}

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 data
  • 404 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

Request
{
  "tx_id": "string"  // Required
}
FieldTypeRequiredDescription
tx_idstringrequiredThe unique identifier of the transaction

Response

{
  "transaction": {
    "tx_id": "string",
    "parent_tx_id": "string",
    "date": "string",
    "amount": "string",
    "ref": "string",
    "status": "string",
    "tx_sha": "string",
    "user_id": "string",
    "added_by": "string",
    "tx_type": "string",
    "fee": "string",
    "recipient_name": "string",
    "credit": "string",
    "debit": "string",
    "verified": boolean,
    "metadata": {                  // Only present for card transactions
      "card_id": "string",
      "merchant_name": "string",
      "merchant_id": "string",
      "mcc": "string",
      "transaction_type": "string"
    }
  }
}

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 data
  • 404 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.

ValueDescription
InvalidInvalid transaction
PendingTransaction initiated but not yet processed
SuccessfulTransaction completed successfully
FailedTransaction 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.

ValueDirectionDescription
EFTOutEFT payment to an account at another bank
RTCOutReal-time clearing (RTC) payment to an account at another bank
InternalOutPayment to another SAVA account. An EFT or RTC payment becomes Internal when the beneficiary account is held at SAVA
CardOutCard purchase or ATM cash withdrawal. See Card Metadata
CreditInMoney received: incoming payments, transfers from other SAVA accounts, and card refunds
ReversalInFunds 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.

FieldTypeDescription
card_idstringUUID of the card used. Matches the card_id returned by the Card Service.
merchant_namestringMerchant name and location as reported by the card network. Omitted if not stored on the transaction.
merchant_idstringMerchant or terminal identifier from the card network. Omitted if not stored on the transaction.
mccstringMerchant 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_typestringCard transaction type code. See Card Transaction Type below. Omitted if not stored on the transaction.

Card Transaction Type (metadata.transaction_type)

ValueDescription
PURPurchase at a merchant
CWDCash withdrawal at an ATM
REFRefund from a merchant back to the card