> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Currency Payout API Reference

> Send funds to recipients across multiple currencies with Hello Clever's v2 Payout endpoints: bank transfers, mobile money, QR, and more.

The v2 Payout API lets you disburse funds to recipients in multiple currencies across APAC, Africa, Latin America, and beyond. You can pay out to bank accounts, mobile money wallets, PayIDs, and QR-based networks. This page covers every payout endpoint, including scheduled payout management, branch code lookups, and QR bank account resolution.

<Note>
  You only need to call Get Payout Methods and Get Required Fields once per method. After the initial discovery, reuse the same method code and field structure for all future payouts in that currency.
</Note>

***

## Get Payout Methods

<Badge color="green">GET</Badge> `/v2/payouts/payout_methods`

Returns all payout methods available for your `app-id`, based on your configured country and currency in the Hello Clever Merchant Dashboard.

### Response fields

<ResponseField name="records" type="object[]">
  Array of available payout methods.

  <Expandable title="properties">
    <ResponseField name="currency" type="string">
      ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="payout_method_name" type="string">
      The method identifier (e.g., `vn_bank_vnd`). Pass this value as `payout_method_name` when you create a payout.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  v2 identifies payout methods by `payout_method_name`, not `payout_method_code`. Call Get Payout Required Fields for a method's limits, supported banks, and required parameters.
</Note>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://api.cleverhub.co/api/v2/payouts/payout_methods \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "records": [
      {
        "currency": "PHP",
        "payout_method_name": "ph_bank_maya_php"
      },
      {
        "currency": "PHP",
        "payout_method_name": "ph_ewallet_gcash_php"
      },
      {
        "currency": "PHP",
        "payout_method_name": "ph_bank_php"
      }
    ]
  }
  ```
</CodeGroup>

***

## Get Payout Required Fields

<Badge color="green">GET</Badge> `/v2/payouts/payout_method/params`

Returns the fields required (or optional) for a specific payout method. Certain payout methods, such as bank transfers to specific countries, require recipient bank codes, account numbers, and other details.

### Query parameters

<ParamField query="payout_method_name" type="string" required>
  The method identifier returned from Get Payout Methods (e.g., `vn_bank_vnd`).
</ParamField>

### Response fields

<ResponseField name="record" type="object">
  Details for the requested payout method.

  <Expandable title="properties">
    <ResponseField name="currency" type="string">
      ISO 4217 currency code, with `symbol` and `logo` alongside it.
    </ResponseField>

    <ResponseField name="payout_method_name" type="string">
      The method identifier.
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable description of the method.
    </ResponseField>

    <ResponseField name="payout_method_params" type="object">
      The keys to send in each transaction's `payout_method_params`. Each entry is formatted as `type:Mandatory|Optional <description>`.
    </ResponseField>

    <ResponseField name="banks" type="object[]">
      Supported banks or e-wallets, each with `code`, `name`, and `short_name`. Empty for methods that do not require a provider selection.
    </ResponseField>

    <ResponseField name="payment_type" type="string">
      `pay_out` for payout methods.
    </ResponseField>

    <ResponseField name="require_contact" type="boolean">
      Whether a contact record is required before paying out. `require_kyc`, `is_refundable`, and `is_cancellable` are returned alongside it.
    </ResponseField>

    <ResponseField name="min_amount" type="number">
      Minimum payout amount, with `max_amount` for the upper bound.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/payout_method/params?payout_method_name=ph_bank_maya_php' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "record": {
      "currency": "PHP",
      "symbol": "₱",
      "logo": "",
      "payout_method_name": "ph_bank_maya_php",
      "description": "MAYA",
      "payout_method_params": {
        "account_number": "string:Mandatory Bank Account Number",
        "account_name": "string:Mandatory Account Holder Name",
        "bank_code": "string:Mandatory Bank Code"
      },
      "banks": [
        {
          "code": "600",
          "name": "GCASH",
          "short_name": null
        }
      ],
      "payment_type": "pay_out",
      "is_refundable": false,
      "is_cancellable": false,
      "require_contact": false,
      "require_kyc": false,
      "min_amount": 200,
      "max_amount": 50000
    }
  }
  ```
</CodeGroup>

***

## Create Payout

<Badge color="blue">POST</Badge> `/v2/payouts`

Initiates one or more payout transactions. Each payout is processed independently. If one transaction in a batch fails, the others still complete.

Payout statuses:

* `created`: Payout initiated.
* `processing`: Payout is being processed.
* `scheduled`: Waiting for funds to be transferred to the payee.
* `completed`: Entire batch completed.
* `expired`: The payout was not processed before its window closed.

<Note>
  For `vn_bank_vnd` payouts where the amount exceeds 300,000,000 VND or the bank requires it, you must include a `branch_code`. Use the Get Branch Codes endpoint to look up valid branch codes.
</Note>

### Body parameters

<ParamField body="payout_method_name" type="string" required>
  The method identifier returned by Get Payout Methods (e.g., `vn_bank_vnd`).
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code.
</ParamField>

