Create Payout Batch via File

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

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

Request

multipart/form-data

Bodyrequired

filebinaryrequired
The file containing payout details. Supported formats are .csv or .xlsx. You can download an example file at this link.
scheduled_atdate-timerequired
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
descriptionstringrequired
Brief description of the payout purpose.
Possible values: >= 5 characters and <= 140 characters
Example: Monthly salary payout for January
is_retryboolean
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.
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_headerstringrequired
The authorization header value that Hello Clever will include in the callback request for security.
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(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("multipart/form-data");
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

filerequired

The file containing payout details. Supported formats are `.csv` or `.xlsx`. You can download an example file at [this link](https://helloclever.co/static/assets/payout/post-request-example.zip).

scheduled_atrequired

descriptionrequired

is_retry

external_id

endpoint_urlrequired

authorization_headerrequired

ResponseClear

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