Integrate bill payments

Let your users pay utility bills, services, taxes and mobile top-ups from their balance: you find the biller and the outstanding bill, lock the payment, execute it, and track it until the biller confirms it.

At a glance

  • Users: End-user model: the payer is the onboarded user in userAnyId. Principal Accounts model: you pay from your principal account and declare the real payer in sender on the lock.
  • Funds: Debited in the against currency you pick and converted to the bill's currency if needed. 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, or poll GET /crypto/v2/synthetics/{syntheticAnyId}.

How it works

  1. You list the billers with GET /crypto/v2/info/bill-companies and the user picks one and a lookup method.
  2. The user enters the reference for that method (barcode, customer number, phone) and you fetch the outstanding bills for it.
  3. You lock the chosen bill with POST /crypto/v2/bill-locks, sending amount when the bill type asks for it. The lock returns a code and the locked price.
  4. You execute the payment with POST /crypto/v2/synthetics/bill-payment, passing the lock code as billCode.
  5. You follow the synthetic until COMPLETED (store the confirmationCode) or CANCELLED (funds are returned automatically).

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

Find the biller

List the bill companies. Filter with exchange (country), productType (SERVICE or TOP_UP), partialName and paginate with page and limit. For the most used billers of a country, grouped by category, use GET /crypto/v2/info/popular-bill-companies?exchange=ARGENTINA (exchange defaults to ARGENTINA).

Request GET /crypto/v2/info/bill-companies?exchange=ARGENTINA&productType=SERVICE&partialName=agua&page=1&limit=50

Response

{
  "data": [
    {
      "code": "AR-S-0009",
      "name": "Aguas Danone",
      "productType": "SERVICE",
      "exchange": "ARGENTINA",
      "asset": "ARS",
      "supportedMethods": [
        {
          "id": "275ee934-7883-4076-888a-e9bb4bef8f5d",
          "type": "00NH-BAR",
          "description": "Aguas Danone pago por codigo de barras",
          "mode": "barcode"
        }
      ]
    }
  ],
  "page": 1,
  "pageSize": 50,
  "lastPage": 1,
  "totalCount": 1
}

Keep the company code and, from the method the user picks, its id and type. Use description and helpText (when present) as the label of the input you show the user.

2

Fetch the outstanding bills

Ask the user for the reference the method expects (the barcode number for a barcode method, the customer or contract number, the phone number for a top-up) and query the bills for it.

Request GET /crypto/v2/info/bill-companies/{companyCode}/{methodId}/{methodType}/{referenceId}

GET /crypto/v2/info/bill-companies/AR-S-0009/275ee934-7883-4076-888a-e9bb4bef8f5d/00NH-BAR/1234567890

Response

[
  {
    "id": "fc69e897-0854-4b9f-8454-076ebd03b41c-0",
    "companyCode": "AR-S-0009",
    "referenceId": "1234567890",
    "productType": "SERVICE",
    "asset": "ARS",
    "exchange": "ARGENTINA",
    "type": "OPEN",
    "amount": "7000",
    "minAmount": "7000",
    "maxAmount": "10000",
    "expireAt": "2026-12-04T00:00:00.000-03:00"
  }
]

The bill id is what you lock. When customerId comes filled, show it to the user so they can check the bill is theirs. type decides how amount works in the next step:

typeWhat it isamount on the lock
CLOSEDThe biller sets the amount (amount)Not needed; the bill amount is always used.
OPENThe user chooses the amount within minAmount and maxAmountRequired, within the range.
FIXEDThe user picks one of the allowedAmounts (typical for top-ups)Required, equal to one of allowedAmounts.

Do not pay a bill after its expireAt.

3

Lock the payment

The lock validates the bill and the amount, runs the compliance checks and fixes the conversion price until expireAt. against is the currency debited from the balance: the bill's local currency, USDT or USDC (default USDT). When it differs from the bill's asset, Manteca converts it as part of the payment.

Request POST /crypto/v2/bill-locks

The payer is the user in userAnyId.

{
  "userAnyId": "100036128",
  "billId": "fc69e897-0854-4b9f-8454-076ebd03b41c-0",
  "against": "USDT",
  "amount": "7000.00"
}

Response 201

