Payout

Create a Payout

This API enables outbound payments in mutilple currency using supported payout methods. Steps to create a payout:

Step 1: Call the Get payout methods to retrieve the list of supported methods.
Step 2: Call the Get payout required fields to get specific required fields for each method.
Step 3: Initialize a payout with the required fields.

You only need to do steps 1 and 2 once. After that, you can use the same method and required fields to create a payout payment.

There are 4 statuses of the payment:

created: Payout payment created.
processing: Payout has been processed
scheduled: Waiting for fund to be charged to the payee.
completed: Payout payment has been completed for the entire batch, not for individual transactions.

Please note: If you use one of the following payout methods, please check the list of supported providers before proceeding:

vn_bank_vnd: View supported
ph_bank_php: View supported
ng_bank_ngn: View supported
sa_bank_zar: View supported
ke_bank_kes: View supported
ke_mobile_money_kes: View supported
gh_mobile_money_ghs: View supported
cm_mobile_money_xaf: View supported
ci_mobile_money_xof: View supported
my_bank_myr: View supported
my_ewallet_*_myr (touchngo, finexus, boost, bigpay, shopeepay, gxbank, merchantrade): View supported
br_bank_brl: View supported
th_bank_thb: View supported
bw_bank_bwp: View supported
ph_qrph_php: View supported
mwk_mobile_money_network: View supported

For vn_bank_vnd, we also provide an API to get branch codes when required.

For kr_bank_krw, we also provide an Required Field API to obtain the list of banks that are currently supported.

Please note that if any of the transactions fail, it will not affect the completion of the entire batch.

POST

payouts

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payouts \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "payout_transaction_details": [
    {
      "first_name": "Clever",
      "last_name": "Hello",
      "email": "test@example.com",
      "amount": 100,
      "payout_method_params": {
        "bsb": "572505",
        "account_number": "76273288",
        "purpose_code": "other",
        "phone": "+61928312999"
      },
      "external_id": null
    }
  ],
  "currency": "AUD",
  "payout_method_name": "au_bank_aud",
  "description": "Test payout",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "external_id": "123"
}
'

{
  "uuid": "OHXTEF9M",
  "currency": "AUD",
  "payout_method_name": "au_bank_aud",
  "description": "Payout payment 2023",
  "total_amount": "1000",
  "status": "created",
  "scheduled_at": null,
  "payout_transactions": [
    {
      "uuid": "GPZUNCM5",
      "balance_id": null,
      "payee": "Clever Hello",
      "email": "test@example.com",
      "amount": "100",
      "payout_method_params": {
        "bsb": "572505",
        "account_number": "76273288",
        "purpose_code": "other",
        "phone": "+61928312999"
      },
      "status": "created",
      "error_message": null,
      "reference": null,
      "external_id": null,
      "created_at": "2025-03-07T06:47:27.069+0000"
    }
  ],
  "external_id": "123",
  "error_code": "HC_PAYOUT1",
  "error_message": "",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  }
}

Authorizations

app-id

string

header

required

A unique identifier assigned to each application.

secret-key

string

header

required

A secure token associated with the app-id.

Body

application/json

payout_transaction_details

object[]

required

Payout transaction details

Show child attributes

currency

string

required

Currency for payout

Example:

"PHP"

payout_method_name

string

required

Payout method name

Example:

"ph_ewallet_gcash_php"

description

string

required

Description of payout payment

Minimum string length: 5

Example:

"Payout payment 2023"

webhook_notification

object

required

Show child attributes

scheduled_at

string<YYYY-MM-DDTHH:mm:ss>

Payout transaction to payee in this time. This datetime would be in UTC timezone.

Example:

"2023-04-01T00:00:00"

external_id

string

Custom ID

Example:

"123"

Callbacks

POST

