Create One-Time PayID
Generate a unique, one-time-use PayID for processing a single payment transaction. This endpoint creates a secure PayID that the customer can use to complete a payment, allowing merchants to receive funds directly.
Once a payment is initiated, the payment_request_notification object can be configured to provide real-time status updates via a callback to a specified endpoint, ensuring that merchants receive notifications for every change in the transaction’s status.
curl --request POST \
--url https://api.cleverhub.co/api/v1/merchants/create_payment \
--header 'Content-Type: application/json' \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>' \
--data '
{
"name": "John Doe",
"gst": true,
"amount": 100,
"description": "Payment for invoice #1234",
"emails": "customer@example.com",
"payment_request_notification": {
"endpoint_url": "https://example.com/payment_callback",
"authorization_header": "Bearer your_token"
},
"prefix_static_payid": "abc",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"metadata": {
"custom_note": "Priority customer"
}
}
'import requests
url = "https://api.cleverhub.co/api/v1/merchants/create_payment"
payload = {
"name": "John Doe",
"gst": True,
"amount": 100,
"description": "Payment for invoice #1234",
"emails": "customer@example.com",
"payment_request_notification": {
"endpoint_url": "https://example.com/payment_callback",
"authorization_header": "Bearer your_token"
},
"prefix_static_payid": "abc",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"metadata": { "custom_note": "Priority customer" }
}
headers = {
"app-id": "<api-key>",
"secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'app-id': '<api-key>',
'secret-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'John Doe',
gst: true,
amount: 100,
description: 'Payment for invoice #1234',
emails: 'customer@example.com',
payment_request_notification: {
endpoint_url: 'https://example.com/payment_callback',
authorization_header: 'Bearer your_token'
},
prefix_static_payid: 'abc',
expired_at: '2024-12-31T23:59:59Z',
external_id: 'custom-id-12345',
metadata: {custom_note: 'Priority customer'}
})
};
fetch('https://api.cleverhub.co/api/v1/merchants/create_payment', 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/merchants/create_payment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'John Doe',
'gst' => true,
'amount' => 100,
'description' => 'Payment for invoice #1234',
'emails' => 'customer@example.com',
'payment_request_notification' => [
'endpoint_url' => 'https://example.com/payment_callback',
'authorization_header' => 'Bearer your_token'
],
'prefix_static_payid' => 'abc',
'expired_at' => '2024-12-31T23:59:59Z',
'external_id' => 'custom-id-12345',
'metadata' => [
'custom_note' => 'Priority customer'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"app-id: <api-key>",
"secret-key: <api-key>"
],
]);
$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/merchants/create_payment"
payload := strings.NewReader("{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("app-id", "<api-key>")
req.Header.Add("secret-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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/merchants/create_payment")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/merchants/create_payment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123456,
"uuid": "pi_as2ks12xa2",
"balance_id": "HDCHJSS",
"name": "John Doe",
"request_payid": "payid123@example.com",
"merchant_name": "Merchant Co.",
"gst": true,
"amount": "100.0",
"total": "110.0",
"gst_amount": "10.0",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"cashback_amount": "5.0",
"pay_by": "2024-12-30T23:59:59Z",
"paid_at": "2024-12-25T12:34:56Z",
"status": "pending",
"description": "Payment for invoice #1234",
"nonce": "unique_nonce_string",
"stage": "overpaid",
"refund_information": {
"refund_payid": "sample@payid.com",
"refund_amount": 0.1,
"request_date": "2024-12-31T23:59:59Z",
"reason": "Broken product"
},
"refund_records": [
{
"uuid": "rf_as231sdas12",
"status": "return_pending",
"refund_amount": 0.1,
"request_date": "2024-12-31T23:59:59Z",
"reason": "Broken product"
}
],
"sender_details": {
"reference": "SenderRef123",
"description": "Payment from John Doe",
"bsb": "123456",
"account_number": "987654321",
"account_name": "John Doe"
},
"short_invoice_url": "https://short.example.com/invoice/123456",
"invoice_url": "https://example.com/invoice/123456",
"metadata": {
"custom_note": "Priority customer"
}
}Authorizations
A unique identifier assigned to each application.
A secure token associated with the app-id.
Body
Customer's full name.
"John Doe"
Indicates if Goods and Services Tax (GST) applies for Australian merchants.
true
The total payment amount for the transaction in AUD.
100
Brief description of the payment purpose.
"Payment for invoice #1234"
Comma-separated list of email addresses for notifications. Only lowercase letters are allowed.
^([a-z0-9_\-\.]+)@([a-z]+)\.([a-z]+)(,[a-z0-9_\-\.]+@[a-z]+\.([a-z]+))*$"customer@example.com"
Details for merchant callback notifications when the payment status changes.
Show child attributes
Show child attributes
Static prefix for the PayID, used to generate a PayID in the format prefix_static_payid@example.co.
^(?=[a-z0-9]{3,35}$)[a-z0-9]*$"abc"
Expiration time of the PayID in UTC format. Should be at least 15 minutes from the current time.
"2024-12-31T23:59:59Z"
Custom identifier for tracking purposes, set by the merchant.
"custom-id-12345"
Optional custom metadata to attach to the transaction.
{ "custom_note": "Priority customer" }
Callbacks
POST{$request.body#/payment_request_notification.endpoint_url}statusChange
Body
A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system.
123456
The UUID assigned to the payment, providing a globally unique reference for the payment request.
"pi_as2ks12xa2"
The identifier of the balance associated with this payment request, allowing for account management and tracking of specific transactions.
"HDCHJSS"
The name of the individual or entity associated with the payment request. This helps identify the payer or payee involved.
"John Doe"
The PayID generated for the payment request, used to uniquely identify and route the payment to the correct recipient.
"payid123@example.com"
The name of the merchant managing or handling the payment. This field is useful for recognising the party to whom the payment is being made.
"Merchant Co."
Indicates whether Goods and Services Tax (GST) applies to the transaction. A value of true means GST is included.
true
The amount requested for the payment, excluding any applicable taxes. This field represents the base value of the transaction.
"100.0"
The total amount due, including all applicable taxes such as GST. This is the final amount the payer needs to pay.
"110.0"
The portion of the total amount that is attributable to GST. This helps in breaking down the tax components of the payment.
"10.0"
The expiration date and time of the PayID, indicating until when the PayID is valid for making the payment.
"2024-12-31T23:59:59Z"
A custom identifier provided for tracking purposes, such as an internal reference or an invoice number.
"custom-id-12345"
The cashback amount, if applicable, that the payer is eligible to receive as part of the transaction.
"5.0"
The last date by which the payment must be made. This provides a clear deadline for the payer.
"2024-12-30T23:59:59Z"
The date and time when the payment was successfully completed. This is used for record-keeping and verification.
"2024-12-25T12:34:56Z"
The current status of the payment request. Possible values include:
pending: The payment request is still open and awaiting payment.received: The payment has been received.expired: The payment request has expired.return_pending: A return of funds is in process.return_received: Returned funds have been received.return_expired: The return process has expired.return_rejected: The return request was rejected.partially_refunded: Part of the payment has been refunded. Further refunds can be requested until the full amount is refunded.
pending, received, expired, return_pending, return_received, return_expired, return_rejected, partially_refunded "pending"
A description accompanying the payment request, providing additional information such as the purpose of the payment or related invoice details.
"Payment for invoice #1234"
A unique value used to validate the transaction, preventing replay attacks and ensuring the integrity of the payment request.
"unique_nonce_string"
Represents the specific stage within the pending status. This value is null unless the transaction is flagged for being overpaid, underpaid, or having an unmatched nonce.
overpaid, underpaid, unmatched_nonce, null "overpaid"
Details about any refunds that are associated with this payment. This includes information about the refund PayID, refund amount, and any reasons provided. Note: this field is deprecated and will be removed in a few upcoming versions. Use refund_records instead.
Show child attributes
Show child attributes
A list of refund records associated with this payment request, replacing refund_information. Each entry details the refund amount, request date, and reason.
Show child attributes
Show child attributes
Information about the sender of the payment, including reference details, bank information, and account holder's name.
Show child attributes
Show child attributes
A shortened version of the invoice URL for convenience. This can be used to quickly share or access the invoice details. Note: this field is deprecated.
"https://short.example.com/invoice/123456"
The full URL of the invoice related to the payment request. This provides access to the detailed invoice online. Note: this field is deprecated.
"https://example.com/invoice/123456"
Optional custom metadata to attach to the transaction.
{ "custom_note": "Priority customer" }
Response
Callback received successfully.
Response
Payment request created successfully.
A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system.
123456
The UUID assigned to the payment, providing a globally unique reference for the payment request.
"pi_as2ks12xa2"
The identifier of the balance associated with this payment request, allowing for account management and tracking of specific transactions.
"HDCHJSS"
The name of the individual or entity associated with the payment request. This helps identify the payer or payee involved.
"John Doe"
The PayID generated for the payment request, used to uniquely identify and route the payment to the correct recipient.
"payid123@example.com"
The name of the merchant managing or handling the payment. This field is useful for recognising the party to whom the payment is being made.
"Merchant Co."
Indicates whether Goods and Services Tax (GST) applies to the transaction. A value of true means GST is included.
true
The amount requested for the payment, excluding any applicable taxes. This field represents the base value of the transaction.
"100.0"
The total amount due, including all applicable taxes such as GST. This is the final amount the payer needs to pay.
"110.0"
The portion of the total amount that is attributable to GST. This helps in breaking down the tax components of the payment.
"10.0"
The expiration date and time of the PayID, indicating until when the PayID is valid for making the payment.
"2024-12-31T23:59:59Z"
A custom identifier provided for tracking purposes, such as an internal reference or an invoice number.
"custom-id-12345"
The cashback amount, if applicable, that the payer is eligible to receive as part of the transaction.
"5.0"
The last date by which the payment must be made. This provides a clear deadline for the payer.
"2024-12-30T23:59:59Z"
The date and time when the payment was successfully completed. This is used for record-keeping and verification.
"2024-12-25T12:34:56Z"
The current status of the payment request. Possible values include:
pending: The payment request is still open and awaiting payment.received: The payment has been received.expired: The payment request has expired.return_pending: A return of funds is in process.return_received: Returned funds have been received.return_expired: The return process has expired.return_rejected: The return request was rejected.partially_refunded: Part of the payment has been refunded. Further refunds can be requested until the full amount is refunded.
pending, received, expired, return_pending, return_received, return_expired, return_rejected, partially_refunded "pending"
A description accompanying the payment request, providing additional information such as the purpose of the payment or related invoice details.
"Payment for invoice #1234"
A unique value used to validate the transaction, preventing replay attacks and ensuring the integrity of the payment request.
"unique_nonce_string"
Represents the specific stage within the pending status. This value is null unless the transaction is flagged for being overpaid, underpaid, or having an unmatched nonce.
overpaid, underpaid, unmatched_nonce, null "overpaid"
Details about any refunds that are associated with this payment. This includes information about the refund PayID, refund amount, and any reasons provided. Note: this field is deprecated and will be removed in a few upcoming versions. Use refund_records instead.
Show child attributes
Show child attributes
A list of refund records associated with this payment request, replacing refund_information. Each entry details the refund amount, request date, and reason.
Show child attributes
Show child attributes
Information about the sender of the payment, including reference details, bank information, and account holder's name.
Show child attributes
Show child attributes
A shortened version of the invoice URL for convenience. This can be used to quickly share or access the invoice details. Note: this field is deprecated.
"https://short.example.com/invoice/123456"
The full URL of the invoice related to the payment request. This provides access to the detailed invoice online. Note: this field is deprecated.
"https://example.com/invoice/123456"
Optional custom metadata to attach to the transaction.
{ "custom_note": "Priority customer" }
curl --request POST \
--url https://api.cleverhub.co/api/v1/merchants/create_payment \
--header 'Content-Type: application/json' \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>' \
--data '
{
"name": "John Doe",
"gst": true,
"amount": 100,
"description": "Payment for invoice #1234",
"emails": "customer@example.com",
"payment_request_notification": {
"endpoint_url": "https://example.com/payment_callback",
"authorization_header": "Bearer your_token"
},
"prefix_static_payid": "abc",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"metadata": {
"custom_note": "Priority customer"
}
}
'import requests
url = "https://api.cleverhub.co/api/v1/merchants/create_payment"
payload = {
"name": "John Doe",
"gst": True,
"amount": 100,
"description": "Payment for invoice #1234",
"emails": "customer@example.com",
"payment_request_notification": {
"endpoint_url": "https://example.com/payment_callback",
"authorization_header": "Bearer your_token"
},
"prefix_static_payid": "abc",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"metadata": { "custom_note": "Priority customer" }
}
headers = {
"app-id": "<api-key>",
"secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'app-id': '<api-key>',
'secret-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'John Doe',
gst: true,
amount: 100,
description: 'Payment for invoice #1234',
emails: 'customer@example.com',
payment_request_notification: {
endpoint_url: 'https://example.com/payment_callback',
authorization_header: 'Bearer your_token'
},
prefix_static_payid: 'abc',
expired_at: '2024-12-31T23:59:59Z',
external_id: 'custom-id-12345',
metadata: {custom_note: 'Priority customer'}
})
};
fetch('https://api.cleverhub.co/api/v1/merchants/create_payment', 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/merchants/create_payment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'John Doe',
'gst' => true,
'amount' => 100,
'description' => 'Payment for invoice #1234',
'emails' => 'customer@example.com',
'payment_request_notification' => [
'endpoint_url' => 'https://example.com/payment_callback',
'authorization_header' => 'Bearer your_token'
],
'prefix_static_payid' => 'abc',
'expired_at' => '2024-12-31T23:59:59Z',
'external_id' => 'custom-id-12345',
'metadata' => [
'custom_note' => 'Priority customer'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"app-id: <api-key>",
"secret-key: <api-key>"
],
]);
$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/merchants/create_payment"
payload := strings.NewReader("{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("app-id", "<api-key>")
req.Header.Add("secret-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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/merchants/create_payment")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/merchants/create_payment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"John Doe\",\n \"gst\": true,\n \"amount\": 100,\n \"description\": \"Payment for invoice #1234\",\n \"emails\": \"customer@example.com\",\n \"payment_request_notification\": {\n \"endpoint_url\": \"https://example.com/payment_callback\",\n \"authorization_header\": \"Bearer your_token\"\n },\n \"prefix_static_payid\": \"abc\",\n \"expired_at\": \"2024-12-31T23:59:59Z\",\n \"external_id\": \"custom-id-12345\",\n \"metadata\": {\n \"custom_note\": \"Priority customer\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123456,
"uuid": "pi_as2ks12xa2",
"balance_id": "HDCHJSS",
"name": "John Doe",
"request_payid": "payid123@example.com",
"merchant_name": "Merchant Co.",
"gst": true,
"amount": "100.0",
"total": "110.0",
"gst_amount": "10.0",
"expired_at": "2024-12-31T23:59:59Z",
"external_id": "custom-id-12345",
"cashback_amount": "5.0",
"pay_by": "2024-12-30T23:59:59Z",
"paid_at": "2024-12-25T12:34:56Z",
"status": "pending",
"description": "Payment for invoice #1234",
"nonce": "unique_nonce_string",
"stage": "overpaid",
"refund_information": {
"refund_payid": "sample@payid.com",
"refund_amount": 0.1,
"request_date": "2024-12-31T23:59:59Z",
"reason": "Broken product"
},
"refund_records": [
{
"uuid": "rf_as231sdas12",
"status": "return_pending",
"refund_amount": 0.1,
"request_date": "2024-12-31T23:59:59Z",
"reason": "Broken product"
}
],
"sender_details": {
"reference": "SenderRef123",
"description": "Payment from John Doe",
"bsb": "123456",
"account_number": "987654321",
"account_name": "John Doe"
},
"short_invoice_url": "https://short.example.com/invoice/123456",
"invoice_url": "https://example.com/invoice/123456",
"metadata": {
"custom_note": "Priority customer"
}
}