Base URL https://payments.clocknext.com/api/v1
Returns a link the customer opens to add or replace the card auto-pay charges. They enter the card on a secure page with your organisation's Stripe or Paddle form; nothing is charged there. The new card replaces the saved one, and any open auto-pay invoice on the customer's active plan is charged to it right away. The link is valid for 24 hours and works once; making a new link turns the older ones off. With returnUrl, the customer is sent there once the card is saved; otherwise they see a "Card saved" page. mode is update when the customer has a saved card, else add. 422 when no payment gateway is connected. When your Clocknext plan does not include Payments, every call is 403 FEATURE_LOCKED.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringCustomer id.
application/json- body
returnUrl?stringWhere to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional.
uriLink made.
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 link and when it stops working.
curl -X POST 'https://payments.clocknext.com/api/v1/customers/cus_abc123/update-payment' \ -H 'Content-Type: application/json' \ -d '{ "returnUrl": "https://app.northwindtraders.com/billing"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "url": "https://payments.clocknext.com/card/Y21nN3E4ZjJ3MDAwMDN4c2YAAAADAWkFcCwk3JdQ8vX2mNp7LwYtR4sHg?return=https%3A%2F%2Fapp.northwindtraders.com%2Fbilling", "expiresAt": "2026-10-28T10:00:00.000Z", "mode": "update", "gateway": "stripe" }}Base URL https://payments.clocknext.com/api/v1
The same call, addressed by the customer's externalId. Same body and response.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
externalId*stringYour own id for the customer: 1–64 letters, numbers or "-". Case-sensitive.
^[A-Za-z0-9-]{1,64}$1 <= length <= 64application/json- body
returnUrl?stringWhere to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional.
uriLink made.
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 link and when it stops working.
curl -X POST 'https://payments.clocknext.com/api/v1/customers/ext/string/update-payment' \ -H 'Content-Type: application/json' \ -d '{ "returnUrl": "https://app.northwindtraders.com/billing"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "url": "https://payments.clocknext.com/card/Y21nN3E4ZjJ3MDAwMDN4c2YAAAAEAWkFcCwq8LmN2pR5tW7vY1zA3cE4fG?return=https%3A%2F%2Fapp.northwindtraders.com%2Fbilling", "expiresAt": "2026-10-28T10:00:00.000Z", "mode": "add", "gateway": "paddle" }}Types
Every object type on this page, with its fields.
UpdatePaymentInput
| Field | Type | Required | Description |
|---|---|---|---|
returnUrl | string | no | Where to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional. |
PaymentUpdateLink
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | The secure card page (/card/<token>), with ?return= when a returnUrl was given. Send it to the customer or open it from your app. |
expiresAt | string | yes | When the link stops working (24 hours after it was made). |
mode | "add" | "update" | yes | update when the customer has a saved card, else add. |
gateway | "stripe" | "paddle" | yes | The organisation's payment gateway. |