Getting Started
Welcome to the Crypto2Pay API documentation. This guide will help you integrate our payment infrastructure into your platform.
Authentication
Every request must include your API key in the Authorization header:
Authorization: YOUR_API_KEY
Your API key is a static token — it does not expire and is not a JWT. Keep it secure and never expose it in client-side code.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api-pix.crypto2pay.app |
| Sandbox | https://sandbox-pix.crypto2pay.app |
Use the Sandbox environment for development and testing. Requests made against the sandbox behave like production but do not move real funds. The sandbox uses the same API keys and request/response structure as production — simply swap the base URL.
Sandbox Simulator
When using the sandbox, you can force a transaction into a specific final status by passing the x-sandbox-behaviour header on the create request. This lets you test your webhook handling and status logic without waiting for real events.
x-sandbox-behaviour: paid
The allowed values depend on the transaction type:
Cash-In (deposits)
| Value | Description |
|---|---|
paid | Transaction is marked as paid |
expired | Transaction expires without payment |
refunded | Transaction is paid then immediately refunded |
paid_then_refunded | Transaction is paid, then refunded after a short delay |
Cash-Out (payouts)
| Value | Description |
|---|---|
paid | Payout is processed successfully |
rejected | Payout is rejected by the receiving institution |
refunded | Payout is reversed after processing |
After the create request succeeds, the simulator will update the transaction status after ~5 seconds and immediately dispatch a webhook to the URL you provided. Your integration should:
- Receive the webhook — handle the status notification as you would in production.
- Confirm via the search endpoint — after receiving the webhook, query the relevant search endpoint to verify the final status:
- Cash-In: Search Charges
- Cash-Out: Search Payments
x-sandbox-behaviour is ignored in production. Never send it in live requests.
Sandbox QR codes are not valid PIX QR codes. They cannot be paid or scanned by any real banking app — attempting to read one will result in an error. Use x-sandbox-behaviour to simulate payment outcomes instead of scanning the QR code.