API Overview

This page provides technical details about the TemboPlus Remittance API that are applicable across all endpoints.

Common Headers

All API requests require the following headers:

Header	Required	Description
x-request-id	Yes	UUID that must be unique for each request. Used for idempotency and request tracing.
Authorization	Yes	Bearer token for authentication. Format: Bearer <token>

Note: Your authentication token will be provided during the onboarding process.

HTTP Status Codes

The API uses the following HTTP status codes:

Status Code	Description
200	Request successful
400	Validation error - The request payload contains invalid data or required headers are missing
403	Unauthorized - Invalid authorization token or token is missing
404	Not Found - Remittance with provided partner reference could not be found
429	Too Many Requests - Duplicate partnerReference or request ID
500	Server Error - An unexpected error occurred on the server

Error Response Format

When an error occurs, the API returns a consistent error format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": [
    {
      "field": "fieldName",
      "message": "Specific error for this field"
    }
  ],
  "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

The details array is included for validation errors to provide specific information about which fields failed validation.

Transaction Status Codes

The API uses the following status codes to indicate the current state of a transaction:

Status	Status Code	Description
CREATED	CREATED	Transaction has been created in the system but not yet submitted to the provider
SUBMITTED	SUBMITTED	Transaction has been submitted to the provider for processing
WAITING_ACK	WAITING_ACK	Transaction is awaiting acknowledgment from the provider
COMPLETED	PAYMENT_SUCCESS	Transaction has been successfully processed
FAILED	PAYMENT_FAILED	Transaction failed to process (general failure)
FAILED	INSUFFICIENT_BALANCE	Transaction failed due to insufficient balance
FAILED	PROVIDER_FAILURE	Transaction failed due to an issue with the provider
FAILED	INVALID_ACCOUNT	Transaction failed because the provided receiverAccount is invalid or not found
REVERSED	REVERSED	Transaction was processed but later reversed
CANCELED	PAYMENT_CANCELED	Transaction was canceled before processing was completed

Field Descriptions

Transaction Identification Fields

Field	Type	Required	Description
id	String	N/A	Unique system-generated identifier for the transaction. Returned in responses only.
transactionId	String	N/A	Alias for 'id'. Used in callback notifications.
partnerId	String	N/A	Identifier for the remitting partner integrating with our service.
partnerReference	String	Yes	Unique transaction identifier from the remitting partner for reconciliation purposes. Must be unique for each transaction.
institutionReference	String	N/A	Reference number provided by the receiving financial institution or mobile network operator. Returned in callbacks and status responses.
receiptNumber	String	N/A	Receipt number for successful transactions, can be shared with recipients as proof of payment.

Transaction Details

Field	Type	Required	Description
paymentDate	String	Yes	Transaction initiation timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Used for compliance tracking and reporting.
transactionDate	String	N/A	The timestamp when the transaction was processed by the receiving institution. Returned in responses only.
senderCurrency	String	Yes	ISO currency code of funds from the remitting partner (e.g., USD).
senderAmount	Number	Yes	Amount debited from the remitting partner in sender's currency.
receiverCurrency	String	Yes	ISO currency code for local disbursement (e.g., TZS for Tanzanian Shilling).
receiverAmount	Number	Yes	Amount to be disbursed to the recipient in local currency.
exchangeRate	Number	Yes	Conversion rate applied between sender and receiver currencies.
transactionFee	Number	N/A	Fee charged for processing the transaction in receiver's currency. Returned in responses only.
transactionAmount	Number	N/A	Total amount including the principal and fee in receiver's currency. Returned in responses only.

Delivery Information

Field	Type	Required	Description
receiverAccount	String	Yes	Account identifier for fund disbursement - must be recipient's mobile phone number (for MOBILE channel) or bank account number (for BANK channel).
receiverChannel	String	Yes	Disbursement channel type: MOBILE (mobile money) or BANK (bank transfer).
institutionCode	String	Yes	Financial institution or mobile network operator code (e.g., VODACOM, TIGO, CRDB). See the complete list of all supported institutions in the relevant endpoint documentation.
callbackUrl	String	Yes	Endpoint where our system will send transaction status updates to the remitting partner.

Status Information

Field	Type	Required	Description
status	String	N/A	Current transaction status.
statusCode	String	N/A	Detailed status code.
statusMessage	String	N/A	Human-readable description of the current transaction status.

Timestamps

Field	Type	Required	Description
createdAt	String	N/A	Timestamp when the transaction was created in our system.
updatedAt	String	N/A	Timestamp when the transaction was last updated.
completedAt	String	N/A	Timestamp when the transaction reached a terminal state (COMPLETED, FAILED, REVERSED, CANCELED).

Idempotency

The API implements idempotency to prevent duplicate transactions. This is achieved using the x-request-id header and the partnerReference field:

1. x-request-id: When the same request ID is used within a short time window (typically 24 hours), the API will return the same response as the original request without processing a new transaction.

2. partnerReference: This must be unique for each transaction. If you attempt to create a new transaction with a partnerReference that has already been used, the API will return a 429 error with the message "Duplicate partnerReference".