Remittance

Use this endpoint to initiate remittance transfers to beneficiaries in Tanzania via Mobile Money wallets or local bank accounts.

Endpoints

• Send Remittance POST /payment/remittance Submit a new remittance transaction request.

• Get Supported Institutions GET /payment/institutions Retrieve the list of supported mobile money operators and banks.

The POST /payment/remittance and GET /payment/institutions endpoints are only available in the live environment. Sandbox access is currently not supported.

Authentication

Requests must include the following headers:

• x-request-id — Unique request identifier (string, UUID recommended)

• x-account-id — Vendor account ID (string)

• x-secret-key — Vendor secret key (string)

Request Payload (Remittance)

{
  "paymentDate": "2025-02-27T10:56:00Z",
  "partnerReference": "HSC8474837-VS83",
  "callbackUrl": "https://partner.example.com/callback",
  "description": "Money transfer for family support",
  "senderCurrency": "USD",
  "senderAmount": 100.00,
  "receiverCurrency": "TZS",
  "receiverAmount": 250000.00,
  "exchangeRate": 2500.00,
  "receiverChannel": "MOBILE",
  "institutionCode": "VODACOM",
  "receiverAccount": "255745908755",
  "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"
  }
}

Field Descriptions

(Fields marked with an asterisk * are required)

Transaction Metadata

• paymentDate*: ISO 8601 timestamp of when the payment was initiated

• partnerReference*: Unique reference from the remittance partner

• callbackUrl*: HTTPS URL to receive asynchronous status updates

• description*: Transaction description/narration for the recipient

Financial Details

• senderCurrency*: ISO 4217 code (e.g., USD, EUR)

• senderAmount*: Amount in sender’s currency

• receiverCurrency*: Currency code for the recipient (currently only TZS)

• receiverAmount*: Amount in TZS (integer, ≥1000)

• exchangeRate*: Exchange rate used for currency conversion

Destination Details

• receiverChannel*: Payment channel type (MOBILE or BANK)

• institutionCode*: Institution identifier (mobile operator or bank). Must be obtained from the GET /payment/institutions endpoint

• receiverAccount*: Recipient account number (mobile number or bank account)

Sender KYC Information

• fullName*: Legal name (2-100 characters)

• nationality*: ISO country code (e.g., US)

• countryCode*: Country of residence (ISO alpha-2)

• idType*: PASSPORT, NATIONAL_ID, or DRIVING_LICENSE

• idNumber*: Identification document number

• idExpiryDate: Expiration date of the identification document (ISO date format, YYYY-MM-DD)

• dateOfBirth*: Date of birth (ISO date format, YYYY-MM-DD)

• phoneNumber*: Contact phone number

• email: Sender's email address

• address*: Sender's physical address

• sourceOfFundsDeclaration*: Source of funds being transferred (e.g., Salary, Business)

• purposeOfTransaction*: Purpose of the money transfer (e.g., Family Support, Education)

• occupation: Sender's occupation

• employer: Sender's employer name

Receiver Information

• fullName*: Legal name (2-100 characters)

• phoneNumber*: Recipient’s phone number (Must be in the format 255XXXXXXXXX)

• email: Receiver's email address

• countryCode*: Must be TZ

Example Responses

Remittance

200 SUCCESS

{
    "statusCode": "PENDING_ACK",
    "transactionRef": "7d9c1a44-b98f-4f7a-9b4b-0f3e62d18c7e",
    "transactionId": "TXN-20251020-89345"
}

Supported Institutions

200 SUCCESS

[
  { "code": "VODACOM", "name": "Vodacom Mobile Money", "type": "MOBILE" },
  { "code": "TIGO", "name": "Tigo Mobile Money", "type": "MOBILE" },
  { "code": "AIRTEL", "name": "Airtel Mobile Money", "type": "MOBILE" },
  { "code": "HALOTEL", "name": "Halotel Mobile Money", "type": "MOBILE" },
  { "code": "CRDB", "name": "CRDB Bank PLC", "type": "BANK", "bic": "CORUTZTZ" },
  { "code": "PBZ", "name": "People's Bank of Zanzibar Ltd", "type": "BANK", "bic": "PBZATZTZ" }
  // … additional banks and operators
]