Refund to the card
Sends part of the customer's invoice balance back to their card. Only card credit can go back, never cash or goodwill; a bigger amount is split across payments. It stays PENDING_AT_GATEWAY until the gateway finishes. idempotencyKey is required.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
customerId?stringThe customer. Send this or externalId; customerId wins if both.
externalId?stringYour own id for the customer, in place of customerId.
amountUsd*numberUSD to send back to the card, out of the customer's card credit.
0 < valueidempotencyKey*stringRequired, 1–200 characters. Reuse it only to retry the same refund.
1 <= length <= 200reason?stringA note for your records.
length <= 300The same key made this refund before; the gateway was not asked again.
application/json- response
statusCode*integerThe HTTP status code of the response, repeated in the body.
statusDetail*The status of the request. status is SUCCESS, and message says what happened.
result*The data of the answer.
curl -X POST 'https://payments.clocknext.com/api/v1/refunds' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "amountUsd": 40, "idempotencyKey": "refund-northwind-oct", "reason": "Customer asked for money back"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Refund already made." }, "result": { "refunds": [ { "id": "cmvgwd4ef000c08l5h8t3m2ya", "invoiceId": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001", "customerId": "cmvgva5po000c07iir1vtn8vl", "creditNoteId": null, "gateway": "STRIPE", "gatewayRefundId": "re_3Q9xK2LkdIwHu7ix0aBcD1Ef", "amountUsd": 40, "chargedAmountMinor": 4000, "chargedCurrencyCode": "USD", "status": "PENDING_AT_GATEWAY", "failureReason": null, "reason": "Customer asked for money back", "createdAt": "2026-10-28T09:20:11.000Z", "settledAt": null } ], "balance": { "totalUsd": 100, "refundableToCardUsd": 60, "invoicesOnlyUsd": 40 }, "replayed": true }}Types
Every object type on this page, with its fields.
CreateRefundInput
| Field | Type | Required | Description |
|---|---|---|---|
customerId | string | no | The customer. Send this or externalId; customerId wins if both. |
externalId | string | no | Your own id for the customer, in place of customerId. |
amountUsd | number | yes | USD to send back to the card, out of the customer's card credit. |
idempotencyKey | string | yes | Required, 1–200 characters. Reuse it only to retry the same refund. |
reason | string | no | A note for your records. |
Refund
Money going back to a customer's card.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The refund's id. |
invoiceId | string | yes | The invoice whose payment it goes back to. |
invoiceNumber | string | yes | That invoice's reference. |
customerId | string | yes | The customer. |
creditNoteId | string | null | yes | The credit note it came from. null for a refund of the invoice balance. |
gateway | "STRIPE" | "PADDLE" | yes | The payment gateway that holds the money. |
gatewayRefundId | string | null | yes | The gateway's own id. null until the gateway answers. |
amountUsd | number | yes | USD taken out of the invoice balance for it. |
chargedAmountMinor | integer | null | yes | What goes back to the card, in the smallest unit of the charged currency. null until known. |
chargedCurrencyCode | string | null | yes | The currency that was charged. null until known. |
status | "PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | yes | PENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money. |
failureReason | string | null | yes | Why a FAILED or REJECTED_IN_GATEWAY_REVIEW refund did not go through. |
reason | string | null | yes | The reason you gave. null when none. |
createdAt | string | yes | When it was requested. |
settledAt | string | null | yes | When the gateway finished. null while pending. |
InvoiceBalance
Credit we owe a customer, which pays their invoices. Not the wallet.
| Field | Type | Required | Description |
|---|---|---|---|
totalUsd | number | yes | What the customer holds now, in USD. |
refundableToCardUsd | number | yes | The part a card paid: what a refund could send back to the card. |
invoicesOnlyUsd | number | yes | The part with no card behind it, such as goodwill. Only usable on invoices. |
List refunds GET
Newest first, paged with `limit` (at most 50) and `cursor` → `nextCursor` — see [Paginating results](/docs/api-reference/pagination). Filter by `customerId`, `invoiceId` and/or `creditNoteId`. Any other query parameter is a `400`.
Get a refund GET
One refund: its status, the gateway's own id, the amount, and what went back to the card in the currency charged.