Create Remittance

POST https://sandbox.temboplus.com/remittance

This endpoint allows international money transfer companies to process payments to recipients in Tanzania. It supports disbursement to both mobile money wallets and bank accounts with comprehensive KYC information support.

Headers

Name	Type	Description
x-request-id*	string	UUID that must be unique for each request. Used for idempotency and request tracing.
Authorization*	string	Bearer token for authentication. Format: Bearer <token>

Request Body

Name	Type	Required	Description
paymentDate	string	Yes	Transaction initiation timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Used for compliance tracking and reporting.
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.
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).
partnerReference	string	Yes	Unique transaction identifier from the remitting partner for reconciliation purposes. Must be unique for each transaction.
callbackUrl	string	Yes	Endpoint where our system will send transaction status updates to the remitting partner.
sender	object	Yes	Contains sender's information for KYC and compliance purposes.
receiver	object	Yes	Contains receiver's information.

Sender Object

Name	Type	Required	Description
fullName	string	Yes	Sender's legal name exactly as it appears on identification documents.
nationality	string	Yes	Sender's country of citizenship (ISO country code).
countryCode	string	Yes	Sender's country of residence (ISO country code).
idType	string	Yes	Type of identification document (PASSPORT, NATIONAL_ID, DRIVING_LICENSE, etc.).
idNumber	string	Yes	Identification document number for KYC verification.
idExpiryDate	string	Yes	Expiration date of the identification document (YYYY-MM-DD).
dateOfBirth	string	Yes	Sender's date of birth (YYYY-MM-DD) for compliance verification.
phoneNumber	string	Yes	Sender's contact number with country code (no spaces or special characters).
email	string	Yes	Sender's email address for transaction notifications.
address	string	Yes	Sender's current residential address for compliance records.
sourceOfFundsDeclaration	string	Yes	Declaration of the origin of funds (required for AML compliance).
purposeOfTransaction	string	Yes	Reason for the money transfer (required for compliance reporting).
occupation	string	Yes	Sender's current occupation (required for KYC).
employer	string	Yes	Sender's employer information (required for transactions above certain thresholds).

Receiver Object

Name	Type	Required	Description
fullName	string	Yes	Recipient's full name as registered with their financial service provider.
phoneNumber	string	Yes	Recipient's mobile number with country code (required for mobile money transfers).
email	string	No	Recipient's email for notifications (optional, can be null).
countryCode	string	Yes	Recipient's country code (e.g., TZ for Tanzania).

200 Success

{
  "partnerReference": "HSC8474837-VS83",
  "status": "SUBMITTED",
  "statusCode": "SUBMITTED",
  "statusMessage": "Transaction has been submitted for processing",
  "createdAt": "2025-02-27T10:57:00Z",
  "updatedAt": "2025-02-27T10:57:00Z"
}

400 Validation Error

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "receiverAccount",
      "message": "Invalid mobile number format"
    }
  ]
}

400 Missing Header

{
  "error": "MISSING_HEADER",
  "message": "Required header is missing",
  "details": [
    {
      "field": "x-request-id",
      "message": "This header is required for all API requests"
    }
  ],
  "requestId": null
}

403 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid authorization token",
  "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

429 Too Many Requests

{
  "error": "DUPLICATE_REQUEST",
  "message": "Duplicate partnerReference",
  "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Curl

curl --request POST \
  --url https://sandbox.temboplus.com/remittance \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'x-request-id: 550e8400-e29b-41d4-a716-446655440000' \
  --data '{
  "paymentDate": "2025-02-27T10:56:00Z",
  "senderCurrency": "USD",
  "senderAmount": 100.00,
  "receiverCurrency": "TZS",
  "receiverAmount": 250000.00,
  "exchangeRate": 2500.00,
  "receiverAccount": "255745908755",
  "receiverChannel": "MOBILE",
  "institutionCode": "VODACOM",
  "partnerReference": "HSC8474837-VS83",
  "callbackUrl": "https://partner.example.com/callback",
  "sender": {
    "fullName": "JOHN DOE",
    "nationality": "US",
    "countryCode": "US",
    "idType": "PASSPORT",
    "idNumber": "A12345678",
    "idExpiryDate": "2027-08-30",
    "dateOfBirth": "2002-09-12",
    "phoneNumber": "1234567890",
    "email": "[e-mail]",
    "address": "123 Main Street, New York, USA",
    "sourceOfFundsDeclaration": "Salary",
    "purposeOfTransaction": "Home Support",
    "occupation": "Software Engineer",
    "employer": "Tech Corp Ltd"
  },
  "receiver": {
    "fullName": "AMINA ABBDALLAH HASSAN",
    "phoneNumber": "255712345678",
    "email": null,
    "countryCode": "TZ"
  }
}'

Supported Institutions

Mobile Money Providers (MOBILE channel)

Institution Code	Description
AIRTEL	Airtel Tanzania (Airtel Money)
TIGO	Tigo (Currently Yas) Mobile Money
HALOTEL	Halotel Money

Banks (BANK channel)

Institution Code	Description
ABSA	ABSA BANK TANZANIA LTD
ACCESS	ACCESSBANK TANZANIA LTD
AKIBA	AKIBA COMMERCIAL BANK LTD
AMANA	AMANA BANK LIMITED
AZANIA	AZANIA BANK LIMITED
BANCABC	AFRICAN BANKING CORPORATION TANZANIA LIMITED
BARODA	BANK OF BARODA (TANZANIA) LTD
BOA	BANK OF AFRICA TANZANIA LIMITED
BOI	BANK OF INDIA (TANZANIA) LIMITED
CANARA	CANARA BANK TANZANIA LTD
CITI	CITIBANK TANZANIA LTD
CRDB	CRDB BANK PLC
DASHENG	CHINA DASHENG BANK LIMITED
DCB	DAR ES SALAAM COMMUNITY BANK LTD
DTB	DIAMOND TRUST BANK TANZANIA LTD
ECOBANK	ECOBANK TANZANIA LIMITED
EQUITY	EQUITY BANK TANZANIA LIMITED
EXIM	EXIM BANK (TANZANIA) LTD
FNB	FIRST NATIONAL BANK LIMITED
GTBANK	GUARANTY TRUST BANK (T) LTD
HABIB	HABIB AFRICAN BANK LIMITED
ICB	INTERNATIONAL COMMERCIAL BANK (TANZANIA) LIMITED
IMBANK	I&M BANK LIMITED
KCB	KCB BANK TANZANIA LIMITED
KILIMANJARO	KILIMANJARO CO-OPERATIVE BANK LTD
MAENDELEO	MAENDELEO BANK LTD
MKOMBOZI	MKOMBOZI COMMERCIAL BANK
MWALIMU	MWALIMU COMMERCIAL BANK PLC
MWANGA	MWANGA HAKIKA MICROFINANCE BANK LIMITED
NBC	NATIONAL BANK OF COMMERCE LTD
NCBA	NCBA BANK LIMITED
NMB	NATIONAL MICROFINANCE BANK LIMITED
PBZ	PEOPLE'S BANK OF ZANZIBAR LTD
SCB	STANDARD CHARTERED BANK (T) LIMITED
STANBIC	STANBIC BANK TANZANIA LTD.
TCB	TANZANIA COMMERCIAL BANK PLC
UBA	UNITED BANK FOR AFRICA (T) LTD
UCHUMI	UCHUMI COMMERCIAL BANK (T) LTD
YETU	YETU MICROFINANCE BANK PLC