Integrate charges

Collect a payment from a payer into one of your users. The payer pays in a supported crypto or fiat asset, and you choose the asset the user receives and, optionally, where it is settled.

At a glance

  • Users: the charge is received by one of your onboarded users (userAnyId). The payer does not need to be a Manteca user.
  • Funds: the payer's deposit funds the charge. Without a destination, the proceeds stay in the receiving user's balance.
  • Tracking: SYNTHETIC_STATUS_UPDATE webhooks, or poll GET /crypto/v2/synthetics/{syntheticAnyId}.

How it works

  1. Lock the charge: fix the asset the payer deposits (entryAsset), the asset the user receives (exitAsset) and the amount to receive (exitAmount). You get a code.
  2. Create the charge synthetic with that code as chargeCode, and an optional destination.
  3. Show the payer the address or QR returned in details.depositAddresses.
  4. The payer pays. Manteca detects the deposit, converts it if the assets differ, and settles to the destination if you gave one.
  5. Track the synthetic until COMPLETED or CANCELLED.

Before you start

{
  "notificationInfo": {
    "type": "WEBHOOK",
    "secret": "your-webhook-secret",
    "webhooks": {
      "SYNTHETIC_STATUS_UPDATE": "https://your-domain.com/webhooks/synthetic-status"
    }
  }
}

Webhooks are sent from four fixed IP addresses: allowlist all of them (see Webhooks).

1

Lock the charge

The lock fixes the conversion between entryAsset and exitAsset for a limited time, so the payer pays a known amount and the user receives exactly exitAmount. entryAsset can be a crypto asset or a fiat currency with an entry network in Coverage. userAnyId is the receiving user. All four fields are required.

Request POST /crypto/v2/charge-locks

{
  "userAnyId": "user-1001",
  "entryAsset": "BRL",
  "exitAsset": "USDT",
  "exitAmount": "100"
}

Response

{
  "code": "3363db60-4c5f-4486-9746-d2f005e444cb",
  "userId": "64f1e9f5b6c7d8e9f0098765",
  "userNumberId": "100009352",
  "userExternalId": "customer-001",
  "entryAsset": "BRL",
  "entryAmount": "552.75",
  "exitAsset": "USDT",
  "exitAmount": "100.00000000",
  "price": "5.50",
  "effectivePrice": "5.5275",
  "expireAt": "2026-07-02T16:30:00.000-03:00",
  "creationTime": "2026-07-02T15:30:00.000-03:00"
}

entryAmount is what the payer has to pay. Create the charge before expireAt; after that, request a new lock. You can read a lock back with GET /crypto/v2/charge-locks/{code}.

2

Create the charge

Only chargeCode is required. Each lock can be used once.

FieldRequiredWhat it does
chargeCodeYesThe code from step 1.
externalIdNoYour unique ID for the charge. Use it for idempotency and to look the charge up later.
destinationNo{ "address", "network" } where the proceeds are settled. Without it, the funds stay in the receiving user's balance.
senderNoRestricts a PIX charge to a single payer (see below).
depositNetworkNoNetwork you prefer the payer to deposit on.
sessionIdNoYour own session identifier, for correlation.
payloadNoYour own metadata. It comes back in the response and the webhooks.

Request POST /crypto/v2/synthetics/charge

{
  "chargeCode": "3363db60-4c5f-4486-9746-d2f005e444cb",
  "externalId": "ext-charge-002",
  "destination": {
    "address": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2",
    "network": "POLYGON"
  },
  "payload": {
    "invoiceId": "inv-001"
  }
}

For a crypto exitAsset, address is an on-chain address. For a fiat exitAsset, the destination is a bank account on that country's network (for example, a CBU, CVU or alias in Argentina, or a PIX key in Brazil). BANK_TRANSFER resolves to the country's default rail (PIX for BRL, SPEI for MXN, a regular transfer for ARS); pass a specific network to force one.

Restrict the payer (PIX)

For BRL charges paid by PIX, send the payer's CPF (11 digits) or CNPJ (14 digits) in sender:

