AUD Payout

Create Payout Batch via File

This API enables you to create a batch payout to PayID or NPP-enabled BSB accounts by uploading a file containing payout details, facilitating bulk payment processing to multiple recipients efficiently.

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

Payment statuses:

created: Payout payment 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 payment has been 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).

POST

payouts

Create Payout Batch via File

curl --request POST \
  --url https://api.cleverhub.co/api/v1/payouts/ \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form scheduled_at=2024-01-01T10:00:00 \
  --form 'description=Monthly salary payout for January' \
  --form endpoint_url=https://merchant.example.com/payout_status_callback \
  --form 'authorization_header=Bearer your_secret_token' \
  --form is_retry=true \
  --form external_id=custom-payout-id-123

import requests

url = "https://api.cleverhub.co/api/v1/payouts/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "scheduled_at": "2024-01-01T10:00:00",
    "description": "Monthly salary payout for January",
    "endpoint_url": "https://merchant.example.com/payout_status_callback",
    "authorization_header": "Bearer your_secret_token",
    "is_retry": "true",
    "external_id": "custom-payout-id-123"
}

response = requests.post(url, data=payload, files=files)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('scheduled_at', '2024-01-01T10:00:00');
form.append('description', 'Monthly salary payout for January');
form.append('endpoint_url', 'https://merchant.example.com/payout_status_callback');
form.append('authorization_header', 'Bearer your_secret_token');
form.append('is_retry', 'true');
form.append('external_id', 'custom-payout-id-123');

const options = {method: 'POST'};

options.body = form;