{$request.body#/webhook_notification/endpoint_url}myEvent

Body

application/json

uuid

string

required

Unique id in system.

Example:

"OHXTEF9M"

currency

string

required

Currency payout

Example:

"PHP"

payout_method_name

string

required

Example:

"ph_ewallet_gcash_php"

total_amount

string

required

Total amount of list payout transactions

Example:

"1000"

status

enum<string>

required

Status of payout payment

Available options:

created,

processing,

scheduled,

completed,

expired

Example:

"completed"

webhook_notification

object

required

Merchant Callback Details

Show child attributes

description

string

Description of payout payment.

Required string length: 1 - 90

Example:

"Payout payment 2023"

scheduled_at

string<YYYY-MM-DDTHH:mm:ss>

Payout transaction to payee in this time. This datetime would be in UTC timezone.

Example:

"2023-04-01T00:00:00.000+0000"

payout_transactions

object[]

Payout transaction details

Show child attributes

error_code

enum<string>

Error code for the batch. We have 2 error codes HC_PAYOUT1 (Insufficient funds to payout. Please topup balance in dashboard) and HC_PAYOUT2 (Insufficient Balance. Hello Clever will charge your PayTo agreement to pay out).

Available options:

HC_PAYOUT1,

HC_PAYOUT2

Example:

"HC_PAYOUT1"

error_message

enum<string>

A description corresponds to the value of the statusCode field.

Available options:

Insufficient available funds. Top up your balance.,

Insufficient Balance. Hello Clever will charge your PayTo agreement to pay out.

Example:

"Insufficient available funds. Top up your balance."

external_id

string

Custom ID

Example:

"123"

Response

200

The merchant's server should returns this code

Response

uuid

string

required

Unique id in system.

Example:

"OHXTEF9M"

currency

string

required

Currency payout

Example:

"PHP"

payout_method_name

string

required

Example:

"ph_ewallet_gcash_php"

total_amount

string

required

Total amount of list payout transactions

Example:

"1000"

status

enum<string>

required

Status of payout payment

Available options:

created,

processing,

scheduled,

completed,

expired

Example:

"completed"

webhook_notification

object

required

Merchant Callback Details

Show child attributes

description

string

Description of payout payment.

Required string length: 1 - 90

Example:

"Payout payment 2023"

scheduled_at

string<YYYY-MM-DDTHH:mm:ss>

Payout transaction to payee in this time. This datetime would be in UTC timezone.

Example:

"2023-04-01T00:00:00.000+0000"

payout_transactions

object[]

Payout transaction details

Show child attributes

error_code

enum<string>

Available options:

HC_PAYOUT1,

HC_PAYOUT2

Example:

"HC_PAYOUT1"

error_message

enum<string>

A description corresponds to the value of the statusCode field.

Available options:

Insufficient available funds. Top up your balance.,

Insufficient Balance. Hello Clever will charge your PayTo agreement to pay out.

Example:

"Insufficient available funds. Top up your balance."

external_id

string

Custom ID

Example:

"123"

Get Payout Required Fields

Get Payout Requests in a Period of Time

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payouts \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "payout_transaction_details": [
    {
      "first_name": "Clever",
      "last_name": "Hello",
      "email": "test@example.com",
      "amount": 100,
      "payout_method_params": {
        "bsb": "572505",
        "account_number": "76273288",
        "purpose_code": "other",
        "phone": "+61928312999"
      },
      "external_id": null
    }
  ],
  "currency": "AUD",
  "payout_method_name": "au_bank_aud",
  "description": "Test payout",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "external_id": "123"
}
'

{
  "uuid": "OHXTEF9M",
  "currency": "AUD",
  "payout_method_name": "au_bank_aud",
  "description": "Payout payment 2023",
  "total_amount": "1000",
  "status": "created",
  "scheduled_at": null,
  "payout_transactions": [
    {
      "uuid": "GPZUNCM5",
      "balance_id": null,
      "payee": "Clever Hello",
      "email": "test@example.com",
      "amount": "100",
      "payout_method_params": {
        "bsb": "572505",
        "account_number": "76273288",
        "purpose_code": "other",
        "phone": "+61928312999"
      },
      "status": "created",
      "error_message": null,
      "reference": null,
      "external_id": null,
      "created_at": "2025-03-07T06:47:27.069+0000"
    }
  ],
  "external_id": "123",
  "error_code": "HC_PAYOUT1",
  "error_message": "",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  }
}

Overview

Payment Gateway (AUD)

Multi-currency Payment APIs

Multi-currency Gateway

Card API

Cashback API

Create a Payout

Authorizations

Body

Callbacks

Body

Response

Response