<ParamField body="payout_transaction_details" type="object[]" required>
  Array of payout transactions. Each is processed independently.

  <Expandable title="properties">
    <ParamField body="first_name" type="string" required>
      Payee first name. Letters, numbers, and single spaces only.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Payee last name. Letters, numbers, and single spaces only.
    </ParamField>

    <ParamField body="email" type="string" required>
      Payee email address. If the method reports `require_contact: true`, this must match the email used to create the contact.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount to send in the currency's base unit. For `VND`, `JPY`, `XAF`, `KRW`, and `XOF`, this value is rounded to the precision the currency supports. See [amount rounding](/api/v2/introduction#amount-rounding). Optional for `usdc_bank`.
    </ParamField>

    <ParamField body="payout_method_params" type="object" required>
      Recipient details for the chosen method, such as `account_number`, `account_name`, and `bank_code`. Call Get Payout Required Fields for the exact keys. They differ per method.
    </ParamField>

    <ParamField body="external_id" type="string">
      Your unique identifier for this transaction.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  Description of the payout batch. Minimum 5 characters.
</ParamField>

<ParamField body="webhook_notification" type="object" required>
  Webhook configuration for this payout batch.

  <Expandable title="properties">
    <ParamField body="endpoint_url" type="string" required>
      Your webhook endpoint URL. Must be TLS 1.2 with a certificate from a well-known commercial authority.
    </ParamField>

    <ParamField body="authorization_header" type="string" required>
      Authorization header value sent with each webhook notification.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="scheduled_at" type="string">
  Timestamp to schedule the payout for a future time, in `YYYY-MM-DDTHH:mm:ss` format. Interpreted as UTC.
</ParamField>

<ParamField body="external_id" type="string">
  Your own identifier for the batch. Usable as a filter on Get Payouts in a Period.
</ParamField>

### Response fields

<ResponseField name="uuid" type="string">
  Unique identifier for the payout batch.
</ResponseField>

<ResponseField name="status" type="string">
  Current batch status: `created`, `processing`, `scheduled`, or `completed`.
</ResponseField>

<ResponseField name="total_amount" type="string">
  Combined amount of every transaction in the batch.
</ResponseField>

<ResponseField name="payout_transactions" type="object[]">
  Array of individual transaction results.

  <Expandable title="properties">
    <ResponseField name="uuid" type="string">
      Individual transaction UUID.
    </ResponseField>

    <ResponseField name="payee" type="string">
      Full name of the payee.
    </ResponseField>

    <ResponseField name="email" type="string">
      Payee email address.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Amount for this transaction.
    </ResponseField>

    <ResponseField name="payout_method_params" type="object">
      The recipient details submitted for this transaction.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of this specific transaction.
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Failure reason for this transaction, or `null`.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      Your identifier for this transaction, if you supplied one.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "payout_transaction_details": [
        {
          "first_name": "Nguyen",
          "last_name": "Van A",
          "email": "payee@example.com",
          "amount": 100000,
          "payout_method_params": {
            "account_number": "1234567890",
            "account_name": "Nguyen Van A",
            "bank_code": "VCB"
          },
          "external_id": "salary_jan_001"
        }
      ],
      "currency": "VND",
      "payout_method_name": "vn_bank_vnd",
      "description": "Salary payment",
      "webhook_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payout",
        "authorization_header": "Bearer abc123xyz"
      },
      "external_id": "batch_jan_001"
    }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "currency": "VND",
    "payout_method_name": "vn_bank_vnd",
    "description": "Salary payment",
    "total_amount": "100000",
    "status": "created",
    "scheduled_at": null,
    "payout_transactions": [
      {
        "uuid": "TXN9QM45",
        "balance_id": null,
        "payee": "Nguyen Van A",
        "email": "payee@example.com",
        "amount": "100000",
        "payout_method_params": {
          "account_number": "1234567890",
          "account_name": "Nguyen Van A",
          "bank_code": "VCB"
        },
        "status": "created",
        "error_message": null,
        "external_id": "salary_jan_001",
        "created_at": "2025-01-15T10:00:00.000+0000"
      }
    ],
    "external_id": "batch_jan_001"
  }
  ```
</CodeGroup>

***

## Get Payout Details

<Badge color="green">GET</Badge> `/v2/payouts/detail`

Returns the current status and details of a payout batch by UUID.

### Query parameters

<ParamField query="uuid" type="string" required>
  The UUID of the payout batch.
</ParamField>

<ParamField query="child_uuid" type="string">
  The UUID of a single transaction within the batch, to return just that transaction.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/detail?uuid=PAY8TK21' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "currency": "VND",
    "payout_method_name": "vn_bank_vnd",
    "description": "Salary payment",
    "total_amount": "100000",
    "status": "completed",
    "scheduled_at": null,
    "payout_transactions": [
      {
        "uuid": "TXN9QM45",
        "payee": "Nguyen Van A",
        "email": "payee@example.com",
        "amount": "100000",
        "status": "completed",
        "error_message": null,
        "reference": null,
        "external_id": "salary_jan_001",
        "created_at": "2025-01-15T10:00:00.000+0000"
      }
    ],
    "external_id": "batch_jan_001",
    "error_code": null,
    "error_message": ""
  }
  ```
