Refund Payment

POST 
https://api.cleverhub.co/api/v1/payment_requests/refund

Initiate a refund request on a completed payment with a received status. This endpoint processes a refund using the available balance in your account. If there is insufficient balance, you will either receive a top-up notification or need to wait for additional funds from new payments (Payins) to complete the refund.

Refunds can be partial or full, depending on the refund_amount specified. A reason for the refund is required for tracking and documentation purposes.

Request

application/json

Bodyrequired

payment_request_idintegerrequired
The unique identifier for the original payment request that is to be refunded.
Example: 1
refund_amountnumber
The amount to be refunded. If this is not specified, the refund will default to the total original payment amount.
Example: 100
reasonstringrequired
The reason for the refund, which must be at least 5 characters long. This is required for record-keeping and can help in cases of partial refunds.
Example: Partial refund due to customer request

Responses

200

Refund initiated successfully.

application/json

Schema

Schema

refund_payidstring
The PayID to which the refund amount should be paid to complete the refund process.
Example: refund_payid@example.com
refund_amountnumber
The total amount that was refunded.
Example: 100
reasonstring
The reason provided for the refund.
Example: Partial refund due to customer request
payment_request object
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)

{
  "refund_payid": "refund_payid@example.com",
  "refund_amount": 100,
  "reason": "Partial refund due to customer request",
  "payment_request": {
    "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

422

Unprocessable Entity

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/payment_requests/refund");
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  \"payment_request_id\": 1,\n  \"refund_amount\": 100,\n  \"reason\": \"Partial refund due to customer request\"\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

{
  "payment_request_id": 1,
  "refund_amount": 100,
  "reason": "Partial refund due to customer request"
}

ResponseClear

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