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

# 🇲🇾 MYR Payout

This endpoint allows you to process payouts in **Malaysian Ringgit (MYR)** to recipients with a bank account in Malaysia.

***

## Endpoint

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

***

## Supported Payment Channels

MYR payouts support the following payment channel:

| **Channel**     | **Description**                           | **Use Case**                       |
| :-------------- | :---------------------------------------- | :--------------------------------- |
| `BANK_TRANSFER` | Standard bank transfer to Malaysian banks | Domestic transfers within Malaysia |

***

## Request Details

### Headers

Include these headers in your request:

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

***

## Sample Requests

<Tabs>
  <Tab title="BANK_TRANSFER">
    Use `BANK_TRANSFER` for standard domestic MYR bank transfers.

    <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": "Jayden Tan",
          "nickName": "TestMY",
          "type": "INDIVIDUAL",
          "stored": false,
          "account": {
              "bankName": "Affin Bank Berhad",
              "sortCode": "00163",
              "swiftCode": "AFFNMYKLXXX",
              "accountNumber": "001234****"
          },
          "sourceOfFunds": "I1",
          "paymentChannel": "BANK_TRANSFER",
          "currency": "MYR",
          "country": "MY"
        },
        "quoteId": "779997685832",
        "reason": "Gift",
        "remark": "TestMYR"
      }'
      ```

      ```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: "Jayden Tan",
            nickName: "TestMY",
            type: "INDIVIDUAL",
            stored: false,
            account: {
              bankName: "Affin Bank Berhad",
              sortCode: "00163",
              swiftCode: "AFFNMYKLXXX",
              accountNumber: "001234****"
            },
            sourceOfFunds: "I1",
            paymentChannel: "BANK_TRANSFER",
            currency: "MYR",
            country: "MY"
          },
          quoteId: "779997685832",
          reason: "Gift",
          remark: "TestMYR"
        })
      };

      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": "Jayden Tan",
              "nickName": "TestMY",
              "type": "INDIVIDUAL",
              "stored": False,
              "account": {
                  "bankName": "Affin Bank Berhad",
                  "sortCode": "00163",
                  "swiftCode": "AFFNMYKLXXX",
                  "accountNumber": "001234****"
              },
              "sourceOfFunds": "I1",
                  "paymentChannel": "BANK_TRANSFER",
              "currency": "MYR",
              "country": "MY"
          },
          "quoteId": "779997685832",
          "reason": "Gift",
          "remark": "TestMYR"
      }

      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}")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

### Request Body Breakdown

<Tabs>
  <Tab title="BANK_TRANSFER Fields">
    | **Field**                         | **Type** | **Description**                                            | **Required** |
    | :-------------------------------- | :------- | :--------------------------------------------------------- | :----------- |
    | `quoteId`                         | String   | The unique ID of the quote for this payout.                | ✅ Yes        |
    | `reason`                          | String   | The purpose of the transfer.                               | ✅ Yes        |
    | `remark`                          | String   | An optional, additional note about the transaction.        | ❔ No         |
    | `recipient`                       | Object   | An object containing all details about the beneficiary.    | ✅ Yes        |
    | `recipient.name`                  | String   | The full name of the recipient.                            | ✅ Yes        |
    | `recipient.nickName`              | String   | The recipient's nickname.                                  | ❔ No         |
    | `recipient.type`                  | String   | The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`.     | ✅ Yes        |
    | `recipient.account`               | Object   | An object containing the recipient's bank account details. | ✅ Yes        |
    | `recipient.account.bankName`      | String   | The name of the recipient's bank.                          | ✅ Yes        |
    | `recipient.account.accountNumber` | String   | The recipient's bank account number.                       | ✅ Yes        |
    | `recipient.account.sortCode`      | String   | The bank code/sort code (e.g., `00163`).                   | ✅ Yes        |
    | `recipient.account.swiftCode`     | String   | The SWIFT code of the bank (e.g., `AFFNMYKLXXX`).          | ✅ Yes        |
    | `recipient.paymentChannel`        | String   | The payment method. Must be `BANK_TRANSFER`.               | ✅ Yes        |
    | `recipient.sourceOfFunds`         | String   | Code indicating the source of funds (e.g., `I1`).          | ✅ Yes        |
  </Tab>
</Tabs>

***

## Success Response (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": "MYR-PAYOUT-ID-12345",
    "reason": "Gift",
    "referenceNumber": "MYRPAYOUTREF123",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "779997685832",
      "source": {
        "currency": "USD",
        "country": "US",
        "amount": 100
      },
      "target": {
        "currency": "MYR",
        "country": "MY",
        "amount": 426.72
      },
      "rate": 4.26,
      "fee": {
        "amount": 0.77
      }
    },
    "recipient": {
      "name": "Jayden Tan",
      "type": "INDIVIDUAL",
      "account": {
          "name": "Jayden Tan",
          "bankName": "Affin Bank Berhad",
          "accountNumber": "001234****"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "MYR",
      "country": "MY"
    },
    "created": "2026-02-04T09:41:02.000Z",
    "processed": "2026-02-04T09:42:02.000Z"
  }
}
```

***

## **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 **bank account number** and **bank code** are correct.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.

<Tip>
  **Testing Failed Payouts:** In the sandbox environment, you can simulate a failed payout by setting `"remark": "fail"` in your request. This triggers a `payout.failed` webhook, allowing you to test your error handling.
</Tip>