Integrate QR payments
Let your users pay QR codes and payment keys (PIX keys, Peruvian phone numbers, Bre-B keys) over each country's local rail with one integration: you lock the payment, execute it, and track it until it settles or is refunded.
At a glance
- Users: End-user model: the payer is the onboarded user in
userAnyId. Principal Accounts model: you operate from your principal account and declare the real payer insenderon every lock. - Funds: Debited in the
againstcurrency you pick on the lock. With a pre-funded company balance, what the user's balance does not cover comes from your company balance (see Funding your account). - Tracking:
SYNTHETIC_STATUS_UPDATEfor the payment andPAYMENT_REFUNDfor refunds, or pollGET /crypto/v2/synthetics/{syntheticAnyId}.
How it works
- Your app scans the QR (or the user types a payment key) and you send it to
POST /crypto/v2/payment-locks. Manteca detects the country and network, decodes the merchant, locks the price and returns a lockcode. - You show the merchant name and amounts to the user. If the QR has no amount, you ask the user for one and lock again with
amount. - You execute the payment with
POST /crypto/v2/synthetics/qr-payment, passing the lockcodeasqrCode. - You follow the synthetic until
COMPLETEDorCANCELLED, and keep listening for refunds afterCOMPLETED.
Before you start
- End-user model: each user must be onboarded and active before paying. Create the user with
POST /crypto/v2/onboarding-actions/initial, sending as much data as you have so fewer follow-up tasks remain, then upload the front and back of the identity document (front only for a single-sided one):POST /crypto/v2/onboarding-actions/upload-identity-imagereturns a signedurland youPUTthe file binary to it. Full flow: Onboard a new user; per-country data andlegalIdformats: Country requirements. - Register the webhooks this flow uses with
PATCH /crypto/v2/company:
{
"notificationInfo": {
"type": "WEBHOOK",
"secret": "your-webhook-secret",
"webhooks": {
"SYNTHETIC_STATUS_UPDATE": "https://your-domain.com/webhooks/synthetic-status",
"PAYMENT_REFUND": "https://your-domain.com/webhooks/payment-refund"
}
}
}Webhooks are sent from four fixed IP addresses: allowlist all of them (see Webhooks).
Countries and currencies
against is the currency debited from the balance: the local currency of the QR, or a stablecoin such as USDT, which Manteca converts within the payment. It defaults to USDT. Supported countries, networks, destination types and the recommended against per country: see Coverage.
Lock the payment
Send the raw scanned string (or the payment key) in paymentDestination. The lock validates the destination, runs the compliance checks on payer and merchant, and fixes the price until expireAt.
Request POST /crypto/v2/payment-locks
The payer is the user in userAnyId. Do not send sender.
{
"userAnyId": "100036128",
"paymentDestination": "00020126330014br.gov.bcb.pix0111123456789015204000053039865406100.005802BR5913John Merchant6009Sao Paulo62070503***6304ABCD",
"against": "USDT"
}sender is required and carries the real payer; without it the lock fails with MISSING_PAYMENT_SENDER. userAnyId can be omitted: the lock runs on your principal account for the country of the destination.
{
"paymentDestination": "00020126330014br.gov.bcb.pix0111123456789015204000053039865406100.005802BR5913John Merchant6009Sao Paulo62070503***6304ABCD",
"against": "BRL",
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
}
}legalIdNationality is the payer's country, not the merchant's. In Brazil, a legalId is tied to the payer name on its first payment: a later lock whose name and surname share no name with the registered one fails with PAYER_NAME_MISMATCH. See sender requirements for the accepted legalId formats per country.
Response 201
{
"code": "5bd4751f-68cb-4ff4-8b41-a05dc057f1e9",
"type": "PIX_QR",
"network": "PIX",
"paymentRecipientName": "John Merchant",
"paymentAssetAmount": "100.00",
"paymentAsset": "BRL",
"paymentAgainstAmount": "18.35",
"paymentAgainst": "USDT",
"expireAt": "2026-07-02T15:40:00.000-03:00",
"creationTime": "2026-07-02T15:30:00.000-03:00"
}Show paymentRecipientName and the amounts to the user before confirming. paymentAssetAmount is what the merchant receives; paymentAgainstAmount is what is debited.
Dynamic (fixed amount) and static (open amount) QRs
- Dynamic, fixed amount (the QR carries the amount): the first lock returns
201with acode. Go to step 2. - Static, open amount (the payer enters the amount): the first lock returns
206with the merchant data and an emptycode. Ask the user for the amount and send the same request again withamountto get a201with a usablecode.
{
"userAnyId": "100036128",
"paymentDestination": "00020101021140200010com.yacare0202...6304E401",
"against": "ARS",
"amount": "15000.00"
}Payment keys
A PIX key or a Peruvian phone number carries no amount, so send amount on the first lock. Without it the lock fails with PAYMENT_DESTINATION_AMOUNT.
{
"paymentDestination": "[email protected]",
"amount": "10.00",
"against": "BRL",
"sender": {
"legalIdNationality": "BRAZIL",
"legalId": "12345678909",
"name": "JOHN",
"surname": "DOE"
}
}- Brazil: a phone PIX key goes with the country code, for example
+5511988887777. - Peru: send the phone number with the country code (
+51987654321). You can sendnetwork(YAPEorPLIN) to pick the network for a phone number. Payments are capped at 500 PEN each (PAYMENT_MAX_AMOUNT). - Colombia: for a Bre-B key that is an email, also send
"country": "COLOMBIA".
Execute the payment
Pass the lock code as qrCode before expireAt. The lock already carries the user, the payer and the amounts. Send your own externalId to recognize the payment later: a repeated externalId returns 409 SYNTHETIC_EXISTS and creates nothing.
Request POST /crypto/v2/synthetics/qr-payment
{
"externalId": "qr-payment-001",
"qrCode": "5bd4751f-68cb-4ff4-8b41-a05dc057f1e9"
}Response 201
{
"id": "6931f4a27cb84dd42b784e99",
"numberId": "98765",
"externalId": "qr-payment-001",
"status": "ACTIVE",
"type": "PIX_PAYMENT",
"details": {
"paymentAsset": "BRL",
"paymentAgainst": "USDT",
"paymentAssetAmount": "100.00",
"paymentAgainstAmount": "18.35"
},
"creationTime": "2026-07-02T15:30:10.000-03:00"
}The creation response is not the final result. Store id and wait for the webhook.
By default (disallowDebt: false), what the user's balance does not cover is taken from your pre-funded company balance. If the payment must use only the user's own balance, send "disallowDebt": true: the request then fails with 400 NO_FUNDS when the balance is short.
originDeclaration is an optional object on the synthetic request, required for crypto funding under CRYPTO_BRL, including when company debt skips the deposit stage. Fiat funding does not require it. See Funds declarations.
When the payment waits for a deposit, you can send "enforceDepositAddressLabel": "example-label" on the synthetic creation request, not the payment-lock request. It filters funding accounts to that exact configured label and requires the deposit to match the label; it does not select the merchant's payout network or change network defaults. See Select a deposit account by label.
Track the operation
SYNTHETIC_STATUS_UPDATE fires on every status change. Poll GET /crypto/v2/synthetics/{syntheticAnyId} for recovery, using the id, numberId or externalId.
{
"event": "SYNTHETIC_STATUS_UPDATE",
"data": {
"id": "6931f4a27cb84dd42b784e99",
"numberId": "98765",
"externalId": "qr-payment-001",
"status": "COMPLETED",
"type": "PIX_PAYMENT",
"details": {
"paymentAssetAmount": "100.00",
"paymentAsset": "BRL",
"paymentAgainstAmount": "18.35",
"paymentAgainst": "USDT"
}
}
}| Status | Meaning | What to do |
|---|---|---|
ACTIVE | Funds debited, payment on its way. It can stay here while the rail confirms. | Show the payment as processing. |
COMPLETED | The merchant received the payment. | Show success, but keep listening for refunds. |
CANCELLED | The payment failed and the funds were returned, or it was fully refunded. | Read the failure code (below) and tell the user. |
Failure reasons
When a payment fails, the reason is in the errors array of the failing WITHDRAW stage, in both the webhook and the GET, formatted as <code>: <description> (for example "P4: Payment blocked by receiver"). Match on the code. Full code list: QR Payments error handling.
| Code | Meaning | Action |
|---|---|---|
P2, P4, P5, P6 | Rejected by the receiving bank, blocked on the receiver side, invalid QR or destination, invalid PIX key | Do not retry; ask the payer to check the QR or key. |
P3 | QR expired at payment time | Create a new lock and retry. |
P7, P8 | Receiving bank timeout or a transient network error | Retry with backoff. |
P1 | Unclassified error | Retry with backoff, with a cap. |
Handle refunds
A merchant can refund a payment after COMPLETED, in full or in parts, minutes or days later. Each refund sends a PAYMENT_REFUND webhook and credits the against currency back to the balance.
{
"event": "PAYMENT_REFUND",
"data": {
"refundId": "9b1c8e7a-2f4d-4a6b-8c3e-1d5f7a9b0c2d",
"paymentNumberId": "98765",
"paymentExternalId": "qr-payment-001",
"amount": "40.00",
"totalAmount": "40.00",
"asset": "BRL",
"amountToRefund": "7.34",
"totalAmountToRefund": "7.34",
"assetToRefund": "USDT",
"partial": true,
"refundedAt": "2026-07-02T18:05:00.000-03:00"
}
}- Deduplicate by
refundId. The same event can arrive more than once. Do not dedupe bypaymentNumberId,paymentExternalIdornetworkId: every refund of the same payment shares them. Group bypaymentNumberId(orpaymentExternalId) to follow the cumulative state of a payment. - A partial refund keeps the synthetic
COMPLETED, soSYNTHETIC_STATUS_UPDATEdoes not show it. Only when the cumulative refunds reach the full amount does the synthetic move toCANCELLED. - Use the cumulative
totalAmount/totalAmountToRefundinstead of adding upamountyourself.amountis in the payment currency (asset);amountToRefundis what is credited back (assetToRefund, theagainstof the payment). - Each refund also appends a
REFUNDstage to the synthetic withrefundId,totalAmount,totalAmountToRefundandfullyRefunded, so you can rebuild the refund history fromGET /crypto/v2/synthetics/{syntheticAnyId}. The synthetic moves toCANCELLEDwhen the latest stage hasfullyRefunded: true. - A failed payment also gets a
REFUNDstage, withinternalRefund: true: the funds were returned automatically and noPAYMENT_REFUNDis sent. Merchant refunds haveinternalRefund: false.
Reconcile
| What | Endpoint |
|---|---|
Past payments, filtered by status, type, from / to and more. isRefunded=true returns the payments the merchant refunded. | GET /crypto/v2/synthetics |
| Current balance (your principal account, or each user under the End-user model) | GET /crypto/v2/user-balances/USERANYID |
| Every debit and credit, with a description of its origin | GET /crypto/v2/stats/balance-activities |
| Closing balance snapshots | GET /crypto/v2/stats/balance-snapshots |
Test in sandbox
Use a test destination as paymentDestination and the flow completes against a mock, with webhooks. For example pix (fixed amount) or pixmanualamount (open amount) with against: "BRL", and qr3 / qr3manualamount with ARS. Append failure to force a CANCELLED (qr3failure), or refund to a qr3 or pix destination to get a PAYMENT_REFUND about 30 seconds after completion. In Peru, Colombia and Venezuela, include inactive in the destination to get PAYMENT_DESTINATION_EXPIRED, as with an expired QR. All codes per country: Testing QR payments.
Errors
Handle errors by internalStatus, not by HTTP status. Do not retry a 409 or other 4xx: the same request returns the same error until the state changes. Retry network errors and 5xx with exponential backoff.
Full list: QR Payments error handling.
Go deeper
- Coverage: countries, networks and destination types.
- Payment lifecycle: status transitions, timing and refund fields.
- Preview a payment: every lock field and the
legalIdpatterns per country. - After the payment: full webhook payloads.
- Onboarding models: End-user vs Principal Accounts.
- Reconciliation and reporting.
Updated 15 days ago