Look up a balance and pay | Billpay

This guide covers the full flow: find the payee, check the balance, pay, and check the payment later.

1. Find the payee

Call List Payees. You can combine these filters. When you send more than one, all of them apply.

Query parameter	Filter
`page`	Page number, starting at 1
`name`	Case-insensitive match anywhere in the display name
`category`	Exact match on the category
`connection_mode`	`online` or `batch`
`has_balance`	`true` for payees that support balance lookups, `false` for payees that do not
`accepts_expired`	`true` for payees that accept payments on expired bills, `false` for payees that do not

curl "https://dev-api.finco.lat/api/v1/payees?category=Electricity&has_balance=true" \
  -H 'Authorization: Bearer your_api_key'

{
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  },
  "payees": [
    {
      "payee_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "CFE",
      "category": "Electricity",
      "type": "Bill",
      "reference_config": { "regex": "^[0-9]{10,12}$" },
      "financial_rules": {
        "minimum_amount": "1",
        "maximum_amount": "50000",
        "payment_type": "totals",
        "accepts_expired": false
      },
      "capabilities": { "has_balance": true, "connection_mode": "batch" }
    }
  ]
}

Before you continue, check the reference against reference_config.regex and the amount against financial_rules. See Concepts for what each field means.

2. Look up the balance

Only for payees with has_balance: true. This step is optional.

curl https://dev-api.finco.lat/api/v1/balances \
  -H 'Authorization: Bearer your_api_key' \
  -H 'Content-Type: application/json' \
  --data '{
    "payee_id": "0d93acf6-b63d-46e8-aa5f-6f2520462608",
    "payer_account": "041837057079959114"
  }'

{
  "balance_id": "4rsie1fb-b61b-44c3-a258-6a9d6e8572849",
  "payee_id": "0d93acf6-b63d-46e8-aa5f-6f2520462608",
  "payee_name": "AGUA DE CDMX (SACMEX)",
  "amount": "36.67",
  "payer_account": "041837057079959114",
  "currency": "MXN",
  "invoice_date": "2024-04-10T19:21:13.380Z",
  "due_date": "2024-04-20T19:21:13.380Z",
  "status": "completed",
  "metadata": {
    "payer_name": "PAYER",
    "payer_address": "PAYER ADDRESS"
  },
  "created_at": "2024-04-10T19:21:13.387Z"
}

Show the amount and due_date to your user. To read the same lookup again, call Retrieve Balance with the balance_id.

3. Pay

Send the payee_id, payer_account, amount and currency. idempotency_key is optional.

curl https://dev-api.finco.lat/api/v1/payments \
  -H 'Authorization: Bearer your_api_key' \
  -H 'Content-Type: application/json' \
  --data '{
    "payee_id": "0d93acf6-b63d-46e8-aa5f-6f2520462608",
    "payer_account": "U0000-19",
    "amount": 1000,
    "currency": "MXN",
    "idempotency_key": "client_side_idempotency_key"
  }'

{
  "payment_id": "0fcbe1fb-b61b-44c3-a258-6a9d6e801804",
  "payer_account": "U0000-19",
  "amount": 1000,
  "currency": "MXN",
  "payee_id": "0d93acf6-b63d-46e8-aa5f-6f2520462608",
  "status": "completed",
  "metadata": {},
  "created_at": "2024-04-10T19:48:43.222Z",
  "auth_number": "8459344721"
}

Store the payment_id and the auth_number. If the payment fails, you get a 422 with an error_type and an error_message. See Error codes.

4. Check a payment later

Call Retrieve Payment with the payment_id. It returns 404 if the payment does not exist.

Retrieve a payment

curl https://dev-api.finco.lat/api/v1/payments/429ee7cb-6eee-4fd2-8bb3-ad22f7f3c88e \
  -H 'Authorization: Bearer your_api_key'

The API also has a Verify Payment endpoint. It takes the same fields as a payment, with idempotency_key required.

Top-ups

For Topup payees, pick one of the payee’s bundles and call Create Topup with the payee_id, the amount and the phone_number. idempotency_key is optional.