Payment links
Create and retrieve USDT payment links.
A payment link is how you issue a collection. The customer pays on the public page (publicUrl). The link starts as pending; after the payment is validated it becomes credited. Do not mark the order paid until the associated payin is settled (payin.settled webhook or GET /payins/{id}). Card data never touches your server. Deposit accounts are created and listed at /deposit-accounts; customer collections are issued with a payment link.
Create a payment link
/api/v1/payment-links
Creates a USDT checkout. Scope payment_links:write.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.
amountstringOptionalAmount in USDT, decimal string (e.g. "50.00").
payerMethodstringOptionalPreferred customer payment method, if applicable.
localAmountstringOptionalLocal-currency amount if you quote before creating the link.
descriptionstringOptionalText shown to the payer.
orderReferencestringOptionalYour order reference. Letters, numbers, dot, hyphen and underscore only. If omitted, ord_ + 12 characters is generated. The same orderReference may return the existing link (HTTP 200).
expiresInSecondsnumberOptionalLifetime in seconds (600–604800).
metadataobjectOptionalUp to 20 string keys (max 40 characters for the key, 500 for the value).
Responses
- HTTP 201Link created.
- HTTP 200A link with the same orderReference already existed.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 400
Bad RequestThe body has undeclared fields (e.g. order_reference instead of orderReference) or fields with an invalid type. message is an array with one text per field. - HTTP 409
seller_not_operationalThe merchant is not operational. - HTTP 409
verification_not_approvedThe merchant verification is not approved. - HTTP 409
idempotency_request_in_progressThe same Idempotency-Key is still being processed. Retry as is. - HTTP 422
invalid_amountInvalid amount, or you sent both amount and localAmount. - HTTP 422
invalid_metadatametadata exceeds the limits (20 string keys, 40 and 500 characters). - HTTP 422
idempotency_key_reuseYou reused the Idempotency-Key with a different body.
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \ -H "Idempotency-Key: order-10042" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount":"50.00","description":"Pedido 10042","orderReference":"10042","metadata":{"cart_id":"c_77"}}'Response
{
"id": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"publicId": "pay_8f2cK1mQ9vR4wL0tYbA3nC",
"publicUrl": "https://panel.clobepay.com/pagar/pay_8f2cK1mQ9vR4wL0tYbA3nC",
"orderReference": "10042",
"amount": "50.00",
"settlementAsset": "USDT",
"description": "Pedido 10042",
"status": "pending",
"expiresAt": "2026-11-20T18:00:00.000Z",
"creditedAt": null,
"settleAt": null,
"providerReference": null,
"receiptUrl": null,
"lastSyncedAt": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"payerMethod": null,
"localQuote": null,
"providerFee": null,
"payin": {
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"status": "pending"
}
}List payment links
/api/v1/payment-links
Paginated list. Scope payment_links:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
statusstringOptionalFilter by status.
pending · credited · expired · refunded
pagenumberOptionalPage (from 1).
Responses
- HTTP 200List. This route uses items, total, page and pageSize (not has_more).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 422
invalid_statusstatus is not an allowed value.
curl -X GET "$CLOBEPAY_API_BASE/payment-links?status=pending" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"items": [
{
"id": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"publicId": "pay_8f2cK1mQ9vR4wL0tYbA3nC",
"publicUrl": "https://panel.clobepay.com/pagar/pay_8f2cK1mQ9vR4wL0tYbA3nC",
"orderReference": "10042",
"amount": "50.00",
"settlementAsset": "USDT",
"description": "Pedido 10042",
"status": "pending",
"expiresAt": "2026-11-20T18:00:00.000Z",
"creditedAt": null,
"settleAt": null,
"providerReference": null,
"receiptUrl": null,
"lastSyncedAt": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"payerMethod": null,
"localQuote": null,
"providerFee": null,
"payin": {
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"status": "pending"
}
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"settlementAsset": "USDT"
}Retrieve a payment link
/api/v1/payment-links/{linkId}
Detail by UUID (do not use publicId here). Scope payment_links:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
linkIduuidRequiredInternal UUID of the link, not the publicId (pay_…).
refreshstringOptionalIf true or 1, first refreshes the collection status.
Responses
- HTTP 200Link detail.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or does not belong to your merchant. Also if linkId is not a UUID.
curl -X GET "$CLOBEPAY_API_BASE/payment-links/7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17?refresh=true" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"id": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"publicId": "pay_8f2cK1mQ9vR4wL0tYbA3nC",
"publicUrl": "https://panel.clobepay.com/pagar/pay_8f2cK1mQ9vR4wL0tYbA3nC",
"orderReference": "10042",
"amount": "50.00",
"settlementAsset": "USDT",
"description": "Pedido 10042",
"status": "pending",
"expiresAt": "2026-11-20T18:00:00.000Z",
"creditedAt": null,
"settleAt": null,
"providerReference": null,
"receiptUrl": null,
"lastSyncedAt": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"payerMethod": null,
"localQuote": null,
"providerFee": null,
"payin": {
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"status": "pending"
}
}