Refund Payment

POST 
https://api.cleverhub.co/api/v2/cards/refund_payment

This endpoint refunds a captured card payment. You can refund either the full amount or a partial amount.

⚠️ You can only refund payments with waiting and received status.

⚠️ If refund_amount is not provided, the full amount will be refunded by default.

Request

application/json

Bodyrequired

uuidstringrequired
The unique ID of the succeeded payment (e.g., VMMAOTFQ).
Example: PSADT5CE
refund_amountnumber
The amount to be refunded. If this is not specified, the refund will default to the total original payment amount.
Example: 50
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 successful

application/json

Schema

Schema

total_amountnumber
Example: 200
refund_amountnumber
Example: 50
descriptionstring
Example: Testing refund
payin_request object
uuidstring
Example: 7PPPMXIGH
namestring
Example: Testing
emailstring
Example: test@helloclever.co
external_idstring
Example: wc_order_6C1hcvg4T7Pom
statusstring
Possible values: [pending, authorised, received, refunded, failed, canceled, waiting]
Example: waiting
pay_codestringnullable
Example: null
currencystring
Example: USD
amountnumber
Example: 10000
totalnumber
Example: 10000
paid_amountnumber
Example: 0
is_refundableboolean
Example: true
payment_methodstring
Example: card
expired_atstring
Example:
webhook_notification object
endpoint_urlstring
Example: https://webhook.site/456adb8f-4407-4bce-90fe-2c431db19696
authorization_headerstring
Example: ****
sender_details object
card object
card_typestring
Example: card
card_brandstring
Example: visa
card_last_4string
Example: 4242
card_token_idstring
Example: card_LLXE799U
created_atdate-time
Example: 2025-05-28T04:22:21.567+0000

Example (auto)

{
  "total_amount": 200,
  "refund_amount": 50,
  "description": "Testing refund",
  "payin_request": {
    "uuid": "7PPPMXIGH",
    "name": "Testing",
    "email": "test@helloclever.co",
    "external_id": "wc_order_6C1hcvg4T7Pom",
    "status": "waiting",
    "pay_code": null,
    "currency": "USD",
    "amount": 10000,
    "total": 10000,
    "paid_amount": 0,
    "is_refundable": true,
    "payment_method": "card",
    "expired_at": "",
    "webhook_notification": {
      "endpoint_url": "https://webhook.site/456adb8f-4407-4bce-90fe-2c431db19696",
      "authorization_header": "****"
    },
    "sender_details": {
      "card": {
        "card_type": "card",
        "card_brand": "visa",
        "card_last_4": "4242",
        "card_token_id": "card_LLXE799U"
      }
    },
    "created_at": "2025-05-28T04:22:21.567+0000"
  }
}

Example

{
  "total_amount": 200,
  "refund_amount": 50,
  "description": "Testing refund",
  "payin_request": {
    "uuid": "PSADT5CE",
    "name": "Hello Clever",
    "email": "test@helloclever.co",
    "external_id": "order_test_01",
    "status": "return_pending",
    "pay_code": null,
    "currency": "USD",
    "amount": "200.0",
    "total": "200.0",
    "paid_amount": "0.0",
    "is_refundable": false,
    "payment_method": "card",
    "expired_at": "",
    "webhook_notification": {
      "endpoint_url": "https://webhook.site/12da7803-c4cf-4f32-812d-aaeaecf20d9d",
      "authorization_header": "****"
    },
    "sender_details": {
      "card": {
        "card_type": "card",
        "card_brand": "visa",
        "card_last_4": "1111"
      }
    },
    "created_at": "2025-05-29T01:29:16.826+0000"
  }
}

400

Bad Request

401

Unauthorized

application/json

Schema

Schema

errors object
codestring
messagestring

Example (auto)

{
  "errors": {
    "code": "string",
    "message": "string"
  }
}

Example

{
  "errors": {
    "code": "REQUIRE_LOGIN",
    "message": "Not Authorised"
  }
}

422

Unprocessable Entity

application/json

Schema

Schema

errors object
messagestring

Example (auto)

{
  "errors": {
    "message": "string"
  }
}

Example

{
  "errors": {
    "message": "Reason must greater than 5 characters."
  }
}

Authorization: app-id

name: app-idtype: apiKeydescription: The app-id is registered and secured inside Hello Clever system and only required when client has initiated or in the middle of the transaction.in: header

name: secret-keytype: apiKeydescription: The secret-key is our client's secret of the source. Required if a publishable key is used to retrieve the source.in: header

• 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/v2/cards/refund_payment");
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  \"uuid\": \"PSADT5CE\",\n  \"refund_amount\": 50,\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

{
  "uuid": "PSADT5CE",
  "refund_amount": 50,
  "reason": "Partial refund due to customer request"
}

ResponseClear

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