Guides
  1. Bill Payments

Bill Payments overview

Bill Payments let you settle utility bills, service subscriptions, tax obligations, and mobile top-ups on behalf of your users. The API connects to hundreds of companies across Argentina, Mexico, Colombia, Peru, and Chile. Payment is executed as a synthetic operation: funds are debited from the user's balance, converted if necessary, and forwarded to the biller in the local currency.

Bill types

TypeBehavioramount in lock
CLOSEDFixed amount set by the billerNot required; amount comes from the bill
OPENVariable amount within a minAmount/maxAmount rangeRequired
FIXEDChoose from an allowedAmounts arrayRequired; must match one of the allowed values

Payment flow

Step

Endpoint

Purpose

  1. Discover companies

GET /v2/info/bill-companies

List billers and their lookup methods

  1. Fetch outstanding bills

GET /v2/info/bill-companies/{code}/{methodId}/{type}/{refId}

Retrieve payable bills for a reference ID

  1. Lock payment

POST /v2/bill-locks

Validate bill data and get a code

  1. Execute payment

POST /v2/synthetics/bill-payment

Submit the payment using the lock code

  1. Track result

SYNTHETIC_STATUS_UPDATE webhook or GET /v2/synthetics/{id}

Confirm final status asynchronously


Status summary

StatusMeaning
STARTINGPayment created, processing not yet begun
ACTIVEFunds debited, payment being forwarded to biller
COMPLETEDPayment accepted; confirmationCode available in response
CANCELLEDPayment failed; all funds automatically returned to originating account

On CANCELLED, all funds are returned automatically. No manual refund action is required.


Settlement behavior

  • If the account already holds the bill's local settlement currency (e.g. ARS, MXN, COP, PEN, CLP), funds can be debited directly.
  • If the account uses USDT or another asset in against, conversion to local settlement currency is executed as part of the payment flow.

See Coverage for the full list of supported countries and currencies.


Section pages