Quickstart

You will create a client and a debt, generate a PIX payment and simulate it being paid. Test mode sends no real messages and costs nothing.

Create a test API key

In the dashboard go to Settings → API & Webhooks → Create key and choose Test mode.Copy the esk_test_... key now, it is shown only once.

Create a client

curl -X POST "https://api.payable.run/api/v1/clients" \
  -H "Authorization: Bearer esk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "João",
    "lastName": "Silva",
    "phone": "11999999999",
    "email": "[email protected]"
  }'

Keep the id from the response.

Create a debt

curl -X POST "https://api.payable.run/api/v1/debts" \
  -H "Authorization: Bearer esk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "CLIENT_ID",
    "productName": "March subscription",
    "amount": 150.00,
    "dueDate": "2026-03-15"
  }'

The debt is enrolled in your collection flow automatically. In test mode its messages are simulated.

Generate the PIX payment

curl -X POST "https://api.payable.run/api/v1/pix/generate-for-debt/DEBT_ID"

This endpoint is public (it powers the customer’s payment page), so it needs no key. Keep the payment id.

Simulate the payment

curl -X POST "https://api.payable.run/api/v1/test/payments/PAYMENT_ID/simulate-paid" \
  -H "Authorization: Bearer esk_test_YOUR_KEY"

Only works with test keys. The debt becomes paid and your webhooks receive payment.received and debt.paid with "live": false.

Get started

Integrate

API reference

Next steps

Register a webhook

Go live

Handle errors

API reference

​Next steps

Register a webhook

Go live

Handle errors

API reference

Next steps