Get PayID Status
Retrieve the current status of a PayID payment request, providing real-time updates to track the state of a payment. This endpoint is essential for monitoring payment progress and handling different outcomes, including refunds.
Possible statuses include:
pending: The customer has not yet made the payment.received: The payment has been successfully completed by the customer.expired: The payment request has expired because it was not fulfilled in time.return_pending: A refund request (either full or partial) is pending on this payment.return_received: The refund has been successfully returned to the original payer.return_expired: The refund request expired after being unfulfilled for 10 days.return_rejected: The refund failed due to an issue with the recipient’s account. No further attempts will be made to process the refund.partially_refunded: Part of the payment has been refunded. Further refunds can be requested until the full amount is refunded.
Note: Either id or payid is required as a query parameter. If both are provided, the id will take precedence in determining the status.
curl --request GET \
--url https://api.cleverhub.co/api/v1/payment_requests/status \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>'import requests
url = "https://api.cleverhub.co/api/v1/payment_requests/status"
headers = {
"app-id": "<api-key>",
"secret-key": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'app-id': '<api-key>', 'secret-key': '<api-key>'}};
fetch('https://api.cleverhub.co/api/v1/payment_requests/status', 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/payment_requests/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.cleverhub.co/api/v1/payment_requests/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("app-id", "<api-key>")
req.Header.Add("secret-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cleverhub.co/api/v1/payment_requests/status")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/payment_requests/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
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.
Query Parameters
Unique Hello Clever ID associated with the Payment Request.
Hello Clever PayID associated with the Payment Request.
Response
Payment request status retrieved 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 GET \
--url https://api.cleverhub.co/api/v1/payment_requests/status \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>'import requests
url = "https://api.cleverhub.co/api/v1/payment_requests/status"
headers = {
"app-id": "<api-key>",
"secret-key": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'app-id': '<api-key>', 'secret-key': '<api-key>'}};
fetch('https://api.cleverhub.co/api/v1/payment_requests/status', 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/payment_requests/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.cleverhub.co/api/v1/payment_requests/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("app-id", "<api-key>")
req.Header.Add("secret-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cleverhub.co/api/v1/payment_requests/status")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/payment_requests/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
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"
}
}
]