Skip to main content

Create a Payout

POST 
https://api.cleverhub.co/api/v2/payouts

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:

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

Request​

Body

    payout_transaction_details object[]required

    Payout transaction details

  • Array [
    • first_namestringrequired

    Payee first name

    Possible values: Value must match regular expression /\A(?![ ])(?![ ]*$)[a-zA-Z0-9 ]*(?<![ ])\z/

    Example: John
    last_namestringrequired

    Payee last name

    Possible values: Value must match regular expression /\A(?![ ])(?![ ]*$)[a-zA-Z0-9 ]*(?<![ ])\z/

    Example: Scarlet
    emailstringrequired

    If required_contact == true, this email must be the same email that was used to create the contact.

    amountnumberrequired

    Amount of each payout transaction. Optional with usdc_bank 's payout method name.

    Example: 100
    external_idstring

    Custom ID

    Example: 123
    payout_method_paramsobjectrequired

    Required parameters for each payout method name

    Example: {"account_number":123456789999,"account_name":"Luyx","bank_code":11111}
  • ]
    • currencystringrequired

    Currency for payout

    Example: PHP
    payout_method_namestringrequired

    Payout method name

    Example: ph_ewallet_gcash_php
    scheduled_atYYYY-MM-DDTHH:mm:ss

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

    Example: 2023-04-01T00:00:00
    descriptionstringrequired

    Description of payout payment

    Possible values: >= 5 characters

    Example: Payout payment 2023
    webhook_notification objectrequired
    endpoint_urlstringrequired

    An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.

    Example: https://example.org
    authorization_headerstringrequired

    The string that Hello Clever will put into the Authorization request header when calling the Callback url.

    Example: SECRET
    external_idstring

    Custom ID

    Example: 123

Responses​

OK

