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 insenderon the lock. - Funds: Debited in the
againstcurrency 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 pollGET /crypto/v2/synthetics/{syntheticAnyId}.
How it works
- You list the billers with
GET /crypto/v2/info/bill-companiesand the user picks one and a lookup method. - The user enters the reference for that method (barcode, customer number, phone) and you fetch the outstanding bills for it.
- You lock the chosen bill with
POST /crypto/v2/bill-locks, sendingamountwhen the bill type asks for it. The lock returns acodeand the locked price. - You execute the payment with
POST /crypto/v2/synthetics/bill-payment, passing the lockcodeasbillCode. - You follow the synthetic until
COMPLETED(store theconfirmationCode) orCANCELLED(funds are returned automatically).
Before you start
- End-user model: the user must be onboarded and active. See Onboard a new user and Country requirements.
- Supported countries and their currencies: see Coverage.
- Register the webhook with
PATCH /crypto/v2/company:
{
"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).
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).
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.
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:
type | What it is | amount on the lock |
|---|---|---|
CLOSED | The biller sets the amount (amount) | Not needed; the bill amount is always used. |
OPEN | The user chooses the amount within minAmount and maxAmount | Required, within the range. |
FIXED | The user picks one of the allowedAmounts (typical for top-ups) | Required, equal to one of allowedAmounts. |
Do not pay a bill after its expireAt.
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"
}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 bill's country.
{
"billId": "fc69e897-0854-4b9f-8454-076ebd03b41c-0",
"against": "USDT",
"amount": "7000.00",
"sender": {
"legalIdNationality": "ARGENTINA",
"legalId": "20300000003",
"name": "JUAN",
"surname": "PEREZ"
}
}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}.
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
billCodecan be used for one payment only. Sending it again returns400 DUPLICATE_REQUEST. - An
externalIdyou already used returns409 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.
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"
}
}
}| Status | Meaning | What to do |
|---|---|---|
STARTING, ACTIVE | Funds debited, payment on its way to the biller. Some billers take longer. | Show the payment as processing. |
COMPLETED | The biller accepted the payment. | Store details.confirmationCode and show it to the user: it is the biller's receipt. |
CANCELLED | The 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.
Reconcile
Bill payments reconcile like any other synthetic:
| What | Endpoint |
|---|---|
Past payments, filtered by status, type, from / to and more | 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 |
Errors
Handle errors by internalStatus, not by HTTP status. Do not retry a 409.
Full list: Bill Payments error handling.
Go deeper
- Coverage: countries, currencies and bill types.
- Bill payment lifecycle: status transitions and timing.
- Discover bills: every query parameter and bill field.
- Bill Payments error handling: all lock errors and
Lcancellation codes. - Reconciliation and reporting.
- Onboarding models: End-user vs Principal Accounts.
Updated 15 days ago