Allocate Account

Creates a new merchant collection account that can receive customer payments. Each account is uniquely assigned to your business 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 legal name of your company (cannot be empty)

• merchantReference* (string) — A unique reference string you generate to identify this account

• tag (string, optional) — Optional account tag, typically assigned during onboarding

Responses

200 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:

• companyName field is empty or missing

• Required fields like reference are not provided

• Invalid JSON syntax in the request body

• Missing Content-Type: application/json header

Error Format:

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

Or with detailed validation information:

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

Resolution

Verify all required fields (companyName, reference) 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 Reference

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

Error Format

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

Resolution Generate a new unique reference string and retry the request.

---

Duplicate Company Name

The company name you're trying to use is already registered in the TemboPlus system. Company names must be unique to prevent confusion and ensure proper account assignment.

Why this happens

• Another merchant has already registered with the same company name

• Your business has previously been registered under this exact name

Error Format

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

Resolution Contact [e-mail] with your business registration details to resolve the naming conflict.

---

No Available Accounts

There are no pre-allocated bank accounts available in your assigned pool. TemboPlus maintains a pool of bank accounts for each merchant, and this pool has been exhausted.

Why this happens

• You have allocated all accounts from your pre-approved 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.