{
  "code": "fa44218d-74f6-458e-aef8-c377c7d714c0",
  "userNumberId": "100036128",
  "paymentAsset": "ARS",
  "paymentAgainst": "USDT",
  "paymentAssetAmount": "7000.00",
  "paymentAgainstAmount": "5.49019608",
  "paymentPrice": "1275.00",
  "expireAt": "2026-12-01T16:21:14.959-03:00",
  "creationTime": "2026-12-01T16:16:14.959-03:00"
}

Show the user paymentAssetAmount (what the biller receives) and paymentAgainstAmount (what is debited) before confirming. If the lock expires, create a new one. You can read a lock back with GET /crypto/v2/bill-locks/{code}.

4

Execute the payment

Pass the lock code as billCode before expireAt. The lock already carries the user, so userAnyId is optional here. Send your own externalId to recognize the payment later.

Request POST /crypto/v2/synthetics/bill-payment

{
  "externalId": "bill-payment-001",
  "billCode": "fa44218d-74f6-458e-aef8-c377c7d714c0"
}

Response 201

{
  "id": "6931dea37cb84dd42b784e14",
  "numberId": "15964",
  "externalId": "bill-payment-001",
  "status": "STARTING",
  "type": "BILL_PAYMENT",
  "details": {
    "confirmationCode": null
  },
  "stages": {
    "1": {
      "stageType": "ORDER",
      "side": "SELL",
      "asset": "USDT",
      "against": "ARS",
      "assetAmount": "5.49019608",
      "price": "1275.00"
    },
    "2": {
      "stageType": "BILL_PAYMENT",
      "billId": "fc69e897-0854-4b9f-8454-076ebd03b41c-0",
      "asset": "ARS",
      "amount": "7000.00"
    }
  }
}

The creation response is not the final result. When against matches the bill currency there is no ORDER stage.

By default (disallowDebt: false), what the user's balance does not cover is taken from your pre-funded company balance. To use only the user's own balance, send "disallowDebt": true together with "skipDeposit": true when the user already holds the balance: the request then fails with 400 NO_FUNDS when the balance is short. Optional fields: sessionId to group operations, and payload, any object of your own that comes back on the synthetic.

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 bill-lock request. It filters funding accounts to that exact configured label and requires the deposit to match the label. It does not change network selection or the bill's payment destination. See Select a deposit account by label.

Retries and idempotency

Neither of these creates a second payment:

  • A billCode can be used for one payment only. Sending it again returns 400 DUPLICATE_REQUEST.
  • An externalId you already used returns 409 SYNTHETIC_EXISTS.

If a request times out, look the payment up by externalId with GET /crypto/v2/synthetics/{syntheticAnyId} before trying again. To pay again after a failure, start over from a new lock.

5

Track the operation

SYNTHETIC_STATUS_UPDATE fires on every status change. Poll GET /crypto/v2/synthetics/{syntheticAnyId} (by id, numberId or externalId) for recovery.

{
  "event": "SYNTHETIC_STATUS_UPDATE",
  "data": {
    "id": "6931dea37cb84dd42b784e14",
    "numberId": "15964",
    "externalId": "bill-payment-001",
    "status": "COMPLETED",
    "type": "BILL_PAYMENT",
    "details": {
      "confirmationCode": "ABC-123456"
    }
  }
}
StatusMeaningWhat to do
STARTING, ACTIVEFunds debited, payment on its way to the biller. Some billers take longer.Show the payment as processing.
COMPLETEDThe biller accepted the payment.Store details.confirmationCode and show it to the user: it is the biller's receipt.
CANCELLEDThe payment failed. All funds are returned automatically.Read the reason and tell the user. No refund action on your side.

On CANCELLED, the reason is in the errors array of the BILL_PAYMENT stage, formatted as L<number>: <message> (for example L8 for an expired bill, L9 for a bill already paid). Match on the L<number> prefix. The same reason is in cancellationReason of GET /crypto/v2/bill-payments/{billPaymentId}. All codes: cancellation codes.

6

Reconcile

Bill payments reconcile like any other synthetic:

WhatEndpoint
Past payments, filtered by status, type, from / to and moreGET /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

Errors

Handle errors by internalStatus, not by HTTP status. Do not retry a 409.

Full list: Bill Payments error handling.

Go deeper


Did this page help you?