Hello Clever Developer Docs

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.

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.

Get Payout Methods

GET /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

object[]

Array of available payout methods.

Show properties

string

ISO 4217 currency code.

string

The method identifier (e.g., vn_bank_vnd). Pass this value as payout_method_name when you create a payout.

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.

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'

{
  "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"
    }
  ]
}

Get Payout Required Fields

GET /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

string

required

The method identifier returned from Get Payout Methods (e.g., vn_bank_vnd).

Response fields

object

Details for the requested payout method.

Show properties

string

ISO 4217 currency code, with symbol and logo alongside it.

string

The method identifier.

string

Human-readable description of the method.

object

The keys to send in each transaction’s payout_method_params. Each entry is formatted as type:Mandatory|Optional <description>.

object[]

Supported banks or e-wallets, each with code, name, and short_name. Empty for methods that do not require a provider selection.

string

pay_out for payout methods.

boolean

Whether a contact record is required before paying out. require_kyc, is_refundable, and is_cancellable are returned alongside it.

number

Minimum payout amount, with max_amount for the upper bound.

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'

{
  "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
  }
}

Create Payout

POST /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.

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.

Body parameters

string

required

The method identifier returned by Get Payout Methods (e.g., vn_bank_vnd).

string

required

ISO 4217 currency code.

object[]

required

Array of payout transactions. Each is processed independently.

Show properties

string

required

Payee first name. Letters, numbers, and single spaces only.

string

required

Payee last name. Letters, numbers, and single spaces only.

string

required

Payee email address. If the method reports require_contact: true, this must match the email used to create the contact.

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. Optional for usdc_bank.

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.

string

Your unique identifier for this transaction.

string

required

Description of the payout batch. Minimum 5 characters.

object

required

Webhook configuration for this payout batch.

Show properties

string

required

Your webhook endpoint URL. Must be TLS 1.2 with a certificate from a well-known commercial authority.

string

required

Authorization header value sent with each webhook notification.

string

Timestamp to schedule the payout for a future time, in YYYY-MM-DDTHH:mm:ss format. Interpreted as UTC.

string

Your own identifier for the batch. Usable as a filter on Get Payouts in a Period.

Response fields

string

Unique identifier for the payout batch.

string

Current batch status: created, processing, scheduled, or completed.

string

Combined amount of every transaction in the batch.

object[]

Array of individual transaction results.

Show properties

string

Individual transaction UUID.

string

Full name of the payee.

string

Payee email address.

string

Amount for this transaction.

object

The recipient details submitted for this transaction.

string

Status of this specific transaction.

string

Failure reason for this transaction, or null.

string

Your identifier for this transaction, if you supplied one.

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"
  }'

{
  "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"
}

Get Payout Details

GET /v2/payouts/detail Returns the current status and details of a payout batch by UUID.

Query parameters

string

required

The UUID of the payout batch.

string

The UUID of a single transaction within the batch, to return just that transaction.

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'

{
  "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": ""
}

Get Payouts in a Period

GET /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

string

required

Start of the date range in ISO 8601 format.

string

required

End of the date range in ISO 8601 format.

string

Filter to the payout batch matching your own identifier.

number

default:"1"

Page number for pagination.

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'

{
  "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"
    }
  ]
}

Cancel Scheduled Payout

POST /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

string

required

The UUID of the scheduled payout to cancel.

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" }'

{
  "uuid": "PAY8TK21",
  "status": "cancelled",
  "message": "Scheduled payout cancelled successfully"
}

Payout Simulation (sandbox only)

POST /v2/payouts/simulate Simulates the outcome of a pending payout in the sandbox environment. Not available in production.

Body parameters

string

required

The UUID of the payout to simulate.

string

required

The outcome to simulate: completed or failed.

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" }'

{
  "uuid": "PAY8TK21",
  "status": "completed",
  "message": "Payout simulation successful"
}

Get Branch Codes

GET /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

string

required

The payout method to look up branch codes for (vn_bank_vnd).

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.

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'

{
  "branch_codes": [
    {
      "branch_code": "79600001",
      "branch_name": "NH THE SIAM COMMERCIAL BANK PUBLIC-CN TP HO CHI MINH (NH The Siam Commercial Bank Public)"
    }
  ]
}

Lookup via QR Content

POST /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

string

required

The raw string content encoded in the VietQR QR code.

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..." }'

{
  "account_name": "NGUYEN VAN A",
  "account_number": "1234567890",
  "bank_name": "Vietcombank",
  "swift_code": "BFTVVNVX"
}

Lookup via QR Image

POST /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

string

required

Base64-encoded image of the VietQR QR code.

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..." }'

{
  "account_name": "NGUYEN VAN A",
  "account_number": "1234567890",
  "bank_name": "Vietcombank",
  "swift_code": "BFTVVNVX"
}

Basics

Payment APIs

Card API

Cashback API

Multi-Currency Payout API Reference

Get Payout Methods

Response fields

Get Payout Required Fields

Query parameters

Response fields

Create Payout

Body parameters

Response fields

Get Payout Details

Query parameters

Get Payouts in a Period

Query parameters

Cancel Scheduled Payout

Body parameters

Payout Simulation (sandbox only)

Body parameters

Get Branch Codes

Query parameters

Lookup via QR Content

Body parameters

Lookup via QR Image

Body parameters

​Get Payout Methods

​Response fields

​Get Payout Required Fields

​Query parameters

​Response fields

​Create Payout

​Body parameters

​Response fields

​Get Payout Details

​Query parameters

​Get Payouts in a Period

​Query parameters

​Cancel Scheduled Payout

​Body parameters

​Payout Simulation (sandbox only)

​Body parameters

​Get Branch Codes

​Query parameters

​Lookup via QR Content

​Body parameters

​Lookup via QR Image

​Body parameters

Get Payout Methods

Response fields

Get Payout Required Fields

Query parameters

Response fields

Create Payout

Body parameters

Response fields

Get Payout Details

Query parameters

Get Payouts in a Period

Query parameters

Cancel Scheduled Payout

Body parameters

Payout Simulation (sandbox only)

Body parameters

Get Branch Codes

Query parameters

Lookup via QR Content

Body parameters

Lookup via QR Image

Body parameters