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
export CLOBEPAY_API_BASE="<test base URL, includes /api/v1>"
export CLOBEPAY_API_KEY="<your sk_test_ key>"3. Check the 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 -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-Keyon every POST (Idempotency). - Deduplicate webhooks by
Clobepay-Event-Idand respond 2xx quickly. - Retry 429 and 5xx with backoff (Errors).