ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

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

POST
/refunds

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

application/json
  1. body
  1. body
  2. …
customerId?string

The customer. Send this or externalId; customerId wins if both.

externalId?string

Your own id for the customer, in place of customerId.

amountUsd*number

USD to send back to the card, out of the customer's card credit.

Range0 < value
idempotencyKey*string

Required, 1–200 characters. Reuse it only to retry the same refund.

Length1 <= length <= 200
reason?string

A note for your records.

Lengthlength <= 300

Response Body

The same key made this refund before; the gateway was not asked again.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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"}'
Example Response
{  "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

FieldTypeRequiredDescription
customerIdstringnoThe customer. Send this or externalId; customerId wins if both.
externalIdstringnoYour own id for the customer, in place of customerId.
amountUsdnumberyesUSD to send back to the card, out of the customer's card credit.
idempotencyKeystringyesRequired, 1–200 characters. Reuse it only to retry the same refund.
reasonstringnoA note for your records.

Refund

Money going back to a customer's card.

FieldTypeRequiredDescription
idstringyesThe refund's id.
invoiceIdstringyesThe invoice whose payment it goes back to.
invoiceNumberstringyesThat invoice's reference.
customerIdstringyesThe customer.
creditNoteIdstring | nullyesThe credit note it came from. null for a refund of the invoice balance.
gateway"STRIPE" | "PADDLE"yesThe payment gateway that holds the money.
gatewayRefundIdstring | nullyesThe gateway's own id. null until the gateway answers.
amountUsdnumberyesUSD taken out of the invoice balance for it.
chargedAmountMinorinteger | nullyesWhat goes back to the card, in the smallest unit of the charged currency. null until known.
chargedCurrencyCodestring | nullyesThe currency that was charged. null until known.
status"PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW"yesPENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money.
failureReasonstring | nullyesWhy a FAILED or REJECTED_IN_GATEWAY_REVIEW refund did not go through.
reasonstring | nullyesThe reason you gave. null when none.
createdAtstringyesWhen it was requested.
settledAtstring | nullyesWhen the gateway finished. null while pending.

InvoiceBalance

Credit we owe a customer, which pays their invoices. Not the wallet.

FieldTypeRequiredDescription
totalUsdnumberyesWhat the customer holds now, in USD.
refundableToCardUsdnumberyesThe part a card paid: what a refund could send back to the card.
invoicesOnlyUsdnumberyesThe 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.