> ## Documentation Index
> Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🇨🇦 CAD Payout

This endpoint allows you to process payouts in **Canadian Dollars (CAD)** to recipients with a bank account in Canada.

***

## Endpoint

**POST:** `https://sandboxapi.me-cash.com/v2/payout`

***

## Request Details

### Headers

Include these headers in your request:

| **Header**     | **Value**          | **Required** |
| :------------- | :----------------- | :----------- |
| `Content-Type` | `application/json` | ✅ Yes        |
| `x-api-key`    | `YOUR_API_KEY`     | ✅ Yes        |

***

**meCash supports two Payment Channels for CAD Payouts:**

* **Bank Transfer**: Bank Transfer is the traditional way to send money directly into a recipient's bank account.
* **Interac**: The Interac E-Transfer is a popular Canadian payment service that lets you send money using an email address or mobile phone number.

## Sample Request for Bank Transfer

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": {
      "name": "John Chuks",
      "address": "12 blue street",
      "account": {
        "bankName": "Bank of Test",
        "accountNumber": "23099XXXXX",
        "address": "bank address",
        "sortCode": "890",
        "swiftCode": "SWIFT1234",
        "transitNumber": "12345"
      },
      "paymentChannel": "BANK_TRANSFER", // INTERAC
      "currency": "CAD",
      "country": "CA"
    },
    "quoteId": "f1474828-6a2e-4ee8-8598-xxxxxxxxxxxx",
    "reason": "Gift",
    "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    "remark": "test"
  }'
  ```

  ```javascript JavaScript (Fetch) theme={null}
  const url = 'https://sandboxapi.me-cash.com/v2/payout';

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      recipient: {
        name: "John Chuks",
        address: "12 blue street",
        account: {
          bankName: "Bank of Test",
          accountNumber: "230999******",
          address: "bank address",
          sortCode: "890",
          swiftCode": "SWIFT1234",
          transitNumber: "12345"
        },
        paymentChannel: "BANK_TRANSFER",
        currency: "CAD",
        country: "CA"
      },
      quoteId: "f1474828-6a2e-4ee8-8598-xxxxxxxxxxx",
      reason: "Gift",
      invoice: "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
      remark: "test"
    })
  };

  fetch(url, options)
    .then(res => {
      if (!res.ok) {
        throw new Error(`HTTP error! status: ${res.status}`);
      }
      return res.json();
    })
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```python Python (Requests) theme={null}
  import requests
  import json

  url = "https://sandboxapi.me-cash.com/v2/payout"

  payload = {
      "recipient": {
          "name": "John Chuks",
          "address": "12 blue street",
          "account": {
              "bankName": "Bank of Test",
              "accountNumber": "230999******",
              "address": "bank address",
              "sortCode": "890",
              "swiftCode": "SWIFT1234",
              "transitNumber": "12345"
          },
          "paymentChannel": "BANK_TRANSFER",
          "currency": "CAD",
          "country": "CA"
      },
      "quoteId": "f1474828-6a2e-4ee8-8598-xxxxxxxxxx",
      "reason": "Gift",
      "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
      "remark": "test"
  }

  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  try:
      response = requests.post(url, headers=headers, data=json.dumps(payload))
      response.raise_for_status()
      print(response.json())
  except requests.exceptions.HTTPError as err:
      print(f"HTTP Error: {err}")
  ```

  ```javascript Node.js (Axios) theme={null}
  const axios = require('axios');

  const url = 'https://sandboxapi.me-cash.com/v2/payout';

  const data = {
    recipient: {
      name: "John Chuks",
      address: "12 blue street",
      account: {
        bankName: "Bank of Test",
        accountNumber: "230999******",
        address: "bank address",
        sortCode: "890",
        swiftCode: "SWIFT1234",
        transitNumber: "12345"
      },
      paymentChannel: "BANK_TRANSFER",
      currency: "CAD",
      country: "CA"
    },
    quoteId: "f1474828-6a2e-4ee8-8598-xxxxxxxxxx",
    reason: "Gift",
    invoice: "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    remark: "test"
  };

  const config = {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    }
  };

  axios.post(url, data, config)
    .then(response => {
      console.log(response.data);
    })
    .catch(error => {
      console.error('Error:', error.response ? error.response.data : error.message);
    });
  ```
