Create One-Time PayID

POST 
https://api.cleverhub.co/api/v1/merchants/create_payment

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.

Request

application/json

Bodyrequired

namestringrequired
Customer's full name.
Example: John Doe
gstbooleanrequired
Indicates if Goods and Services Tax (GST) applies for Australian merchants.
Example: true
amountnumberrequired
The total payment amount for the transaction in AUD.
Example: 100
descriptionstringrequired
Brief description of the payment purpose.
Example: Payment for invoice #1234
emailsstringrequired
Comma-separated list of email addresses for notifications. Only lowercase letters are allowed.
Possible values: Value must match regular expression ^([a-z0-9_\-\.]+)@([a-z]+)\.([a-z]+)(,[a-z0-9_\-\.]+@[a-z]+\.([a-z]+))*$
Example: customer@example.com
prefix_static_payidstringdeprecated
Static prefix for the PayID, used to generate a PayID in the format prefix_static_payid@example.co.
Possible values: Value must match regular expression ^(?=[a-z0-9]{3,35}$)[a-z0-9]*$
Example: abc
expired_atdate-time
Expiration time of the PayID in UTC format. Should be at least 15 minutes from the current time.
Example: 2024-12-31T23:59:59Z
external_idstring
Custom identifier for tracking purposes, set by the merchant.
Example: custom-id-12345
payment_request_notification objectrequired
Details for merchant callback notifications when the payment status changes.
endpoint_urlurirequired
A publicly accessible URL that Hello Clever will invoke when the transaction status changes. The endpoint must support HTTPS with TLS 1.2 or higher and use a valid certificate.
Example: https://example.com/payment_callback
authorization_headerstringrequired
The value for the Authorization header used in the callback request for additional security.
Example: Bearer your_token

Responses

200

Payment request created successfully.

application/json

Schema

Schema

idinteger
A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system.
Example: 123456
balance_idstring
The identifier of the balance associated with this payment request, allowing for account management and tracking of specific transactions.
Example: HDCHJSS
namestring
The name of the individual or entity associated with the payment request. This helps identify the payer or payee involved.
Example: John Doe
request_payidstring
The PayID generated for the payment request, used to uniquely identify and route the payment to the correct recipient.
Example: payid123@example.com
merchant_namestring
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.
Example: Merchant Co.
gstboolean
Indicates whether Goods and Services Tax (GST) applies to the transaction. A value of true means GST is included.
Example: true
amountstring
The amount requested for the payment, excluding any applicable taxes. This field represents the base value of the transaction.
Example: 100.0
totalstring
The total amount due, including all applicable taxes such as GST. This is the final amount the payer needs to pay.
Example: 110.0
gst_amountstring
The portion of the total amount that is attributable to GST. This helps in breaking down the tax components of the payment.
Example: 10.0
expired_atdate-time
The expiration date and time of the PayID, indicating until when the PayID is valid for making the payment.
Example: 2024-12-31T23:59:59Z
external_idstring
A custom identifier provided for tracking purposes, such as an internal reference or an invoice number.
Example: custom-id-12345
cashback_amountstring
The cashback amount, if applicable, that the payer is eligible to receive as part of the transaction.
Example: 5.0
pay_bydate-time
The last date by which the payment must be made. This provides a clear deadline for the payer.
Example: 2024-12-30T23:59:59Z
paid_atdate-time
The date and time when the payment was successfully completed. This is used for record-keeping and verification.
Example: 2024-12-25T12:34:56Z
statusstring
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.
Possible values: [pending, received, expired, return_pending, return_received, return_expired, return_rejected]
Example: pending
descriptionstring
A description accompanying the payment request, providing additional information such as the purpose of the payment or related invoice details.
Example: Payment for invoice #1234
noncestring
A unique value used to validate the transaction, preventing replay attacks and ensuring the integrity of the payment request.
Example: unique_nonce_string
stagestring
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.
Possible values: [overpaid, underpaid, unmatched_nonce, null]
Example: overpaid
refund_information object
Details about any refunds that are associated with this payment. This includes information about the refund PayID, refund amount, and any reasons provided.
refund_payidstring
The PayID used to top up for a refund, if the refund is needed. This helps identify the source of refund.
Example: sample@payid.com
refund_amountnumber
The amount that is being refunded to the payer. This helps in tracking the value being returned.
Example: 0.1
request_datedate-time
The date and time when the refund was requested. This is important for record-keeping and verification purposes.
Example: 2024-12-31T23:59:59Z
reasonstring
The reason provided for the refund, giving context to the request. This can include reasons such as product issues or cancellation.
Example: Broken product
sender_details object
Information about the sender of the payment, including reference details, bank information, and account holder's name.
referencestring
A reference provided by the sender for the transaction, used for identifying the purpose or source of the funds.
Example: SenderRef123
descriptionstring
Additional description provided by the sender, adding context to the payment.
Example: Payment from John Doe
bsbstring
The Bank-State-Branch (BSB) number of the sender, which is used to identify the bank and branch involved in the transaction.
Example: 123456
account_numberstring
The account number from which the payment is being sent, helping in tracing the source of the payment.
Example: 987654321
account_namestring
The name on the account from which the payment is being sent. This helps in verifying the identity of the sender.
Example: John Doe
short_invoice_urlurideprecated
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.
Example: https://short.example.com/invoice/123456
invoice_urlurideprecated
The full URL of the invoice related to the payment request. This provides access to the detailed invoice online. Note: this field is deprecated.
Example: https://example.com/invoice/123456

