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

FieldRequiredDescription
billCodeYescode from POST /v2/bill-locks
externalIdYesYour unique payment reference. A value already used returns 409 SYNTHETIC_EXISTS and creates nothing
userAnyIdNoIf 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.
disallowDebtNoIf 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
skipDepositNoIf true, skips the internal deposit step

Response fields

FieldDescription
idInternal synthetic ID
numberIdHuman-readable numeric ID
externalIdEchoed from your request
statusInitial status (STARTING); not final
stagesBreakdown of operations: stage 1 is the FX order (if applicable), stage 2 is the bill payment
details.confirmationCodenull until COMPLETED; populated with the biller's receipt code after success

confirmationCode

confirmationCode 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

Neither retry creates a second payment:

  • Each billCode can be used for a single payment. Resending a request with a billCode that was already used returns 400 DUPLICATE_REQUEST.
  • An externalId you already used returns 409 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.


Did this page help you?