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 in sender on every lock.
  • Funds: Debited in the against currency 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_UPDATE for the payment and PAYMENT_REFUND for refunds, or poll GET /crypto/v2/synthetics/{syntheticAnyId}.

How it works

  1. 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 lock code.
  2. 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.
  3. You execute the payment with POST /crypto/v2/synthetics/qr-payment, passing the lock code as qrCode.
  4. You follow the synthetic until COMPLETED or CANCELLED, and keep listening for refunds after COMPLETED.

Before you start

{
  "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.

1

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"
}

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 201 with a code. Go to step 2.
  • Static, open amount (the payer enters the amount): the first lock returns 206 with the merchant data and an empty code. Ask the user for the amount and send the same request again with amount to get a 201 with a usable code.
{
  "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 send network (YAPE or PLIN) 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".
2

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.

3

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"
    }
  }
}
StatusMeaningWhat to do
ACTIVEFunds debited, payment on its way. It can stay here while the rail confirms.Show the payment as processing.
COMPLETEDThe merchant received the payment.Show success, but keep listening for refunds.
CANCELLEDThe 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.

CodeMeaningAction
P2, P4, P5, P6Rejected by the receiving bank, blocked on the receiver side, invalid QR or destination, invalid PIX keyDo not retry; ask the payer to check the QR or key.
P3QR expired at payment timeCreate a new lock and retry.
P7, P8Receiving bank timeout or a transient network errorRetry with backoff.
P1Unclassified errorRetry with backoff, with a cap.
4

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 by paymentNumberId, paymentExternalId or networkId: every refund of the same payment shares them. Group by paymentNumberId (or paymentExternalId) to follow the cumulative state of a payment.
  • A partial refund keeps the synthetic COMPLETED, so SYNTHETIC_STATUS_UPDATE does not show it. Only when the cumulative refunds reach the full amount does the synthetic move to CANCELLED.
  • Use the cumulative totalAmount / totalAmountToRefund instead of adding up amount yourself. amount is in the payment currency (asset); amountToRefund is what is credited back (assetToRefund, the against of the payment).
  • Each refund also appends a REFUND stage to the synthetic with refundId, totalAmount, totalAmountToRefund and fullyRefunded, so you can rebuild the refund history from GET /crypto/v2/synthetics/{syntheticAnyId}. The synthetic moves to CANCELLED when the latest stage has fullyRefunded: true.
  • A failed payment also gets a REFUND stage, with internalRefund: true: the funds were returned automatically and no PAYMENT_REFUND is sent. Merchant refunds have internalRefund: false.
5

Reconcile

WhatEndpoint
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 originGET /crypto/v2/stats/balance-activities
Closing balance snapshotsGET /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


Did this page help you?