</CodeGroup>

***

## Sample Request: Interac E-Transfer

Here are examples of how to make a CAD payout request via Interac, using the recipient's email or mobile number.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "recipient": {
          "name": "Nettie Wuckert",
          "mobileNumber": "613700****",
          "email": "Guiseppe_Wisoky77@example.net",
          "type": "BUSINESS",
          "account": {},
          "paymentChannel": "INTERAC",
          "currency": "CAD",
          "country": "CA",
          "stored": true
      },
      "quoteId": "5392890f-cab6-40ee-8db2-xxxxxxxxxx",
      "reason": "Gift",
      "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
      "remark": "Testing"
  }'
  ```

  ```javascript JavaScript (Fetch) theme={null}
  const url = 'https://sandboxapi.me-cash.com/v2/payout';

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      recipient: {
        name: "Nettie Wuckert",
        mobileNumber: "613700****",
        email: "Guiseppe_Wisoky77@example.net",
        type: "BUSINESS",
        account: {},
        paymentChannel: "INTERAC",
        currency: "CAD",
        country: "CA",
        stored: true
      },
      quoteId: "5392890f-cab6-40ee-8db2-9de2532b2de0",
      reason: "Gift",
      invoice: "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
      remark: "Testing"
    })
  };

  fetch(url, options)
    .then(res => {
      if (!res.ok) {
        throw new Error(`HTTP error! status: ${res.status}`);
      }
      return res.json();
    })
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```python Python (Requests) theme={null}
  import requests
  import json

  url = "https://sandboxapi.me-cash.com/v2/payout"

  payload = {
      "recipient": {
          "name": "Nettie Wuckert",
          "mobileNumber": "613700****",
          "email": "Guiseppe_Wisoky77@example.net",
          "type": "BUSINESS",
          "account": {},
          "paymentChannel": "INTERAC",
          "currency": "CAD",
          "country": "CA",
          "stored": true
      },
      "quoteId": "5392890f-cab6-40ee-8db2-xxxxxxxxxx",
      "reason": "Gift",
      "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
      "remark": "Testing"
  }

  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  try:
      response = requests.post(url, headers=headers, data=json.dumps(payload))
      response.raise_for_status()
      print(response.json())
  except requests.exceptions.HTTPError as err:
      print(f"HTTP Error: {err}")
  ```

  ```javascript Node.js (Axios) theme={null}
  const axios = require('axios');

  const url = 'https://sandboxapi.me-cash.com/v2/payout';

  const data = {
    recipient: {
      name: "Nettie Wuckert",
      mobileNumber: "613700****",
      email: "Guiseppe_Wisoky77@example.net",
      type: "BUSINESS",
      account: {},
      paymentChannel: "INTERAC",
      currency: "CAD",
      country: "CA",
      stored: true
    },
    quoteId: "5392890f-cab6-40ee-8db2-xxxxxxxxxx",
    reason: "Gift",
    invoice: "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    remark: "Testing"
  };

  const config = {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    }
  };

  axios.post(url, data, config)
    .then(response => {
      console.log(response.data);
    })
    .catch(error => {
      console.error('Error:', error.response ? error.response.data : error.message);
    });
  ```
</CodeGroup>

***

### Request Body Breakdown

