> For the complete documentation index, see [llms.txt](https://tembo.gitbook.io/tembo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tembo.gitbook.io/tembo/momo-collection-and-payout-api/api-reference/payout/initiate-remittance.md).

# Initiate Remittance

### 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.

{% hint style="warning" %}
The `POST /payment/remittance` and `GET /payment/institutions` endpoints are only available in the **live environment**. Sandbox access is currently not supported.
{% endhint %}

### 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)

```json
{
  "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": "johndoe@example.com",
    "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* <mark style="color:red;">`*`</mark> *are required)*

#### Transaction Metadata

* **`paymentDate`**<mark style="color:red;">\*</mark>: ISO 8601 timestamp of when the payment was initiated
* **`partnerReference`**<mark style="color:red;">\*</mark>: Unique reference from the remittance partner
* **`callbackUrl`**<mark style="color:red;">\*</mark>: HTTPS URL to receive asynchronous status updates
* **`description`**<mark style="color:red;">\*</mark>: Transaction description/narration for the recipient

#### Financial Details

* **`senderCurrency`**<mark style="color:red;">\*</mark>: ISO 4217 code (e.g., USD, EUR)
* **`senderAmount`**<mark style="color:red;">\*</mark>: Amount in sender’s currency
* **`receiverCurrency`**<mark style="color:red;">\*</mark>: Currency code for the recipient (currently only `TZS`)
* **`receiverAmount`**<mark style="color:red;">\*</mark>: Amount in TZS (integer, ≥1000)
* **`exchangeRate`**<mark style="color:red;">\*</mark>: Exchange rate used for currency conversion

#### Destination Details

* **`receiverChannel`**<mark style="color:red;">\*</mark>: Payment channel type (`MOBILE` or `BANK`)
* **`institutionCode`**<mark style="color:red;">\*</mark>: Institution identifier (mobile operator or bank). Must be obtained from the **`GET /payment/institutions`** endpoint
* **`receiverAccount`**<mark style="color:red;">\*</mark>: Recipient account number (mobile number or bank account)

#### Sender KYC Information

* **`fullName`**<mark style="color:red;">\*</mark>: Legal name (2-100 characters)
* **`nationality`**<mark style="color:red;">\*</mark>: ISO country code (e.g., US)
* **`countryCode`**<mark style="color:red;">\*</mark>: Country of residence (ISO alpha-2)
* **`idType`**<mark style="color:red;">\*</mark>: `PASSPORT`, `NATIONAL_ID`, or `DRIVING_LICENSE`
* **`idNumber`**<mark style="color:red;">\*</mark>: Identification document number
* **`idExpiryDate`**: Expiration date of the identification document (ISO date format, YYYY-MM-DD)
* **`dateOfBirth`**<mark style="color:red;">\*</mark>: Date of birth (ISO date format, YYYY-MM-DD)
* **`phoneNumber`**<mark style="color:red;">\*</mark>: Contact phone number
* **`email`**: Sender's email address
* **`address`**<mark style="color:red;">\*</mark>: Sender's physical address
* **`sourceOfFundsDeclaration`**<mark style="color:red;">\*</mark>: Source of funds being transferred (e.g., Salary, Business)
* **`purposeOfTransaction`**<mark style="color:red;">\*</mark>: Purpose of the money transfer (e.g., Family Support, Education)
* **`occupation`**: Sender's occupation
* **`employer`**: Sender's employer name

#### Receiver Information

* **`fullName`**<mark style="color:red;">\*</mark>: Legal name (2-100 characters)
* **`phoneNumber`**<mark style="color:red;">\*</mark>: Recipient’s phone number (Must be in the format `255XXXXXXXXX`)
* **`email`**: Receiver's email address
* **`countryCode`**<mark style="color:red;">\*</mark>: Must be `TZ`

### Example Responses

#### Remittance

<details>

<summary><code>200</code> SUCCESS</summary>

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

</details>

#### Supported Institutions

<details>

<summary><code>200</code> SUCCESS</summary>

```json
[
  { "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
]
```

</details>