Charges Overview
A charge synthetic lets you collect a payment from a payer into one of your users. The payer can pay in any supported asset: crypto or fiat: and you decide which asset you want to receive.
A charge always begins with a deposit from the payer. This is what distinguishes it from a ramp: the deposit stage is required and acts as the trigger for everything that follows.
Charge flow
- Lock the charge:
POST /crypto/v2/charge-locksfixes the exchange rate between the asset the payer deposits (entryAsset) and the asset you want to receive (exitAsset). The API returns acode. - Create the synthetic:
POST /crypto/v2/synthetics/chargewith thatcodeaschargeCodeand, optionally, thedestinationwhere the funds settle. The response contains the addresses / QR the payer must pay to. - Track: confirm the collection via the
SYNTHETIC_STATUS_UPDATEwebhook, or by pollingGET /crypto/v2/synthetics/{syntheticAnyId}.
Optional declaration fields on the create request are originDeclaration for incoming crypto and destination.declaration for outgoing crypto settlement. They are required for the applicable crypto leg when operating under CRYPTO_BRL. Fiat deposits and fiat settlement do not require them. See Funds declarations for the complete object.
Stages
Each charge is composed of up to three stages, depending on what you requested:
| Stage | When | Description |
|---|---|---|
DEPOSIT | Always | Receives the payer's entryAsset. The only truly required part of a charge. |
ORDER | Only when entryAsset ≠ exitAsset | Converts the entryAsset into the exitAsset at the locked price. |
WITHDRAW | Only when you pass destination | Settles the funds to the destination. Otherwise they accumulate in the receiving user's balance. |
So if you collect in the same asset you want to receive and pass no destination, the charge is a simple DEPOSIT and the funds accumulate. Any conversion or withdrawal is added as an extra stage.
What you present to the payer
The most important part of the create response is details.depositAddresses:
- Crypto entries return an on-chain address per supported network:
{ "type": "INFO", "address": "...", "network": "..." }. - Fiat entries return a QR:
{ "type": "QR", "code": "...", "url": "...", "expiresAt": "..." }, wherecodeis the QR string andurlrenders the QR image.
In all cases details also carries the locked paymentPrice, entryAmount, and exitAmount to display.
The lock expires at
expireAt: after that, create a new one. After it expires, create a new charge lock.
Restrict the payer (PIX)
For BRL charges paid by PIX, you can limit the charge to a single payer. Send the payer's CPF or CNPJ in sender when you call POST /crypto/v2/synthetics/charge:
{
"chargeCode": "3363db60-4c5f-4486-9746-d2f005e444cb",
"externalId": "ext-charge-002",
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
}
}Only a PIX sent from an account held by that CPF or CNPJ is credited. If a different account holder pays:
- The payment is not credited to the user and is returned to the payer. No
DEPOSIT_DETECTEDwebhook is sent. - The charge moves to
CANCELLEDright away. You receive aSYNTHETIC_STATUS_UPDATEwith the reason instages["1"].errors. - A later payment to the same QR is not credited either.
To restrict the payer, legalId must be a CPF (11 digits) or a CNPJ (14 digits). This check only runs in production: in sandbox, a payment from any account is credited.
Idempotency
Pass a unique externalId when creating the synthetic. No second charge is created: retrying the same request (same chargeCode) returns 404 CHARGE_LOCK_NF, because the lock was already used, and reusing the externalId with a new chargeCode returns 409 SYNTHETIC_EXISTS. In both cases, recover the existing charge with GET /crypto/v2/synthetics/{syntheticAnyId}, passing the externalId as syntheticAnyId.
Endpoint reference
| Action | Endpoint |
|---|---|
| Create charge lock | POST /crypto/v2/charge-locks |
| Get charge lock | GET /crypto/v2/charge-locks/{code} |
| Create charge synthetic | POST /crypto/v2/synthetics/charge |
| Get synthetic by ID | GET /crypto/v2/synthetics/{syntheticAnyId} |
Testing in sandbox
In sandbox, a charge completes on its own a few seconds after you create it: you do not need to pay the QR or send crypto. The SYNTHETIC_STATUS_UPDATE webhooks arrive as in production.
Related pages
- Coverage: supported entry networks and assets, and settlement options
- Charge lifecycle: synthetic statuses, stages, and the confirmation webhook
- Charges Error Handling: error codes per endpoint
Updated 19 days ago