| **Field**                         | **Type** | **Description**                                                                                             | **Required** |
| :-------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------- | :----------- |
| `quoteId`                         | String   | The unique ID of the quote for this payout.                                                                 | ✅ Yes        |
| `reason`                          | String   | The purpose of the transfer (e.g., `Payment for services`).                                                 | ✅ Yes        |
| `invoice`                         | String   | Optional identifier for the invoice (returned from file upload).                                            | ❌ No         |
| `remark`                          | String   | An optional, additional note about the transaction.                                                         | ❔ No         |
| `recipient`                       | Object   | An object containing all details about the person receiving the funds.                                      | ✅ Yes        |
| `recipient.name`                  | String   | The full name of the recipient or business.                                                                 | ✅ Yes        |
| `recipient.paymentChannel`        | String   | The payment method. Can be `BANK_TRANSFER` or `INTERAC` for CAD payouts.                                    | ✅ Yes        |
| `recipient.currency`              | String   | The ISO currency code. Must be `CAD`.                                                                       | ✅ Yes        |
| `recipient.country`               | String   | The recipient's two-letter ISO country code. Must be `CA`.                                                  | ✅ Yes        |
| `recipient.mobileNumber`          | String   | **(Interac Only)** The recipient's mobile number. Either `mobileNumber` or `email` is required for Interac. | ✅ Yes        |
| `recipient.email`                 | String   | **(Interac Only)** The recipient's email address. Either `mobileNumber` or `email` is required for Interac. | ✅ Yes        |
| `recipient.type`                  | String   | **(Interac Only)** The recipient type. Can be `INDIVIDUAL` or `BUSINESS`.                                   | ✅ Yes        |
| `recipient.stored`                | Boolean  | **(Interac Only)** Set to `true` if the recipient is a saved beneficiary.                                   | ✅ Yes        |
| `recipient.address`               | String   | **(Bank Transfer Only)** The recipient's full residential or business address.                              | ✅ Yes        |
| `recipient.account`               | Object   | **(Bank Transfer Only)** An object containing the recipient's bank account details.                         | ✅ Yes        |
| `recipient.account.accountNumber` | String   | **(Bank Transfer Only)** The recipient's bank account number.                                               | ✅ Yes        |
| `recipient.account.bankName`      | String   | **(Bank Transfer Only)** The name of the recipient's bank.                                                  | ✅ Yes        |
| `recipient.account.address`       | String   | **(Bank Transfer Only)** The address of the recipient's bank branch.                                        | ✅ Yes        |
| `recipient.account.sortCode`      | String   | **(Bank Transfer Only)** The 3-digit institution number for the Canadian bank.                              | ✅ Yes        |
| `recipient.account.swiftCode`     | String   | **(Bank Transfer Only)** The recipient bank's SWIFT/BIC code.                                               | ✅ Yes        |
| `recipient.account.transitNumber` | String   | **(Bank Transfer Only)** The 5-digit number identifying the recipient's bank branch in Canada.              | ✅ Yes        |

***

## Success Response (Bank Transfer) (200 OK)

If the payout is successfully created, the API returns the following response:

```json copy theme={null}
{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "d4e5f6a7-b8c9-1234-abcd-xxxxxxxxxxxxx",
    "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    "reason": "Gift",
    "referenceNumber": "CADXFER5ABCFG",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "f1474828-6a2e-4ee8-xxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 125000
      },
      "target": {
        "currency": "CAD",
        "country": "CA",
        "amount": 100
      },
      "rate": 1250,
      "fee": {
        "amount": 500
      }
    },
    "recipient": {
      "name": "John Chuks",
      "address": "12 blue street",
      "account": {
        "accountNumber": "2309...XXX",
        "bankName": "Bank Test",
        "sortCode": "890",
        "swiftCode": "SWIFT1234",
        "transitNumber": "12345"
        
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "CAD",
      "country": "CA"
    },
    "created": "2025-09-23T08:10:15.123456Z",
    "processed": "2025-09-23T08:12:30.789101Z"
  }
}
```

## Success Response for Interac (200 OK)

If the payout is successfully created, the API returns the following response:

