Create Static PayID

POST 
https://api.cleverhub.co/api/v1/customers/create_static_open_payid

Creates a Static Open PayID that serves as a unique, reusable identifier linked to a customer’s information. This Static PayID can be used for multiple transactions, offering a persistent payment identifier that simplifies future payments and customer recognition.

When a Static PayID is created, it securely associates essential customer details like name, email, and optional address or phone number, ensuring a streamlined payment process for returning customers. Additionally, the customer_notification configuration allows for real-time updates on transaction status, providing merchants with immediate feedback on payment events through a secure callback mechanism.

Request

application/json

Bodyrequired

namestringrequired
The full name of the customer for whom the Static PayID is created.
Possible values: Value must match regular expression ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$
Example: John Doe
emailstringrequired
The email address associated with the Static PayID.
Example: johndoe@example.com
prefix_static_payidstringrequired
Prefix used to generate a unique PayID for the customer.
Possible values: Value must match regular expression ^(?=.{3,35}$)[a-z0-9.]*
Example: customer.prefix123
addressstring
The full address associated with the Static PayID.
Example: 123 Example Street
phonestring
Phone number associated with the Static PayID, including country code.
Example: +61412345678
citystring
City where the customer resides.
Example: Sydney
zip_codestring
Postal code of the customer's location.
Example: 2000
statestring
State where the customer resides.
Example: NSW
external_idstring
Custom identifier set by the merchant to reference the Static PayID.
Example: custom-id-67890
customer_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 have a valid certificate from a recognized authority.
Example: https://example.com/notification_callback
authorization_headerstringrequired
The value for the Authorization header that Hello Clever will include in the callback request for security purposes.
Example: Bearer your_custom_token

Responses

200

Static Open PayID created successfully.

application/json

Schema

Schema

namestring

Name of the Static Open PayID.

emailstring

Email associated with the Static Open PayID.

addressstring

Address linked with the Static Open PayID.

phonestring

Phone number associated with the Static Open PayID.

zip_codestring

Postal code of the customer’s location.

citystring

City associated with the Static Open PayID.

statestring

State associated with the Static Open PayID.

external_idstring

Custom identifier that can be used for future reference.

customer_notification object

Merchant Callback Details

endpoint_urluri

Callback URL for status notifications.

authorization_headerstring

Authorization header used in callback.

statusstring

Current status of the Static PayID.

Possible values: [active, expired]

Example (auto)

{
  "name": "string",
  "email": "string",
  "address": "string",
  "phone": "string",
  "zip_code": "string",
  "city": "string",
  "state": "string",
  "external_id": "string",
  "customer_notification": {
    "endpoint_url": "string",
    "authorization_header": "string"
  },
  "status": "active"
}

400

Bad Request.

401

Unauthorized.

422

Unprocessable Entity.

Callbacks

POST statusChange

POST 
{$request.body#/customer_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/customers/create_static_open_payid");
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  \"email\": \"johndoe@example.com\",\n  \"prefix_static_payid\": \"customer.prefix123\",\n  \"address\": \"123 Example Street\",\n  \"phone\": \"+61412345678\",\n  \"city\": \"Sydney\",\n  \"zip_code\": \"2000\",\n  \"state\": \"NSW\",\n  \"external_id\": \"custom-id-67890\",\n  \"customer_notification\": {\n    \"endpoint_url\": \"https://example.com/notification_callback\",\n    \"authorization_header\": \"Bearer your_custom_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",
  "email": "johndoe@example.com",
  "prefix_static_payid": "customer.prefix123",
  "address": "123 Example Street",
  "phone": "+61412345678",
  "city": "Sydney",
  "zip_code": "2000",
  "state": "NSW",
  "external_id": "custom-id-67890",
  "customer_notification": {
    "endpoint_url": "https://example.com/notification_callback",
    "authorization_header": "Bearer your_custom_token"
  }
}

ResponseClear

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