Skip to main content

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

Payment request status retrieved successfully.

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

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`.
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
Parameters
— query
— query
ResponseClear

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