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

# 🇰🇷 KRW Payout

This endpoint allows you to process payouts in **South Korean Won (KRW)** to recipients with a bank account in South Korea.

***

## Endpoint

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

***

## Supported Payment Channels

KRW payouts support the following payment channel:

| **Channel**     | **Description**                              | **Use Case**                          |
| :-------------- | :------------------------------------------- | :------------------------------------ |
| `BANK_TRANSFER` | Standard bank transfer to South Korean banks | Domestic transfers within South Korea |

***

## 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 KRW 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": "Min-jun Kim",
          "nickName": "TestLRQ",
          "gender": "M",
          "mobileNumber": "080123*****",
          "occupation": "business entrepreneur",
          "countryName": "KR",
          "type": "BUSINESS",
          "stored": false,
          "account": {
              "bankName": "KDB산업:Korea Development Bank",
              "sortCode": "01462",
              "swiftCode": "DBSSSGSGXXX",
              "bankCity": "Seoul",
              "accountNumber": "001299******",
          },
          "sourceOfFunds": "I1",
          "paymentChannel": "BANK_TRANSFER",
          "currency": "KRW",
          "country": "KR"
        },
        "quoteId": "b51741c8-05c5-41af-9bbf-xxxxxxxxxxxxx",
        "reason": "Gift",
        "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: "Min-jun Kim",
            nickName: "TestLRQ",
            gender: "M",
            mobileNumber: "080123*****",
            occupation: "business entrepreneur",
            countryName: "KR",
            type: "BUSINESS",
            stored: false,
            account: {
              bankName: "KDB산업:Korea Development Bank",
              sortCode: "01462",
              swiftCode: "DBSSSGSGXXX",
              bankCity: "Seoul",
              accountNumber: "001299******",

            },
            sourceOfFunds: "I1",
            paymentChannel: "BANK_TRANSFER",
            currency: "KRW",
            country: "KR"
          },
          quoteId: "b51741c8-05c5-41af-9bbf-xxxxxxxxxxxxx",
          reason: "Gift",
          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": "Min-jun Kim",
              "nickName": "TestLRQ",
              "gender": "M",
              "mobileNumber": "080123*****",
              "occupation": "business entrepreneur",
              "countryName": "KR",
              "type": "BUSINESS",
              "stored": False,
              "account": {
                  "bankName": "KDB산업:Korea Development Bank",
                  "sortCode": "01462",
                  "swiftCode": "DBSSSGSGXXX",
                  "bankCity": "Seoul",
                  "accountNumber": "001299******",

              },
              "sourceOfFunds": "I1",
                  "paymentChannel": "BANK_TRANSFER",
              "currency": "KRW",
              "country": "KR"
          },
          "quoteId": "b51741c8-05c5-41af-9bbf-xxxxxxxxxxxxx",
          "reason": "Gift",
          "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}")
      ```
    </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.mobileNumber`          | String   | The recipient's mobile number.                             | ✅ Yes        |
    | `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., `01462` for KDB).           | ✅ 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": "KRW-PAYOUT-ID-67890",
    "reason": "Gift",
    "referenceNumber": "KRWPAYOUTREF456",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "b51741c8-05c5-41af-9bbf-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 10000
      },
      "target": {
        "currency": "KRW",
        "country": "KR",
        "amount": 14000
      },
      "rate": 1.4,
      "fee": {
        "amount": 100
      }
    },
    "recipient": {
      "name": "Min-jun Kim",
      "type": "BUSINESS",
      "account": {
          "name": "Min-jun Kim",
          "bankName": "KDB산업:Korea Development Bank",
          "accountNumber": "001299******"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "KRW",
      "country": "KR"
    },
    "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>