Create a Payout

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

Initiate a batch payout to multiple recipients using either PayID or BSB-enabled accounts. This API enables efficient bulk payment processing, allowing merchants to handle payouts to multiple recipients in a single request.

If a payout fails due to insufficient funds and the is_retry flag is set to true, the system will continue to attempt processing until sufficient funds become available, either through a balance top-up or new incoming payments.

Payment statuses:

• created: Payout created and pending further processing.
• processing: Payout has been topped up to the corresponding PayID and is currently being processed.
• scheduled: Waiting for funds to be debited from the payer's account; the payout is scheduled but not yet executed.
• completed: Payout completed successfully for the entire batch. Note that individual transaction failures do not affect the completion status of the overall batch.

Important notes:

• If using a phone number as the PayID, prefix it with the country code, separated by a dash. For example: +61-412345678.
• PayIDs using email addresses must be in lowercase (e.g., johnwick@gmail.com).
• Either payid or both bsb and account_number are required. You cannot use both payid and bsb/account_number in the same request for a single transaction.

Request

application/json

Bodyrequired

payout_transaction_details object[]required
List of payout transaction details.
Array [
payeestringrequired
Full name of the payee.
Possible values: Value must match regular expression ^(?![!])(?<![!])^[a-zA-Z0-9 ']*$
Example: John Doe
addressstring
Full address of the payee.
Example: 123 Example Street, Sydney, NSW 2000
emailstringrequired
Payee's email address (required).
Example: john.doe@example.com
amountnumberrequired
The payout amount for this transaction.
Example: 150
payidstring
The payee's PayID (required if bsb and account_number are not provided).
Example: john.doe@example.com
payid_typestring
Type of PayID.
• email: Email address.
• phone: Phone number with country code. For example, +61-412345678
• abn: Australian Business Number.
Possible values: [email, phone, abn]
Example: email
bsbstring
The BSB number, required if payid is not provided.
Example: 123456
account_numberstring
The payee's account number, required if payid is not provided.
Example: 987654321
]
scheduled_atdate-timerequired
Scheduled date and time for the payout transaction. This date-time is in UTC.
Example: 2024-01-01T10:00:00
descriptionstringrequired
Brief description of the payout purpose.
Possible values: >= 5 characters and <= 140 characters
Example: Monthly payout for January
is_retryboolean
Indicates if the system should retry the payout in case of insufficient funds. Default is false. If set to true, the system will continue to try until the balance is sufficient, either through top-up or new payments.
Default value: false
Example: true
external_idstring
A custom identifier provided by the merchant for tracking purposes.
Example: custom-payout-id-123
endpoint_urlurirequired
URL that Hello Clever will invoke when the status of the transaction changes. The client must expose a TLS 1.2-secured endpoint with a certificate from a well-known commercial certificate authority. Self-signed or internally signed certificates are not accepted.
Example: https://merchant.example.com/payout_status_callback
authorization_headerstring
Authorization header value for securing the callback request to the specified endpoint.
Example: Bearer your_secret_token

Responses

200

Payout batch created successfully.

application/json

Schema

Schema

idinteger
A unique identifier assigned to the payout payment, used for tracking and referencing purposes within the system.
Example: 12345
uuidstring
A unique UUID assigned to the payout payment, providing a globally unique reference for the transaction.
Example: 550e8400-e29b-41d4-a716-446655440000
descriptionstring
A description of the payout payment, providing context or additional information such as the purpose of the payout.
Example: Payout for invoice #12345
payidstring
The PayID used for topping up the payout payment, allowing for easy routing of funds to the correct recipient.
Example: sample@payid.com
total_amountstring
The total amount of all transactions included in the payout, providing the complete value being paid out.
Example: 1000.00
total_refundstring
The total amount that has been refunded to the payee, if applicable.
Example: 100.00
total_failed_transactionsstring
The total number of transactions within the payout that failed to complete successfully.
Example: 2
scheduled_atdate-time
The date and time when the payout transaction is scheduled to occur, expressed in UTC.
Example: 2024-12-31T23:59:59Z
statusstring
The current status of the payout payment. Possible values include:
• created: The payout has been created but not yet processed.
• processing: The payout is currently being processed.
• scheduled: The payout is scheduled for a future date.
• completed: The payout has been completed successfully.
• expired: The payout has expired.
Possible values: [created, processing, scheduled, completed, expired]
Example: processing
export_urluri
A URL for downloading an attachment related to the payout payment, such as a receipt or transaction details.
Example: https://example.com/download/payout_attachment
payout_notification object
Details regarding the merchant callback settings for payout status updates, including the endpoint URL and authorization header.
endpoint_urluri
An internet-accessible URL that will be invoked when the status of the payout changes, allowing the merchant to receive real-time updates.
Example: https://merchant.com/payout_callback
authorization_headerstring
The authorization header value to be used in the callback request, helping ensure the request is authenticated.
Example: Bearer your_token
error_codestring
An error code associated with the payout, indicating any issues that occurred during processing.
Example: HC_PAYOUT1
error_messagestring
A description of the error encountered during the payout process, providing context for troubleshooting.
Example: Insufficient funds to payout. Please top up balance in the dashboard.
is_retryboolean
Indicates whether the payout is being retried after a previous failure.
Example: false
external_idstring
A custom identifier for the payout, provided by the merchant for tracking and reference purposes.
Example: custom-payout-id-6789
payout_transactions object[]
A list of individual transactions that are part of the payout, including details such as payee information and transaction status.
Array [
idinteger
A unique identifier assigned to the payout transaction, used for tracking and referencing purposes.
Example: 123
balance_idstring
The UUID of the balance transaction associated with the payout, providing a reference to the specific balance movement.
Example: 550e8400-e29b-41d4-a716-446655441111
payeestring
The name of the payee receiving the payout, used to identify the recipient of the funds.
Example: John Doe
payidstring
The PayID of the payee, used to route the payout to the correct recipient.
Example: payee@payid.com
payid_typestring
The type of PayID being used by the payee. Valid values include:
• EMAIL: An email address.
• PHONE: A phone number.
• ABN: An Australian Business Number.
Possible values: [EMAIL, PHONE, ABN]
Example: EMAIL
bsbstring
The Bank-State-Branch (BSB) number of the payee's account, used to identify the bank and branch for the transaction.
Example: 123456
account_numberstring
The account number of the payee, used to route the payout to the correct bank account.
Example: 987654321
amountstring
The amount being paid to the payee as part of the payout transaction.
Example: 500.00
statusstring
The current status of the payout transaction. Possible values include:
• created: The transaction has been created but not yet processed.
• processing: The transaction is currently being processed.
• settled: The transaction has been completed successfully.
• failed: The transaction failed to complete successfully.
Possible values: [created, processing, settled, failed]
Example: settled
error_messagestring
An error message providing details about why the payout transaction failed, if applicable.
Example: Payment failed due to insufficient funds.
created_atdate-time
The date and time when the payout transaction was created, expressed in UTC.
Example: 2024-01-01T00:00:00Z
]

Example (auto)

{
  "id": 12345,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Payout for invoice #12345",
  "payid": "sample@payid.com",
  "total_amount": "1000.00",
  "total_refund": "100.00",
  "total_failed_transactions": "2",
  "scheduled_at": "2024-12-31T23:59:59Z",
  "status": "processing",
  "export_url": "https://example.com/download/payout_attachment",
  "payout_notification": {
    "endpoint_url": "https://merchant.com/payout_callback",
    "authorization_header": "Bearer your_token"
  },
  "error_code": "HC_PAYOUT1",
  "error_message": "Insufficient funds to payout. Please top up balance in the dashboard.",
  "is_retry": false,
  "external_id": "custom-payout-id-6789",
  "payout_transactions": [
    {
      "id": 123,
      "balance_id": "550e8400-e29b-41d4-a716-446655441111",
      "payee": "John Doe",
      "payid": "payee@payid.com",
      "payid_type": "EMAIL",
      "bsb": "123456",
      "account_number": "987654321",
      "amount": "500.00",
      "status": "settled",
      "error_message": "Payment failed due to insufficient funds.",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

400

Bad Request

401

Unauthorized

404

Not Found

422

Unprocessable Entity

Callbacks

POST payoutCallback

POST 
{$request.body#/endpoint_url}

application/json

Body

PayoutObject

idinteger
A unique identifier assigned to the payout payment, used for tracking and referencing purposes within the system.
Example: 12345
uuidstring
A unique UUID assigned to the payout payment, providing a globally unique reference for the transaction.
Example: 550e8400-e29b-41d4-a716-446655440000
descriptionstring
A description of the payout payment, providing context or additional information such as the purpose of the payout.
Example: Payout for invoice #12345
payidstring
The PayID used for topping up the payout payment, allowing for easy routing of funds to the correct recipient.
Example: sample@payid.com
total_amountstring
The total amount of all transactions included in the payout, providing the complete value being paid out.
Example: 1000.00
total_refundstring
The total amount that has been refunded to the payee, if applicable.
Example: 100.00
total_failed_transactionsstring
The total number of transactions within the payout that failed to complete successfully.
Example: 2
scheduled_atdate-time
The date and time when the payout transaction is scheduled to occur, expressed in UTC.
Example: 2024-12-31T23:59:59Z
statusstring
The current status of the payout payment. Possible values include:
• created: The payout has been created but not yet processed.
• processing: The payout is currently being processed.
• scheduled: The payout is scheduled for a future date.
• completed: The payout has been completed successfully.
• expired: The payout has expired.
Possible values: [created, processing, scheduled, completed, expired]
Example: processing
export_urluri
A URL for downloading an attachment related to the payout payment, such as a receipt or transaction details.
Example: https://example.com/download/payout_attachment
payout_notification object
Details regarding the merchant callback settings for payout status updates, including the endpoint URL and authorization header.
endpoint_urluri
An internet-accessible URL that will be invoked when the status of the payout changes, allowing the merchant to receive real-time updates.
Example: https://merchant.com/payout_callback
authorization_headerstring
The authorization header value to be used in the callback request, helping ensure the request is authenticated.
Example: Bearer your_token
error_codestring
An error code associated with the payout, indicating any issues that occurred during processing.
Example: HC_PAYOUT1
error_messagestring
A description of the error encountered during the payout process, providing context for troubleshooting.
Example: Insufficient funds to payout. Please top up balance in the dashboard.
is_retryboolean
Indicates whether the payout is being retried after a previous failure.
Example: false
external_idstring
A custom identifier for the payout, provided by the merchant for tracking and reference purposes.
Example: custom-payout-id-6789
payout_transactions object[]
A list of individual transactions that are part of the payout, including details such as payee information and transaction status.
Array [
idinteger
A unique identifier assigned to the payout transaction, used for tracking and referencing purposes.
Example: 123
balance_idstring
The UUID of the balance transaction associated with the payout, providing a reference to the specific balance movement.
Example: 550e8400-e29b-41d4-a716-446655441111
payeestring
The name of the payee receiving the payout, used to identify the recipient of the funds.
Example: John Doe
payidstring
The PayID of the payee, used to route the payout to the correct recipient.
Example: payee@payid.com
payid_typestring
The type of PayID being used by the payee. Valid values include:
• EMAIL: An email address.
• PHONE: A phone number.
• ABN: An Australian Business Number.
Possible values: [EMAIL, PHONE, ABN]
Example: EMAIL
bsbstring
The Bank-State-Branch (BSB) number of the payee's account, used to identify the bank and branch for the transaction.
Example: 123456
account_numberstring
The account number of the payee, used to route the payout to the correct bank account.
Example: 987654321
amountstring
The amount being paid to the payee as part of the payout transaction.
Example: 500.00
statusstring
The current status of the payout transaction. Possible values include:
• created: The transaction has been created but not yet processed.
• processing: The transaction is currently being processed.
• settled: The transaction has been completed successfully.
• failed: The transaction failed to complete successfully.
Possible values: [created, processing, settled, failed]
Example: settled
error_messagestring
An error message providing details about why the payout transaction failed, if applicable.
Example: Payment failed due to insufficient funds.
created_atdate-time
The date and time when the payout transaction was created, expressed in UTC.
Example: 2024-01-01T00:00:00Z
]

Callbacks Responses

200

Callback received successfully

400

Bad request

401

Unauthorized

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cleverhub.co/api/v1/payouts");
request.Headers.Add("Accept", "application/json");
var content = new StringContent("{\n  \"payout_transaction_details\": [\n    {\n      \"payee\": \"John Doe\",\n      \"address\": \"123 Example Street, Sydney, NSW 2000\",\n      \"email\": \"john.doe@example.com\",\n      \"amount\": 150,\n      \"payid\": \"john.doe@example.com\",\n      \"payid_type\": \"email\",\n      \"bsb\": \"123456\",\n      \"account_number\": \"987654321\"\n    }\n  ],\n  \"scheduled_at\": \"2024-01-01T10:00:00\",\n  \"description\": \"Monthly payout for January\",\n  \"is_retry\": true,\n  \"external_id\": \"custom-payout-id-123\",\n  \"endpoint_url\": \"https://merchant.example.com/payout_status_callback\",\n  \"authorization_header\": \"Bearer your_secret_token\"\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

Body required

{
  "payout_transaction_details": [
    {
      "payee": "John Doe",
      "address": "123 Example Street, Sydney, NSW 2000",
      "email": "john.doe@example.com",
      "amount": 150,
      "payid": "john.doe@example.com",
      "payid_type": "email",
      "bsb": "123456",
      "account_number": "987654321"
    }
  ],
  "scheduled_at": "2024-01-01T10:00:00",
  "description": "Monthly payout for January",
  "is_retry": true,
  "external_id": "custom-payout-id-123",
  "endpoint_url": "https://merchant.example.com/payout_status_callback",
  "authorization_header": "Bearer your_secret_token"
}

ResponseClear

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