Make a bill payment
Make a bill payment
Execute a bill payment with a synthetic operation using the code from POST /v2/bill-locks. The operation is asynchronous—the creation response reflects initial state only. Final status arrives via webhook or polling.
Execution request
curl -X POST https://sandbox.manteca.dev/crypto/v2/synthetics/bill-payment \
-H "md-api-key: $MD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "billpay-001",
"userAnyId": "100036128",
"billCode": "fa44218d-7b3c-4a1e-bc9f-2d5e8f01c3a7",
}'Execution response
{
"id": "6931dea37cb84dd42b784e14",
"numberId": "15964",
"externalId": "billpay-001",
"status": "STARTING",
"type": "BILL_PAYMENT",
"details": {
"confirmationCode": null,
"sender": {
"legalIdNationality": "ARGENTINA",
"legalId": "00000000000",
"name": "JANE",
"surname": "DOE"
}
},
"currentStage": 1,
"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"
}
}
}Request fields
| Field | Required | Description |
|---|---|---|
billCode | Yes | code from POST /v2/bill-locks |
externalId | Yes | Your unique payment reference. A value already used returns 409 SYNTHETIC_EXISTS and creates nothing |
userAnyId | No | If omitted, the payment runs for the user the bill lock was created for. Under the Principal Accounts model, the end user is declared via sender on the lock. |
disallowDebt | No | If true, only the user's own balance is used and the payment fails with NO_FUNDS if it does not cover it. If false (default), what the user's balance does not cover is taken from your pre-funded company balance |
skipDeposit | No | If true, skips the internal deposit step |
Response fields
| Field | Description |
|---|---|
id | Internal synthetic ID |
numberId | Human-readable numeric ID |
externalId | Echoed from your request |
status | Initial status (STARTING); not final |
stages | Breakdown of operations: stage 1 is the FX order (if applicable), stage 2 is the bill payment |
details.confirmationCode | null until COMPLETED; populated with the biller's receipt code after success |
confirmationCode
confirmationCodeconfirmationCode is only present after the synthetic reaches COMPLETED. Retrieve it from the webhook payload or from GET /v2/synthetics/{id}. Store it for reconciliation—it is the biller's official receipt identifier.
externalId as idempotency key
externalId as idempotency keyNeither retry creates a second payment:
- Each
billCodecan be used for a single payment. Resending a request with abillCodethat was already used returns400 DUPLICATE_REQUEST. - An
externalIdyou already used returns409 SYNTHETIC_EXISTS.
If your request times out or receives a network error, check whether the first payment was created before sending a new one (see After a bill payment).
Stages
When against differs from the bill currency, the operation runs in two stages:
- Stage 1 (
ORDER) — Sells the debit asset for the bill's settlement currency (e.g., USDT → ARS). - Stage 2 (
BILL_PAYMENT) — Forwards the converted amount to the biller.
When against matches the bill currency, only stage 2 runs.
Continue to After a payment to handle status updates.
Updated 27 days ago