</CodeGroup>

***

## Get Payouts in a Period

<Badge color="green">GET</Badge> `/v2/payouts/all`

Returns a paginated list of payout batches within a date range. Supports up to a 1-year period. Contact Hello Clever if you need a longer range.

### Query parameters

<ParamField query="from_date" type="string" required>
  Start of the date range in ISO 8601 format.
</ParamField>

<ParamField query="to_date" type="string" required>
  End of the date range in ISO 8601 format.
</ParamField>

<ParamField query="external_id" type="string">
  Filter to the payout batch matching your own identifier.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/all?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z&page=1' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "from_date": "2025-01-01T00:00:00.000+0000",
    "to_date": "2025-01-31T23:59:59.000+0000",
    "page": 1,
    "size": 10,
    "next_page": null,
    "total_page": 1,
    "total_count": 1,
    "records": [
      {
        "uuid": "PAY8TK21",
        "currency": "VND",
        "status": "completed"
      }
    ]
  }
  ```
</CodeGroup>

***

## Cancel Scheduled Payout

<Badge color="blue">POST</Badge> `/v2/payouts/cancel_scheduled`

Cancels a payout that has been scheduled to run at a future time. Only payouts in `scheduled` status can be cancelled.

### Body parameters

<ParamField body="uuid" type="string" required>
  The UUID of the scheduled payout to cancel.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts/cancel_scheduled \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "uuid": "PAY8TK21" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "status": "cancelled",
    "message": "Scheduled payout cancelled successfully"
  }
  ```
</CodeGroup>

***

## Payout Simulation (sandbox only)

<Badge color="blue">POST</Badge> `/v2/payouts/simulate`

Simulates the outcome of a pending payout in the sandbox environment. Not available in production.

### Body parameters

<ParamField body="uuid" type="string" required>
  The UUID of the payout to simulate.
</ParamField>

<ParamField body="status" type="string" required>
  The outcome to simulate: `completed` or `failed`.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts/simulate \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "uuid": "PAY8TK21", "status": "completed" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "status": "completed",
    "message": "Payout simulation successful"
  }
  ```
</CodeGroup>

***

## Get Branch Codes

<Badge color="green">GET</Badge> `/v2/payouts/branch_codes`

Returns branch codes for the `vn_bank_vnd` payout method. A branch code is required when the payout amount exceeds 300,000,000 VND or when the destination bank requires it.

### Query parameters

<ParamField query="payout_method_name" type="string" required>
  The payout method to look up branch codes for (`vn_bank_vnd`).
</ParamField>

<ParamField query="swift_code" type="string" required>
  The SWIFT code of the destination bank. Use Lookup via QR Content or Lookup via QR Image to resolve a SWIFT code from a VietQR code.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/branch_codes?payout_method_name=vn_bank_vnd&swift_code=BFTVVNVX' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "branch_codes": [
      {
        "branch_code": "79600001",
        "branch_name": "NH THE SIAM COMMERCIAL BANK PUBLIC-CN TP HO CHI MINH (NH The Siam Commercial Bank Public)"
      }
    ]
  }
  ```
</CodeGroup>

***

## Lookup via QR Content

<Badge color="blue">POST</Badge> `/v2/banks/lookup/qr_content`

Resolves bank account details from a VietQR (EMV Co) QR code content string. Returns the account name, account number, bank name, and SWIFT code when the QR content is valid.

### Body parameters

<ParamField body="qr_content" type="string" required>
  The raw string content encoded in the VietQR QR code.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/banks/lookup/qr_content \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "qr_content": "00020101021238570010A000000727..." }'
  ```

  ```json Response theme={null}
  {
    "account_name": "NGUYEN VAN A",
    "account_number": "1234567890",
    "bank_name": "Vietcombank",
    "swift_code": "BFTVVNVX"
  }
  ```
</CodeGroup>

***

## Lookup via QR Image

<Badge color="blue">POST</Badge> `/v2/banks/lookup/qr_image`

Resolves bank account details from a VietQR (EMV Co) QR code image. Returns the account name, account number, bank name, and SWIFT code when the image contains valid QR data.

### Body parameters

<ParamField body="qr_image" type="string" required>
  Base64-encoded image of the VietQR QR code.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/banks/lookup/qr_image \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "qr_image": "iVBORw0KGgoAAAANSUhEUgAA..." }'
  ```

  ```json Response theme={null}
  {
    "account_name": "NGUYEN VAN A",
    "account_number": "1234567890",
    "bank_name": "Vietcombank",
    "swift_code": "BFTVVNVX"
  }
  ```
</CodeGroup>


## Related topics

- [Handle Multi-Currency Payins and Payouts](/developer-reference/api-use-cases/handle-multi-currency-payins-and-payouts.md)
- [Multi-Currency Payment API](/api/v2/introduction.md)
- [Multi-Currency Payin API Reference](/api/v2/payin.md)