Get PayID Status

GET 
https://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

id integer

Unique Hello Clever ID associated with the Payment Request.

payid string

Hello Clever PayID associated with the Payment Request.

Responses

200

Payment request status retrieved 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

404

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());

Request Collapse all

Base URL

https://api.cleverhub.co/api

Auth

app-id

secret-key

Parameters

id — query

payid — query

ResponseClear

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