fetch('https://api.cleverhub.co/api/v1/payouts/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cleverhub.co/api/v1/payouts/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cleverhub.co/api/v1/payouts/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cleverhub.co/api/v1/payouts/")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cleverhub.co/api/v1/payouts/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

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

Body

multipart/form-data

file

required

The file containing payout details. Supported formats are .csv or .xlsx. You can download an example file at this link.

scheduled_at

string<date-time>

required

The scheduled date and time for the payout transaction in UTC. Format should be YYYY-MM-DDTHH:mm:ss.

Example:

"2024-01-01T10:00:00"

description

string

required

Brief description of the payout purpose.

Required string length: 5 - 140

Example:

"Monthly salary payout for January"

endpoint_url

string<uri>

required

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_header

string

required

The authorization header value that Hello Clever will include in the callback request for security.

Example:

"Bearer your_secret_token"

is_retry

boolean

default:false

If set to true, the system will attempt to retry the payout in case of insufficient funds, processing it once funds are available. Default is false.

Example:

true

external_id

string

A custom identifier provided by the merchant for tracking purposes.

Example:

"custom-payout-id-123"

Callbacks

POST

{$request.body#/endpoint_url}payoutCallback

Body

application/json

PayoutObject

integer

A unique identifier assigned to the payout payment, used for tracking and referencing purposes within the system.

Example:

12345

uuid

string

A unique UUID assigned to the payout payment, providing a globally unique reference for the transaction.

Example:

"550e8400-e29b-41d4-a716-446655440000"

description

string

A description of the payout payment, providing context or additional information such as the purpose of the payout.

Example:

"Payout for invoice #12345"

payid

string

The PayID used for topping up the payout payment, allowing for easy routing of funds to the correct recipient.

Example:

"sample@payid.com"

total_amount

string

The total amount of all transactions included in the payout, providing the complete value being paid out.

Example:

"1000.00"

total_refund

string

The total amount that has been refunded to the payee, if applicable.

Example:

"100.00"

total_failed_transactions

string

The total number of transactions within the payout that failed to complete successfully.

Example:

"2"

scheduled_at

string<date-time>

The date and time when the payout transaction is scheduled to occur, expressed in UTC.

Example:

"2024-12-31T23:59:59Z"

status

enum<string>

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.

Available options:

created,

processing,

scheduled,

completed,

expired

Example:

"processing"

export_url

string<uri>

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.

Show child attributes

error_code

string

An error code associated with the payout, indicating any issues that occurred during processing.

Example:

"HC_PAYOUT1"

error_message

string

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_retry

boolean

Indicates whether the payout is being retried after a previous failure.

Example:

false

external_id

string

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.

Show child attributes

Response

Callback received successfully

Response

Payout batch created successfully.

integer

A unique identifier assigned to the payout payment, used for tracking and referencing purposes within the system.

Example:

12345

uuid

string

A unique UUID assigned to the payout payment, providing a globally unique reference for the transaction.

Example:

"550e8400-e29b-41d4-a716-446655440000"

description

string

A description of the payout payment, providing context or additional information such as the purpose of the payout.

Example:

"Payout for invoice #12345"

payid

string

The PayID used for topping up the payout payment, allowing for easy routing of funds to the correct recipient.

Example:

"sample@payid.com"

total_amount

string

The total amount of all transactions included in the payout, providing the complete value being paid out.

Example:

"1000.00"

total_refund

string

The total amount that has been refunded to the payee, if applicable.

Example:

"100.00"

total_failed_transactions

string

The total number of transactions within the payout that failed to complete successfully.

Example:

"2"

scheduled_at

string<date-time>

The date and time when the payout transaction is scheduled to occur, expressed in UTC.

Example:

"2024-12-31T23:59:59Z"

status

enum<string>

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.

Available options:

created,

processing,

scheduled,

completed,

expired

Example:

"processing"

export_url

string<uri>

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.

Show child attributes

error_code

string

An error code associated with the payout, indicating any issues that occurred during processing.

Example:

"HC_PAYOUT1"

error_message

string

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_retry

boolean

Indicates whether the payout is being retried after a previous failure.

Example:

false

external_id

string

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.

Show child attributes

Get Payout List

Cancel Scheduled Payout

Create Payout Batch via File

curl --request POST \
  --url https://api.cleverhub.co/api/v1/payouts/ \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form scheduled_at=2024-01-01T10:00:00 \
  --form 'description=Monthly salary payout for January' \
  --form endpoint_url=https://merchant.example.com/payout_status_callback \
  --form 'authorization_header=Bearer your_secret_token' \
  --form is_retry=true \
  --form external_id=custom-payout-id-123

import requests

url = "https://api.cleverhub.co/api/v1/payouts/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "scheduled_at": "2024-01-01T10:00:00",
    "description": "Monthly salary payout for January",
    "endpoint_url": "https://merchant.example.com/payout_status_callback",
    "authorization_header": "Bearer your_secret_token",
    "is_retry": "true",
    "external_id": "custom-payout-id-123"
}

response = requests.post(url, data=payload, files=files)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('scheduled_at', '2024-01-01T10:00:00');
form.append('description', 'Monthly salary payout for January');
form.append('endpoint_url', 'https://merchant.example.com/payout_status_callback');
form.append('authorization_header', 'Bearer your_secret_token');
form.append('is_retry', 'true');
form.append('external_id', 'custom-payout-id-123');

const options = {method: 'POST'};

options.body = form;

fetch('https://api.cleverhub.co/api/v1/payouts/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cleverhub.co/api/v1/payouts/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cleverhub.co/api/v1/payouts/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cleverhub.co/api/v1/payouts/")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cleverhub.co/api/v1/payouts/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"scheduled_at\"\r\n\r\n2024-01-01T10:00:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nMonthly salary payout for January\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"endpoint_url\"\r\n\r\nhttps://merchant.example.com/payout_status_callback\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"authorization_header\"\r\n\r\nBearer your_secret_token\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"is_retry\"\r\n\r\ntrue\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"external_id\"\r\n\r\ncustom-payout-id-123\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

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

Overview

Payment Gateway (AUD)

Multi-currency Payment APIs

Multi-currency Gateway

Card API

Cashback API

Create Payout Batch via File

Body

Callbacks

Body

Response

Response