List refunds
Newest first, paged with limit (at most 50) and cursor → nextCursor — see Paginating results. Filter by customerId, invoiceId and/or creditNoteId. Any other query parameter is a 400.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
customerId?stringRestrict results to this customer.
invoiceId?stringOnly the refunds of this invoice.
creditNoteId?stringOnly the refunds a credit note started.
limit?integerRows on one page: default 50, maximum 50 (a bigger value is cut to 50). Zero, a negative number or a non-number is a 400.
1 <= value <= 5050cursor?stringId to page after — the last id of the previous page.
Refunds.
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*One page of refunds.
curl -X GET 'https://payments.clocknext.com/api/v1/refunds?customerId=cus_abc123&invoiceId=cmvgvkn14002u08l2ct47s2a7&creditNoteId=cmvgwcf2k000c08l5y1d6u8ra&limit=50&cursor=cus_zzz789'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "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 }, { "id": "cmvgwd7rj000d08l5z6k9p1qb", "invoiceId": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001", "customerId": "cmvgva5po000c07iir1vtn8vl", "creditNoteId": "cmvgwcf2k000c08l5y1d6u8ra", "gateway": "STRIPE", "gatewayRefundId": "re_3Q9xK2LkdIwHu7ix0bEfG2Hi", "amountUsd": 50, "chargedAmountMinor": 5000, "chargedCurrencyCode": "USD", "status": "PENDING_AT_GATEWAY", "failureReason": null, "reason": null, "createdAt": "2026-10-28T09:25:31.000Z", "settledAt": null }, { "id": "cmvgwd7rj000d08l5z6k9p1qb", "invoiceId": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001", "customerId": "cmvgva5po000c07iir1vtn8vl", "creditNoteId": null, "gateway": "PADDLE", "gatewayRefundId": "adj_01hv8x3k2m9q7r5t1w6y4z0abc", "amountUsd": 40, "chargedAmountMinor": 4000, "chargedCurrencyCode": "USD", "status": "REJECTED_IN_GATEWAY_REVIEW", "failureReason": "The refund was rejected by Paddle.", "reason": null, "createdAt": "2026-10-21T14:02:40.000Z", "settledAt": "2026-10-23T08:15:00.000Z" } ], "nextCursor": null }}Types
Every object type on this page, with its fields.
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. |
Void a credit note POST
Cancels a credit note while its invoice is still `OPEN`: the invoice owes the amount again. Once the invoice is paid it can't be voided, nor can a note that gave money back. A voided note answers `CREDIT_NOTE_ALREADY_VOID`. Answers the note and the invoice.
Refund to the card POST
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.