Allocate Account

Creates a new merchant collection account that can receive customer payments. Each account is uniquely assigned to your merchant and comes with a dedicated bank account number.

Endpoint

POST /account/allocate

Request

Headers

• Content-Type* — Must be application/json

• Authorization* — Bearer token (Bearer YOUR_API_TOKEN)

• x-request-id* — Unique UUID per request for tracing

Body Parameters

• merchantName* (string) —The merchant’s registered legal name. This field must not be empty.

• merchantReference* (string) — A unique identifier assigned to the merchant by the partner. Along with the accountNo, it is included in webhook notifications as an additional identifier, helping the partner determine which merchant a payment belongs to.

• tag*(string) — Identifies the pool of accounts from which an account should be allocated. Check below for more details.

Accounts are limited and are made available in predefined pools. Each pool is associated with a specific tag. When requesting an account, the supplied tag determines which pool TemboPlus should use.

For example, a partner managing two merchants could organize the accounts as follows:

• merchant-a tag → accounts reserved for Merchant A

• merchant-b tag → accounts reserved for Merchant B

This allows the partner to separate and manage account availability for each merchant.

Responses

201 OK

Response Format:

{
  "id": "e8820cc4-a2e1-444c-9f48-ef2f77367e3f",
  "accountName": "TEMBOPLUS COMPANY LIMITED",
  "accountNo": "XXXXXXXXXX",
  "bankId": "ECOBANK",
  "bankName": "ECOBANK TANZANIA",
  "swiftCode": "ECOCTZTZ",
  "tag": "TM"
}

Response Fields:

• id (string) — Unique UUID for the allocated collection account

• accountName (string) — Registered name associated with the collection account

• accountNo (string) — Bank account number assigned for payment collection

• bankId (string) — Short bank identifier

• bankName (string) — Bank name

• swiftCode (string) — SWIFT/BIC code of the bank

• tag (string) — Tag associated with the account

400 BAD REQUEST

This error occurs when the request contains missing or invalid parameters. The API validates all required fields and data formats before processing your request.

Common Causes:

• merchantName field is empty or missing

• Required fields like merchantReference are not provided

• Invalid JSON syntax in the request body

• Missing Content-Type: application/json header

Error Format:

{
  "merchantName": "\"merchantName\" cannot be empty"
}

Or with detailed validation information:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Validation Error",
  "details": {
    "merchantName": "\"merchantName\" is required"
  }
}

Resolution

Verify all required fields (merchantName, merchantReference) are included and properly formatted before sending the request.

401 UNAUTHORIZED

This error indicates authentication failure. The API could not verify your identity using the provided credentials.

Common Causes:

• Missing Authorization header in the request

• Invalid bearer token format (should be Bearer YOUR_TOKEN)

• Expired or revoked API token

• Incorrect API token value

Error Format

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}

Resolution

Ensure your request includes the correct authorization header: Authorization: Bearer YOUR_API_TOKEN

409 CONFLICT

This error occurs when the request conflicts with the current state of a resource or violates system constraints.

---

Duplicate Merchant Reference

You're attempting to use a reference that has already been used for another account allocation. Each reference must be unique across all your account allocations.

Error Format

{
  "message": "DUPLICATE_MERCHANT_REFERENCE",
  "error": "Conflict",
  "statusCode": 409
}

Resolution Generate a new unique reference and retry the request.

---

No Available Accounts

There are currently no bank accounts available in the selected account pool.

Why this happens

• The account pool for this tag has been exhausted. A new account cannot be allocated until additional accounts are added to the pool.

Error Format

{
  "message": "NO_AVAILABLE_ACCOUNTS",
  "error": "Conflict",
  "statusCode": 409
}

Immediate Action Required Contact [e-mail] to request additional accounts be added to your pool. Include your expected usage volume.

For Planning Monitor your account usage regularly and request pool expansions before running out to avoid service interruptions.

500 INTERNAL SERVER ERROR

This error indicates a temporary server-side issue that prevented the request from being processed. These are typically transient problems that resolve automatically.

Common causes:

• Temporary banking system connectivity issues

• Server maintenance or updates in progress

• Third-party service temporary unavailability

Error format

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Something went wrong"
}

Resolution:

• Wait 1-2 minutes and retry the request

• Contact support with your x-request-id if the issue persists beyond 10 minutes

Note: These errors are usually temporary and resolve within a few minutes.