Example (auto)

{
  "id": 123456,
  "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"
  },
  "sender_details": {
    "reference": "SenderRef123",
    "description": "Payment from John Doe",
    "bsb": "123456",
    "account_number": "987654321",
    "account_name": "John Doe"
  }
}

400

Bad Request.

401

Unauthorized.

422

Unprocessable Entity.

Callbacks

POST statusChange

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

application/json

Bodyrequired

idinteger
A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system.
Example: 123456
balance_idstring
The identifier of the balance associated with this payment request, allowing for account management and tracking of specific transactions.
Example: HDCHJSS
namestring
The name of the individual or entity associated with the payment request. This helps identify the payer or payee involved.
Example: John Doe
request_payidstring
The PayID generated for the payment request, used to uniquely identify and route the payment to the correct recipient.
Example: payid123@example.com
merchant_namestring
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.
Example: Merchant Co.
gstboolean
Indicates whether Goods and Services Tax (GST) applies to the transaction. A value of true means GST is included.
Example: true
amountstring
The amount requested for the payment, excluding any applicable taxes. This field represents the base value of the transaction.
Example: 100.0
totalstring
The total amount due, including all applicable taxes such as GST. This is the final amount the payer needs to pay.
Example: 110.0
gst_amountstring
The portion of the total amount that is attributable to GST. This helps in breaking down the tax components of the payment.
Example: 10.0
expired_atdate-time
The expiration date and time of the PayID, indicating until when the PayID is valid for making the payment.
Example: 2024-12-31T23:59:59Z
external_idstring
A custom identifier provided for tracking purposes, such as an internal reference or an invoice number.
Example: custom-id-12345
cashback_amountstring
The cashback amount, if applicable, that the payer is eligible to receive as part of the transaction.
Example: 5.0
pay_bydate-time
The last date by which the payment must be made. This provides a clear deadline for the payer.
Example: 2024-12-30T23:59:59Z
paid_atdate-time
The date and time when the payment was successfully completed. This is used for record-keeping and verification.
Example: 2024-12-25T12:34:56Z
statusstring
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.
Possible values: [pending, received, expired, return_pending, return_received, return_expired, return_rejected]
Example: pending
descriptionstring
A description accompanying the payment request, providing additional information such as the purpose of the payment or related invoice details.
Example: Payment for invoice #1234
noncestring
A unique value used to validate the transaction, preventing replay attacks and ensuring the integrity of the payment request.
Example: unique_nonce_string
stagestring
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.
Possible values: [overpaid, underpaid, unmatched_nonce, null]
Example: overpaid
refund_information object
Details about any refunds that are associated with this payment. This includes information about the refund PayID, refund amount, and any reasons provided.
refund_payidstring
The PayID used to top up for a refund, if the refund is needed. This helps identify the source of refund.
Example: sample@payid.com
refund_amountnumber
The amount that is being refunded to the payer. This helps in tracking the value being returned.
Example: 0.1
request_datedate-time
The date and time when the refund was requested. This is important for record-keeping and verification purposes.
Example: 2024-12-31T23:59:59Z
reasonstring
The reason provided for the refund, giving context to the request. This can include reasons such as product issues or cancellation.
Example: Broken product
sender_details object
Information about the sender of the payment, including reference details, bank information, and account holder's name.
referencestring
A reference provided by the sender for the transaction, used for identifying the purpose or source of the funds.
Example: SenderRef123
descriptionstring
Additional description provided by the sender, adding context to the payment.
Example: Payment from John Doe
bsbstring
The Bank-State-Branch (BSB) number of the sender, which is used to identify the bank and branch involved in the transaction.
Example: 123456
account_numberstring
The account number from which the payment is being sent, helping in tracing the source of the payment.
Example: 987654321
account_namestring
The name on the account from which the payment is being sent. This helps in verifying the identity of the sender.
Example: John Doe
short_invoice_urlurideprecated
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.
Example: https://short.example.com/invoice/123456
invoice_urlurideprecated
The full URL of the invoice related to the payment request. This provides access to the detailed invoice online. Note: this field is deprecated.
Example: https://example.com/invoice/123456

Callbacks Responses

200

Callback received successfully.

400

Bad request.

401

Unauthorized access.

Authorization: app-id

name: app-idtype: apiKeyin: headerdescription: A unique identifier assigned to each application.

name: secret-keytype: apiKeyin: headerdescription: A secure token associated with the `app-id`.

• 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/merchants/create_payment");
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  \"name\": \"John Doe\",\n  \"gst\": true,\n  \"amount\": 100,\n  \"description\": \"Payment for invoice #1234\",\n  \"emails\": \"customer@example.com\",\n  \"expired_at\": \"2024-12-31T23:59:59Z\",\n  \"external_id\": \"custom-id-12345\",\n  \"payment_request_notification\": {\n    \"endpoint_url\": \"https://example.com/payment_callback\",\n    \"authorization_header\": \"Bearer your_token\"\n  }\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

app-id

secret-key

Body required

{
  "name": "John Doe",
  "gst": true,
  "amount": 100,
  "description": "Payment for invoice #1234",
  "emails": "customer@example.com",
  "expired_at": "2024-12-31T23:59:59Z",
  "external_id": "custom-id-12345",
  "payment_request_notification": {
    "endpoint_url": "https://example.com/payment_callback",
    "authorization_header": "Bearer your_token"
  }
}

ResponseClear

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