Documentation/API/Accounts

Account Service

API reference for managing accounts and transactions

VERTEX ENGINE

00

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 by calling the entity endpoint again.

Table of Contents

  1. Create Account
  2. Get Accounts by Entity ID
  3. Get Account Details
  4. Get Transactions
  5. Get Transaction by ID
  6. Transaction Field Reference

1. Create Account

Creates a new banking account for an entity.

Subject: svc.account.<partner_id>.create

Request

{
  "entity_id": "string"  // Required - UUID format
}

Required Fields

  • entity_id - The 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
}

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

{
  "entity_id": "string"  // Required
}

Required Fields

  • entity_id - The 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

{
  "account_id": "string"  // Required
}

Required Fields

  • account_id - The 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

{
  "account_id": "string"  // Required
}

Required Fields

  • account_id - The 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",
      "tx_payment_type": "string",
      "fee": "string",
      "recipient_name": "string",
      "credit": "string",
      "debit": "string",
      "running_balance": "string",
      "verified": boolean
    }
  ]
}

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

{
  "tx_id": "string"  // Required
}

Required Fields

  • tx_id - The 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",
    "tx_payment_type": "string",
    "fee": "string",
    "recipient_name": "string",
    "credit": "string",
    "debit": "string",
    "running_balance": "string",
    "verified": boolean
  }
}

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
ReversedTransaction was reversed/refunded
Previous: UsersNext: Payments