Preview a payment

Preview a payment

Payment preview is the first step of QR Payments.

Use POST /v2/payment-locks to:

  • decode the destination,
  • validate destination/network compatibility,
  • and generate the lock data required for confirmation.

Under the Principal Accounts model, sender is required and must include the real payer information for compliance. Under the End-user model, the payer is the user in userAnyId.

Under the Principal Accounts model, userAnyId identifies your principal account in Manteca, and sender carries the actual end-user identity (country, legal ID, name, surname). Under the End-user model, sender matches the user identified by userAnyId.



Example request

curl -X POST https://sandbox.manteca.dev/crypto/v2/payment-locks \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "against": "ARS",
    "paymentDestination": "00020101021140200010com.yacare02022350150011336972350495204739953030325802AR5910HAVANNA SA6012BUENOS AIRES81220010com.yacare0204Y2156304E401",
    "sender": {
      "legalIdNationality": "ARGENTINA",
      "legalId": "00000000000",
      "name": "JANE",
      "surname": "DOE"
    }
  }'
{
      "code": "fa44218d-7b3c-4a1e-bc9f-2d5e8f01c3a7",
      "type": "QR3",
      "companyId": "64a1b2c3d4e5f6a7b8c9d0e1",
      "userId": "64a1b2c3d4e5f6a7b8c9d0e2",
      "userNumberId": "12345",
      "userExternalId": "ext-001",
      "sender": {
          "name": "JANE",
				  "surname": "DOE",
          "legalId": "00000000000",
          "legalIdNationality": "ARGENTINA"
      },
      "paymentRecipientName": "Comercio SRL",
      "paymentRecipientLegalId": "30712345678",
      "paymentAssetAmount": "15000.00",
      "paymentAsset": "ARS",
      "paymentPrice": "1250.50",
      "paymentAgainstAmount": "12.00",
      "paymentAgainst": "USDT",
      "creationTime": "2026-02-21T15:25:00.000Z"
  }

Pass code as paymentCode to POST /v2/synthetics/qr-payment to execute.


Inputs

Required

  • paymentDestination: QR payload or supported key-style destination (depending on country/method).
  • against: asset/currency to debit from balance.
  • sender: payer information.

Conditionally required

  • amount: required when destination does not carry an embedded amount (for example key-based or open/pseudo-static flows).

What preview returns

A successful preview can return:

  • normalized payment destination data,
  • route/payment metadata,
  • pricing/conversion context,
  • and (when resolvable) a lock code for payment confirmation.

Lock behavior by QR type

QR typeFirst lock responseRequired for execution
Fixed-amount QRReturns code immediatelyUse code directly
Open-amount QRReturns QR info without codeSend second lock with amount to receive code
PIX key or phoneReturns code immediatelyamount must be included in the first lock

For Peruvian phone numbers, you can optionally send a network field (YAPE or PLIN) to specify the preferred payment network.

For Colombia Breb-Key email payments, you must send country field (COLOMBIA) to specify that is a email payment Breb-Key.

For Peru, payments are currently capped at 500 PEN per transaction. Lock requests above this amount are rejected with PAYMENT_MAX_AMOUNT.

Open-amount QR codes require two lock calls. The first call returns destination data. The second call—identical to the first but with amount added—returns the code for execution.



sender field requirements

Under the Principal Accounts model, sender is required on every lock request and must represent the real payer for compliance purposes. Without it, the lock fails with MISSING_PAYMENT_SENDER. Providing inaccurate data will cause payment rejection.

FieldRequiredDescription
legalIdNationalityYesPayer's country (e.g., ARGENTINA, BRAZIL, PERU). Accepts the full country name or ISO 3166-1 alpha-2 / alpha-3 codes — see the full list of accepted values. Matches the field name used by the Principal Accounts limits query.
legalIdYesNational ID or tax number
nameYesFirst name
surnameYesLast name

In Brazil, the same legalId must always come with the same payer. A legalId is registered under the payer's name on its first executed payment (or earlier, if it already belongs to a registered person). From then on, locks for that legalId are rejected with PAYER_NAME_MISMATCH if name and surname share no name with the registered one. Casing, accents and name order don't matter, and particles or suffixes such as da, dos, Filho or Junior don't count as a shared name.

The legacy exchange field is deprecated as the payer's country. The API still accepts it for backward compatibility, but new integrations must use legalIdNationality.

Country legalId patterns (common QR markets)

CountrySupported legalId typesAccepted pattern(s)
ArgentinaCUIT (and DNI as pseudo legalId when enabled)^\d{2}-?\d{8}-?\d{1}$, ^[\d]{1,3}\.?[\d]{3}\.?[\d]{3}$
BrazilCPF/CNPJ, RG^[0-9]{3}[.]?[0-9]{3}[.]?[0-9]{3}-?[0-9]{2}$, ^[0-9]{2}[.]?[0-9]{3}[.]?[0-9]{3}\/?[0-9]{4}\-?[0-9]{2}$, ^[0-9]{7,9}[0-9Xx]?$, ^[0-9]{2}\.[0-9]{3}\.[0-9]{3}-[0-9Xx]$
PeruDNI, CE`^\d8(\d-\d)?$, ^[A-Za-z0-9]12$`
BoliviaCI^\d{7,10}$, ^[A-Z]{2}\d{7,10}$, ^\d{7,10}[A-Z]{2}$
ColombiaNUIP, CC, PPT^\d{10}$, ^\d{6,10}$, ^[A-Za-z0-9]{6,15}$
ParaguayCI, RUC^\d{6,8}$, ^\d{8,9}$

An Argentine payer (legalIdNationality: ARGENTINA) paying a QR from another country (e.g. Brazil or Peru) may also send a passport as legalId, with pattern ^[A-Za-z]{1,3}[0-9]{5,8}$ (e.g. AAA123456). QR payments in Argentina still require CUIT or DNI. Payments with a fiat against that require a deposit still need CUIT or DNI.


Any-country behavior

If sender.legalIdNationality points to another supported market outside the main QR markets, validation still applies with that country's production legalId rules. For extended/global scenarios, generic legalId validation is available with:

  • ^[a-zA-Z0-9\-\/_.\\]{6,60}$

Some legalId types also apply checksum/algorithm validation in addition to regex format.


Did this page help you?