# Remittance

For remittance companies, that is licensed international money transfer operators (IMTOs): pay out remittances to beneficiaries' bank accounts with the sender and beneficiary details that regulators require.

## When to use it

Use remittance instead of [Create a transfer](api:createSingleTransfer) when the money comes from an individual sender abroad and you must record who sent it. A remittance always pays from your own business's account; it can't be sent on behalf of a customer.

## Before you start

- `MG_BASE_URL`, `MG_API_KEY` and `MG_ACCOUNT_NUMBER` (an account number of your source account, from [List accounts](api:listAccounts)) are set, as in the [Quickstart](../01-get-started/03-quickstart.md).
- **NGN remittances** are paid from a remittance collection account that Multigate sets up for your business. Ask your Multigate contact before you go live. Without it, NGN remittances are accepted and then fail.
- Fund the source account for the amount plus the fee.
- Check the beneficiary's account with [Look up an account name](api:nameEnquiry). A remittance doesn't check it for you.
- Your API user needs the *initiate payment* or *approve payment* permission.

## How it works

```mermaid
sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Bank as Beneficiary bank
    You->>MG: POST /transfer/name-enquiry (beneficiary account)
    MG-->>You: Account name
    You->>MG: POST /transfer/remittance (sender, beneficiary, uniqueRequestId)
    MG-->>You: 200, data.status pending, pending_approval or processing
    MG->>Bank: Payment
    Bank-->>MG: Result
    MG-)You: transfer / transfer_completed or transfer_failed
```

A remittance follows the same rules as a payout: balance check, fees, screening, your approval rules, the same [statuses](05-payouts.md#transfer-statuses) and the same webhooks. The differences:

| | Remittance | Transfer |
|---|---|---|
| Sender details | Required (`sender.firstName`, `sender.lastName`, more recommended) | None |
| Beneficiary check and saving | Not checked, not saved | Looked up and saved |
| On behalf of a customer | No | Yes, with `onBehalfOf` |
| Large NGN amounts | Refused above the per-payment maximum | Split into several transfers |
| Supporting documents | Can't be sent, so third-party USD remittances are refused | `assets` |
| Response | Nested under `data` | Top level |
| Emails | Only "Transaction Declined" | "Transfer Notification" too |

## Send a remittance

Generate a `uniqueRequestId` (unique across Multigate, with your own prefix) and store it before you call. Then send the remittance:

```bash
export MG_REQUEST_ID="acme_rm_$(uuidgen | tr 'A-Z' 'a-z')"
curl -s -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/remittance" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "uniqueRequestId": "$MG_REQUEST_ID",
    "sourceAccountNumber": "$MG_ACCOUNT_NUMBER",
    "currencyIso3Code": "NGN",
    "amount": 180000,
    "narration": "Family support Oct",
    "sender": {
      "firstName": "John", "lastName": "Mensah",
      "emailAddress": "john.mensah@example.com", "phoneNumber": "+447700900123",
      "address": "10 High Street", "city": "London", "countryIso3Code": "GBR"
    },
    "beneficiary": {
      "firstName": "Ama", "lastName": "Mensah",
      "accountName": "Ama Mensah", "accountNumber": "0123456789",
      "bankBicOrCode": "058", "bankName": "Guaranty Trust Bank", "countryIso3Code": "NGA"
    }
}
EOF
```

```json
{
  "message": "Successful",
  "data": {
    "transactionId": "PMT-261010-170000903311",
    "uniqueRequestId": "acme_rm_5c2e8f10-7a4b-4d3e-9f21-6b0c1d2e3f4a",
    "status": "processing",
    "amount": "180000.00",
    "currencyIso3Code": "NGN",
    "sourceAccountNumber": "1029384756",
    "narration": "Family support Oct",
    "sender": { "firstName": "John", "lastName": "Mensah", "countryIso3Code": "GBR" },
    "beneficiary": { "accountName": "Ama Mensah", "accountNumber": "0123456789", "bankBicOrCode": "058", "countryIso3Code": "NGA" }
  }
}
```

The remittance is nested under **`data`**, unlike single transfers. `failureReason` appears when `status` is `failed`. Store `data.transactionId` with your `uniqueRequestId`, then follow [Payouts › After you send](05-payouts.md#after-you-send): the webhooks, polling and timeout handling are the same.

- **Required:** `uniqueRequestId`, `sourceAccountNumber`, `currencyIso3Code`, `amount`, `narration`, `sender.firstName`, `sender.lastName`, `beneficiary.accountNumber`, `beneficiary.accountName`, `beneficiary.bankBicOrCode`, `beneficiary.countryIso3Code`.
- **Send all the sender details you hold** (address, phone, email, country, and BVN for Nigerian senders). They're used for compliance screening.
- **Beneficiary fields** are limited to those in [Initiate a remittance](api:createRemittance). Others, such as `address` (use `addressLine1`) or `bankCountryIso3Code`, are silently dropped.
- **Narration** is shortened to 36 characters. When Multigate sends the payment to the bank, it adds its own `transactionId` after your narration (`Family support Oct PMT-…`), so every payout can be matched to the bank's records during reconciliation. Some banks show only the start of a long narration, so put what the beneficiary must see first.
- **Track it** with [Get a remittance](api:getRemittance) by `transactionId` or `uniqueRequestId`, or with [Find transfers](api:listTransfers).

## Statuses

| Status | Final | Webhook | Meaning |
|---|---|---|---|
| `pending` | No | — | Being screened. |
| `pending_approval` | No | — | Waiting for an approver in your business. |
| `processing` | No | — | Sent for payment. Some banks confirm hours later: Multigate keeps asking the bank for the outcome for up to 24 hours (often at first, then less often), so a remittance can complete long after you sent it. |
| `completed` | Yes | `transfer_completed` | Paid. |
| `failed` | Yes | `transfer_failed` (not always) | Not paid; any debit reversed. Unlike other payouts, a remittance the bank refuses fails straight away, without waiting for Multigate's operations team to confirm it. |
| `rejected` | Yes | — | Declined by an approver; "Transaction Declined" email to the creator. |

```mermaid
stateDiagram-v2
    direction LR
    [*] --> pending
    [*] --> pending_approval
    [*] --> processing
    pending --> processing
    pending --> failed
    pending_approval --> pending
    pending_approval --> rejected
    processing --> completed
    processing --> failed
```

## Emails

Remittances send no "Transfer Notification" emails. The only email is "Transaction Declined", if an approver in your business declines one.

## Errors

The `400` errors are the same as [payout errors](05-payouts.md#errors), plus:

| Message | When | Fix |
|---|---|---|
| Maximum amount exceeded | An amount above the per-payment maximum. Remittances aren't split. | Send several remittances, each with its own `uniqueRequestId`. |
| Supporting documents are required for 3rd party USD transfers. | A USD remittance to someone other than the account holder. | Not possible through this endpoint today; contact Multigate. |
| Unable to process remittance transaction (in `failureReason`, after a `transfer_failed` webhook) | No remittance collection account is set up for your business (NGN). | Ask Multigate to set it up, then send again with a new `uniqueRequestId`. |
| Remittance payment not found (Get a remittance) | No transfer of your business has that ID. | Check the ID. |

After a timeout or `5xx`, look the remittance up by `uniqueRequestId` before retrying. See [Idempotency](../02-concepts/03-idempotency.md).

## Next

- [Remittance companies (IMTOs)](../05-use-cases/03-remittance-imto.md): the end-to-end flow.
- [Event catalogue](../03-webhooks-and-emails/02-event-catalogue.md) for the transfer webhooks.