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.

Flow

  1. Your server creates the link with POST /payment-links and an Idempotency-Key.
  2. The response includes the payment page publicUrl and its payin, both pending.
  3. You redirect the customer to that URL (or open it in a popup). The customer pays.
  4. Clobepay validates the payment before settling it, and only then moves the payin to settled.
  5. You receive the payin.settled webhook and mark the order as paid.
Payment link statuses
pending
Payment credited
credited
Full refundrefunded
Expiredexpired

Create a link

  • amount in 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.

Ways to open the payment page
OptionStatusHow
RedirectRecommendedSend the customer to publicUrl with a 302 or window.location.
Popup / new tabAvailableOpen publicUrl with window.open from the customer’s click to avoid popup blockers.

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

Statuses of the link and its payin
LinkPayinMeaning
pendingpendingCreated; the customer has not paid yet or the payment is being validated.
creditedsettledPayment validated and credited to your merchant. You can deliver.
expiredexpiredExpired without payment.
refundedrefundedPayment refunded.

To decide whether an order is paid, always use the payin status (Payins and deposits).

Route reference: Payment links.