Billpay · Get started
Billpay concepts
Payees, payee types, references and the rules each payee defines.
Payee
A payee is a biller or service that your users can pay. Every payee has a payee_id (a UUID) that you send on balance, payment and top-up requests.
You get payees from List Payees or one at a time from Get Payee Details. The list is paginated and sorted alphabetically by display name.
Payee types
The type field tells you how to integrate with the payee.
| Type | What it is | Usually includes |
|---|---|---|
Bill |
A biller you pay with a reference | financial_rules, capabilities |
Topup |
Phone recharge packages | bundles |
EGift |
A gift card. See Gift Cards. | currency, images, redemption_info, price |
Categories
The category field is the payee’s industry. You can filter the list by one of these exact values:
Telecommunications, Telephone, Cable, Internet, Gas, Water, Electricity, Bank, Beauty, Unknown, Government, Transportation, Retail, Giftcard.
Actions
A payee offers one or more actions:
| Action | Meaning | Endpoint |
|---|---|---|
pay |
The payee accepts payments | /payments |
balance |
The payee supports balance lookups | /balances |
topup |
The payee sells phone recharge packages | /topups |
Reference (payer account)
The payer_account is the reference being paid, such as the account number on the user’s bill. With a balance lookup, the account number is all your user needs to see what they owe.
reference_config.regex is an optional regular expression you can use to validate the reference before you send it. It is null when no pattern is available.
Payee rules
Bill payees usually include two blocks that tell you what the payee accepts.
financial_rules
| Field | Meaning |
|---|---|
minimum_amount |
Minimum payment amount, as a decimal string in currency units |
maximum_amount |
Maximum payment amount, as a decimal string in currency units |
payment_type |
Supported payment mode: totals or partials |
accepts_expired |
Whether payments are accepted when the bill is expired |
capabilities
| Field | Meaning |
|---|---|
has_balance |
Whether you can run a balance lookup for this payee |
connection_mode |
How the payee integration is executed: online or batch |
Top-up bundles
Topup payees include bundles, the predefined top-up amounts. Values follow the format the API returns, which can be a string or a number.
Balance
A balance is the result of a lookup. It returns the amount due, the payee_name, the invoice_date, the due_date and a balance_id you can use to retrieve it again.
Payment
A payment is created when you pay a reference. The response includes a payment_id, the status and an auth_number. You can retrieve a payment by its ID at any time.
Idempotency key
idempotency_key is a unique value you generate so Monato can recognize a request from later ones. It is optional on payments and top-ups. It also appears in the daily conciliation file as your ID for each payment.
Client account
Retrieve Account returns your client name, email and account details, including the account status and balances.