After a bill payment

After a bill payment

Bill payment execution is asynchronous. Use webhooks as the primary mechanism for status updates.

Status transitions

STARTING → ACTIVE → COMPLETED
                  ↘ CANCELLED
StatusMeaning
STARTINGOperation created; processing not yet begun
ACTIVEFunds debited; payment being forwarded to the biller
COMPLETEDBiller accepted payment; confirmationCode is now available
CANCELLEDPayment failed; all funds automatically returned to the originating account

COMPLETED and CANCELLED are terminal. Close your internal processing once either is received.

On CANCELLED, the reason arrives in stages[].errors on the BILL_PAYMENT stage, as an L<number> code. See Error handling for the full table.

On CANCELLED, all funds are returned automatically. No refund action is required on your side.


Webhooks

Configure your webhook endpoint in PATCH /v2/company.

SYNTHETIC_STATUS_UPDATE payload

{
  "event": "SYNTHETIC_STATUS_UPDATE",
  "data": {
    "id": "6931dea37cb84dd42b784e14",
    "numberId": "15964",
    "externalId": "billpay-001",
    "status": "COMPLETED",
    "type": "BILL_PAYMENT",
    "details": {
      "confirmationCode": "ABC-123456",
      "sender": {
        "exchange": "ARGENTINA",
        "legalId": "00000000000",
        "name": "JANE",
        "surname": "DOE"
      }
    },
    "currentStage": 2,
    "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"
      }
    }
  }
}

SYSTEM_NOTICE webhooks are also recommended for operational alerts—configure both in your endpoint settings.


Retrieving confirmationCode

confirmationCode is populated only after COMPLETED. It appears in:

  • The SYNTHETIC_STATUS_UPDATE webhook payload under data.details.confirmationCode
  • The GET /v2/synthetics/{syntheticAnyId} response under details.confirmationCode

Store this value for reconciliation. It is the biller's official receipt identifier and may be required to resolve disputes.


Did this page help you?