Quickstart

From a test key to your first payment link and its webhook, in five steps.

This guide takes you from zero to a confirmed collection in the test environment. Everything is server to server: your backend calls the API with a secret key and Clobepay notifies you by webhook once the money is settled.

1. Get a test key

In the dashboard, open Integration settings and create a secret test key (prefix sk_test_). It is shown only once: store it in your secrets manager. Details in API keys.

2. Set up your environment

Environment variables
export CLOBEPAY_API_BASE="<test base URL, includes /api/v1>"
export CLOBEPAY_API_KEY="<your sk_test_ key>"

3. Check the key

cURL · Check your key
curl "$CLOBEPAY_API_BASE/me" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Expected response: HTTP 200

The response includes your merchant identifier (MID), the environment and the key scopes.

4. Create a payment link

cURL · Create a 50 USDT payment link
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \
  -H "Idempotency-Key: order-10042" \
  -H "Content-Type: application/json" \
  -d '{"amount":"50.00","description":"Pedido 10042","orderReference":"10042","metadata":{"cart_id":"c_77"}}'

Expected response: HTTP 201

Redirect your customer to the publicUrl in the response. The link and its payin start as pending. More in Payment links.

5. Wait for confirmation

Register a webhook endpoint, verify the Clobepay-Signature header and mark the order as paid only when you receive payin.settled (or when GET /payins/{id} returns settled). The customer returning to your site does not confirm the payment.

Before going live

  • Use an sk_live_ key only on your production servers.
  • Send Idempotency-Key on every POST (Idempotency).
  • Deduplicate webhooks by Clobepay-Event-Id and respond 2xx quickly.
  • Retry 429 and 5xx with backoff (Errors).