{
  "chargeCode": "3363db60-4c5f-4486-9746-d2f005e444cb",
  "externalId": "ext-charge-003",
  "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 someone else pays, the payment is returned to the payer, no DEPOSIT_DETECTED is sent, and the charge moves to CANCELLED right away with the reason in stages["1"].errors. A later payment to the same QR is not credited either.

The payer restriction only runs in production. In sandbox, a payment from any account is credited.

3

Show the payer how to pay

The create response is the charge synthetic in STARTING. What you show the payer is in details:

Response (trimmed)

{
  "id": "64f1f5a5b6c7d8e9f0011111",
  "numberId": "2401",
  "externalId": "ext-charge-002",
  "status": "STARTING",
  "type": "CHARGE",
  "details": {
    "depositAddresses": {
      "PIX": {
        "type": "QR",
        "code": "00020126580014br.gov.bcb.pix...",
        "url": "https://widget.manteca.dev/qr?code=00020126580014br.gov.bcb.pix...",
        "expiresAt": "2026-07-02T16:30:00.000-03:00"
      }
    },
    "entryAsset": "BRL",
    "entryAmount": "552.75",
    "exitAsset": "USDT",
    "exitAmount": "100.00000000",
    "paymentPrice": "5.50",
    "priceExpireAt": "2026-07-02T16:30:00.000-03:00"
  },
  "currentStage": 1,
  "stages": {
    "1": { "stageType": "DEPOSIT", "asset": "BRL", "thresholdAmount": "552.75", "expireAt": "2026-07-02T19:30:00.000Z" },
    "2": { "stageType": "ORDER", "side": "BUY", "asset": "USDT", "against": "BRL", "assetAmount": "100.00000000", "price": "5.50" },
    "3": { "stageType": "WITHDRAW", "asset": "USDT", "amount": "100.00000000", "destination": { "address": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2", "network": "POLYGON" } }
  }
}

depositAddresses has one entry per network the payer can use:

Fiat entries return a QR bound to this charge: { "type": "QR", "code", "url", "expiresAt" }. Render code as a QR in your own UI, or show the image at url. The QR stops working at expiresAt.

Show entryAmount and entryAsset as the amount to pay. The deposit stage completes once the amount detected reaches entryAmount, so ask the payer to send that exact amount before the deposit stage expireAt.

Networks the payer can use, per asset: see Coverage.

The stages object always starts with a DEPOSIT stage (the payer's payment), followed by an ORDER stage when entryAsset and exitAsset differ and a WITHDRAW stage when you sent destination. A charge in the same asset with no destination is a single DEPOSIT stage, and the funds stay in the receiving user's balance. The stages object can also contain INTERNAL stages; skip them. Details: Charge lifecycle.

4

Track the operation

Each status change sends a SYNTHETIC_STATUS_UPDATE. The payload data is the same object that GET /crypto/v2/synthetics/{syntheticAnyId} returns; you can pass the externalId as syntheticAnyId.

{
  "event": "SYNTHETIC_STATUS_UPDATE",
  "data": {
    "id": "6a1eee5f36723d2aa07a9442",
    "externalId": "ext-charge-004",
    "status": "COMPLETED",
    "type": "CHARGE",
    "details": {
      "entryAsset": "ARS",
      "entryAmount": "7461.40",
      "exitAsset": "USDT",
      "exitAmount": "10.00000000"
    },
    "stages": {
      "1": { "stageType": "DEPOSIT", "asset": "ARS", "thresholdAmount": "7461.40", "detectedAmount": "7461.40" },
      "2": { "stageType": "ORDER", "side": "BUY", "asset": "USDT", "against": "ARS", "assetAmount": "10.00000000", "price": "746.14" },
      "3": { "stageType": "WITHDRAW", "asset": "USDT", "amount": "10.00000000", "destination": { "network": "POLYGON", "address": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2" } }
    },
    "payload": { "invoiceId": "inv-004" }
  }
}
StatusWhat it meansWhat to do
STARTING, ACTIVE, WAITING, PAUSEDCreated, waiting for the payment, or between stages.Keep waiting. Show the payment instructions until the payment arrives.
COMPLETEDAll stages finished.Mark the charge as paid. If there was a WITHDRAW stage, the funds were sent.
CANCELLEDThe charge closed without completing (for example, the payer did not pay in time, or a restricted PIX came from someone else).Read errors on the failing stage. Create a new lock and charge if you want to collect again.

The usual path is STARTING, ACTIVE, COMPLETED. Treat the webhook as the main signal and re-fetch the synthetic before closing your record. Every status and transition: Charge lifecycle.

Test 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. You receive the same SYNTHETIC_STATUS_UPDATE webhooks as in production.

Errors

Handle errors by internalStatus, not by HTTP status.

Do not retry a 409. See Charges error handling for the full list.

Go deeper


Did this page help you?