Get PayID Status
GEThttps://api.cleverhub.co/api/v1/payment_requests/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.
Note: Either id
or payid
is required as a query parameter. If both are provided, the id
will take precedence in determining the status.
Request
Query Parameters
Unique Hello Clever ID associated with the Payment Request.
Hello Clever PayID associated with the Payment Request.
Responses
- 200
- 400
- 401
- 404
Payment request status retrieved successfully.
- application/json
- Schema
- Example (auto)
Schema
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.
A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system.
123456
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:
Possible values: [pending
, received
, expired
, return_pending
, return_received
, return_expired
, return_rejected
]
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.
Possible values: [overpaid
, underpaid
, unmatched_nonce
, null
]
overpaid
refund_information object
sender_details object
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
{
"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"
}
}
Bad Request
Unauthorized
Not Found
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.Get, "https://api.cleverhub.co/api/v1/payment_requests/status");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());