Schema
    uuidstringrequired

    Unique id in system.

    Example: OHXTEF9M
    currencystringrequired

    Currency payout

    Example: PHP
    payout_method_namestringrequired
    Example: ph_ewallet_gcash_php
    descriptionstring

    Description of payout payment.

    Possible values: non-empty and <= 90 characters

    Example: Payout payment 2023
    total_amountstringrequired

    Total amount of list payout transactions

    Example: 1000
    statusstringrequired

    Status of payout payment

    Possible values: [created, processing, scheduled, completed, expired]

    Example: completed
    webhook_notification object

    Merchant Callback Details

    endpoint_urlurl (endpoint_url)required

    An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.

    Example: https://example.org
    authorization_header(authorization_header)required

    The string which Hello Clever will put into the Authorization request header when calling the Callback url.

    Example: SECRET
    scheduled_atYYYY-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

  • Array [
    • uuidstringrequired

    Unique ID of the transaction

    Example: DQCJ7JJE
    balance_idstringnullable

    Balance ID for linked to the payout

    Example: null
    payeestringrequired

    Full name of the payee

    Example: Hello Clever Test
    emailemailrequired

    Payee email address

    Example: test@helloclever.co
    amountstringrequired

    Payout amount

    Example: 100.0
    payout_method_paramsobjectrequired

    Method-specific payout details

    Example: {"account_number":123456789999,"account_name":"Luyx","bank_code":11111}
    statusstringrequired

    Transaction status

    Example: created
    error_messagestringnullable
    Example: null
    referencestringnullable
    Example: null
    external_idstringnullable

    External custom reference

    Example: 123456
    created_atdate-time

    Timestamp when the transaction was created

    Example: 2025-03-07T06:47:27.069+0000
  • ]
    • error_codestring

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

    Possible values: [HC_PAYOUT1, HC_PAYOUT2]

    Example: HC_PAYOUT1
    error_messagestring

    A description corresponds to the value of the statusCode field.

    Possible values: [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_idstring

    Custom ID

    Example: 123

Callbacks​

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

If the merchant specifies values for the webhook_notification object during the Create a Payout invocation, then a notification will be sent to the merchant system when it's status has changed.

The event will use webhook_notification.endpoint_url as endpoint and webhook_notification.authorization_header as Authorization header. We strongly recommend to use a different value for authorization_header on each payment request to increase the level of security.

This call is made by Hello Clever on a best effort basis. Hello Clever will implement retry mechanisms to ensure transient network failures do not affect the ability to call this endpoint. Hello Clever may call this endpoint more than once with the same payload so the merchant must ensure that the endpoint is implemented with idempotent behaviour always returning a 200 OK response even after subsequent calls.

If the target endpoint does not return HTTP 200, Hello Clever will retry the webhook call 3 times with 15 minutes delay per call.

Body

    uuidstringrequired

    Unique id in system.

    Example: OHXTEF9M
    currencystringrequired

    Currency payout

    Example: PHP
    payout_method_namestringrequired
    Example: ph_ewallet_gcash_php
    descriptionstring

    Description of payout payment.

    Possible values: non-empty and <= 90 characters

    Example: Payout payment 2023
    total_amountstringrequired

    Total amount of list payout transactions

    Example: 1000
    statusstringrequired

    Status of payout payment

    Possible values: [created, processing, scheduled, completed, expired]

    Example: completed
    webhook_notification object

    Merchant Callback Details

    endpoint_urlurl (endpoint_url)required

    An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.

    Example: https://example.org
    authorization_header(authorization_header)required

    The string which Hello Clever will put into the Authorization request header when calling the Callback url.

    Example: SECRET
    scheduled_atYYYY-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

  • Array [
    • uuidstringrequired

    Unique ID of the transaction

    Example: DQCJ7JJE
    balance_idstringnullable

    Balance ID for linked to the payout

    Example: null
    payeestringrequired

    Full name of the payee

    Example: Hello Clever Test
    emailemailrequired

    Payee email address

    Example: test@helloclever.co
    amountstringrequired

    Payout amount

    Example: 100.0
    payout_method_paramsobjectrequired

    Method-specific payout details

    Example: {"account_number":123456789999,"account_name":"Luyx","bank_code":11111}
    statusstringrequired

    Transaction status

    Example: created
    error_messagestringnullable
    Example: null
    referencestringnullable
    Example: null
    external_idstring

    External custom reference

    Example: 123456
    created_atdate-time

    Timestamp when the transaction was created

    Example: 2025-03-07T06:47:27.069+0000
  • ]
    • error_codestring

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

    Possible values: [HC_PAYOUT1, HC_PAYOUT2]

    Example: HC_PAYOUT1
    error_messagestring

    A description corresponds to the value of the statusCode field.

    Possible values: [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_idstring

    Custom ID

    Example: 123

Authorization: app-id

name: app-idtype: apiKeydescription: The app-id is registered and secured inside Hello Clever system and only required when client has initiated or in the middle of the transaction.in: header
name: secret-keytype: apiKeydescription: The secret-key is our client's secret of the source. Required if a publishable key is used to retrieve the source.in: header
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cleverhub.co/api/v2/payouts");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var content = new StringContent("{\n  \"payout_transaction_details\": [\n    {\n      \"first_name\": \"John\",\n      \"last_name\": \"Scarlet\",\n      \"email\": \"string\",\n      \"amount\": 100,\n      \"external_id\": \"123\",\n      \"payout_method_params\": {\n        \"account_number\": 123456789999,\n        \"account_name\": \"Luyx\",\n        \"bank_code\": 11111\n      }\n    }\n  ],\n  \"currency\": \"PHP\",\n  \"payout_method_name\": \"ph_ewallet_gcash_php\",\n  \"scheduled_at\": \"2023-04-01T00:00:00\",\n  \"description\": \"Payout payment 2023\",\n  \"webhook_notification\": {\n    \"endpoint_url\": \"https://example.org\",\n    \"authorization_header\": \"SECRET\"\n  },\n  \"external_id\": \"123\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://api.cleverhub.co/api
Auth
Body
{
  "payout_transaction_details": [
    {
      "first_name": "John",
      "last_name": "Scarlet",
      "email": "string",
      "amount": 100,
      "external_id": "123",
      "payout_method_params": {
        "account_number": 123456789999,
        "account_name": "Luyx",
        "bank_code": 11111
      }
    }
  ],
  "currency": "PHP",
  "payout_method_name": "ph_ewallet_gcash_php",
  "scheduled_at": "2023-04-01T00:00:00",
  "description": "Payout payment 2023",
  "webhook_notification": {
    "endpoint_url": "https://example.org",
    "authorization_header": "SECRET"
  },
  "external_id": "123"
}
ResponseClear

Click the Send API Request button above and see the response here!