Billy API

Billy is FinFactory's bills-payment API. Look up any Philippine biller, quote the fee, and pay the bill — from inside your app.

Billy exposes a large and growing catalog of Philippine billers through a single, versioned REST API — the most important billers are already here, and more are added over time. Every response is JSON, every request is authenticated with a partner API key, and the whole surface is described by a hand-authored OpenAPI 3.0 specification you can use to generate SDKs.

The model

A typical integration is four steps:

Fund your float — Billy pays billers out of a balance you top up in advance. No float, no payments.
Look up a biller — search the catalog and read its field schema so you can render the right form.
Quote the fee — send an amount, get back the convenience fee and customer total before the customer commits.
Pay the bill — post the payment; Billy reserves the money, posts to the biller, and tells you the outcome by webhook.

The float is the part most integrations underestimate. Read Your float early — it explains the balance, holds, and why a payment can come back 402.

Base URL

https://bills.finfactory.dev/api/v1

Every endpoint except the OpenAPI spec and this documentation requires an API key. Authenticated requests are limited to 120 per minute per partner.

What you can do

Resource	What it gives you
Categories	Biller categories with active biller counts.
Billers	Paginated, filterable, searchable list of billers available to your account.
Biller detail	One biller with its field schema (including validation regexes), current fee, and policies.
Quote	A fee quote for a given amount against a biller.
Payments	Pay a bill, then read it back or list your payment history.
Refunds	Reverse a settled payment, in full or in part.
Wallet	Your float balance, per-currency balances, and a statement of every movement.
Top-ups	Add funds to your float and track when they land.
Webhook deliveries	The delivery log for every event Billy has sent you.

Two ways to fund a payment

Every payment is funded one of two ways, chosen per payment with funding_source:

Funding source	How it works
`wallet` (default)	The money comes out of your prefunded float. You've already collected from your customer however you like.
`collect`	Billy collects from the end-user first, via a hosted checkout, then pays the biller. Your float isn't touched.

See Making a payment for both flows.

Money, precisely

Every amount Billy returns is a decimal string with exactly two places — "1500.00", never 1500 or 1500.0. Internally Billy stores money as whole centavos, never as a floating-point number: fractions of a cent across millions of bills add up to a real hole in real money. Send amounts as numbers or numeric strings; you will always get strings back.

New here? Jump straight to the Quickstart and make your first call.

SDKs & tooling

Generated clients are available for PHP, Python, and TypeScript, all built from the OpenAPI spec. A Postman collection is included for exploring the API interactively.