Payment links
Create a collection with a hosted payment page. It starts pending and is confirmed only when its payin is settled.
A payment link is a collection with a payment page hosted by Clobepay. The customer’s payment details are captured on that page: they never touch your site or your server. It settles in USDT.
You can create payment links with an API key. The response includes the
publicUrl, the payin object and metadata. You can also create them from the dashboard.Flow
- Your server creates the link with
POST /payment-linksand anIdempotency-Key. - The response includes the payment page
publicUrland its payin, bothpending. - You redirect the customer to that URL (or open it in a popup). The customer pays.
- Clobepay validates the payment before settling it, and only then moves the payin to
settled. - You receive the
payin.settledwebhook and mark the order as paid.
Key rule: a link starts
pending and is confirmed only when its payin is settled. The customer returning to your site does not confirm the payment, and no unvalidated notification settles a collection.pending
Payment credited
credited
Full refundrefunded
Expiredexpired
Create a link
amountin USDT, as a decimal string with up to 2 decimals.orderReference: your order reference.metadata: up to 20 keys of up to 500 characters. It is copied to the payin and sent in webhooks. Do not include personal data.- The merchant must be operational with an approved verification; otherwise
409 verification_not_approved.
POST/payment-links
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"
}
}Show the payment page to the customer
You need no SDK or library: the link publicUrl is all it takes. The payment page is hosted and includes 3-D Secure card authentication when it applies.
| Option | Status | How |
|---|---|---|
| Redirect | Recommended | Send the customer to publicUrl with a 302 or window.location. |
| Popup / new tab | Available | Open publicUrl with window.open from the customer’s click to avoid popup blockers. |
When the customer returns to your site, or the popup closes, the link is still
pending: confirm the order only with the payin.settled webhook or by retrieving the payin.Retrieve
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"
}Statuses
| Link | Payin | Meaning |
|---|---|---|
pending | pending | Created; the customer has not paid yet or the payment is being validated. |
credited | settled | Payment validated and credited to your merchant. You can deliver. |
expired | expired | Expired without payment. |
refunded | refunded | Payment refunded. |
To decide whether an order is paid, always use the payin status (Payins and deposits).
Route reference: Payment links.