# Create Remittance

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>  | string | UUID that must be unique for each request. Used for idempotency and request tracing. |
| Authorization<mark style="color:red;">\*</mark> | 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).                                  |

{% tabs %}
{% tab title="200 Success" %}
```json
{
  "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"
}
```
{% endtab %}

{% tab title="400 Validation Error" %}
```json
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "receiverAccount",
      "message": "Invalid mobile number format"
    }
  ]
}
```
{% endtab %}

{% tab title="400 Missing Header" %}
```json
{
  "error": "MISSING_HEADER",
  "message": "Required header is missing",
  "details": [
    {
      "field": "x-request-id",
      "message": "This header is required for all API requests"
    }
  ],
  "requestId": null
}
```
{% endtab %}

{% tab title="403 Unauthorized" %}
```json
{
  "error": "UNAUTHORIZED",
  "message": "Invalid authorization token",
  "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
{% endtab %}

{% tab title="429 Too Many Requests" %}
```json
{
  "error": "DUPLICATE_REQUEST",
  "message": "Duplicate partnerReference",
  "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}
```shell
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": "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"
  }
}'
```
{% endtab %}
{% endtabs %}

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