```json copy theme={null}

{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-xxxxxxxxxx",
    "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    "reason": "Gift",
    "referenceNumber": "CADINT5ZYXWV",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "5392890f-cab6-40ee-8db2-xxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 150000
      },
      "target": {
        "currency": "CAD",
        "country": "CA",
        "amount": 120
      },
      "rate": 1250,
      "fee": {
        "amount": 500
      }
    },
    "recipient": {
      "name": "Nettie Wuckert",
      "email": "Guiseppe_Wisoky77@example.net",
      "account": {},
      "paymentChannel": "INTERAC",
      "currency": "CAD",
      "country": "CA"
    },
    "created": "2025-10-03T15:10:15.123456Z",
    "processed": "2025-10-03T15:10:16.789101Z"
  }
}
```

## Response Breakdown

This table explains each field in the success response payload. Note that some fields in the `recipient` object are specific to the payment channel used.

| **Field**                              | **Type** | **Description**                                                                                |
| :------------------------------------- | :------- | :--------------------------------------------------------------------------------------------- |
| `message`                              | String   | A confirmation message indicating the result of the request.                                   |
| `status`                               | String   | The overall status of the request, e.g., `success`.                                            |
| `data`                                 | Object   | A container for all the transaction data.                                                      |
| `data.id`                              | String   | The unique identifier for this payout transaction.                                             |
| `data.reason`                          | String   | The reason for the payout that was provided in the request.                                    |
| `data.invoice`                         | String   | Optional identifier for the invoice provided in the request.                                   |
| `data.referenceNumber`                 | String   | A unique reference number generated for the payout.                                            |
| `data.state`                           | String   | The current state of the payout (`COMPLETED`, `PENDING`, etc.).                                |
| `data.quote`                           | Object   | An object containing the details of the quote used for this transaction.                       |
| `data.quote.target.amount`             | Number   | The converted amount that the recipient is scheduled to receive.                               |
| `data.recipient`                       | Object   | An object containing details of the recipient.                                                 |
| `data.recipient.name`                  | String   | The full name of the recipient.                                                                |
| `data.recipient.email`                 | String   | **(Interac Only)** The recipient's email address that the e-Transfer notification was sent to. |
| `data.recipient.paymentChannel`        | String   | The payment channel used for the payout, either `BANK_TRANSFER` or `INTERAC`.                  |
| `data.recipient.account.accountNumber` | String   | **(Bank Transfer Only)** The recipient's masked bank account number.                           |
| `data.recipient.account.bankName`      | String   | **(Bank Transfer Only)** The name of the recipient's bank.                                     |
| `data.recipient.account.sortCode`      | String   | **(Bank Transfer Only)** The 3-digit institution number of the recipient's bank.               |
| `data.recipient.account.transitNumber` | String   | **(Bank Transfer Only)** The 5-digit transit number of the recipient's bank branch.            |
| `data.created`                         | String   | ISO 8601 timestamp of when the transaction was created.                                        |
| `data.processed`                       | String   | ISO 8601 timestamp of when the transaction was successfully processed.                         |

***

## Payout Transaction States

The payout transaction can have one of the following states:

| **State**   | **Description**                          |
| :---------- | :--------------------------------------- |
| `COMPLETED` | The payout was successfully processed.   |
| `PENDING`   | The payout is still being processed.     |
| `FAILED`    | The payout failed to process.            |
| `REFUNDED`  | The payout has been sent back to sender. |

***

## Error Handling

| **Status Code** | **Meaning**           | **Example Response**                   |
| :-------------- | :-------------------- | :------------------------------------- |
| `400`           | Insufficient Balance  | Insufficient Balance                   |
| `401`           | Unauthorized          | Invalid API key provided.              |
| `403`           | Forbidden             | IP not whitelisted                     |
| `404`           | Not Found             | The requested endpoint does not exist. |
| `422`           | Unprocessable Entity  | Invalid quote ID provided.             |
| `500`           | Internal Server Error | An internal error occurred.            |

***

## Best Practices

✅ Ensure `quoteId` is valid and linked to an existing quote.\
✅ Confirm that the recipient’s account number, transit number, and institution number are correct.\
✅ Use a valid API key in the headers.\
✅ Handle error responses correctly in your integration.