> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bill Payments
> Let your users pay 700+ Mexican services β phone recharges, gift cards, utility bills, toll roads β from your pre-funded Chipi credits. One REST endpoint, 170+ brands, USDC settlement, no end-user wallet required.
The Bill Payments service is **live in Mexico** (MXN). You pre-fund Chipi credits in USDC; on each purchase Chipi debits your credits, fulfills with the provider in MXN, and lets you charge your own users however you want (card, transfer, in-app balance β that side is outside Chipi). You earn a configurable markup on every transaction.
## At a glance
Live SKUs across all 4 categories
Direct integrations with major Mexican carriers and providers
Phone, Gift Cards, Bills, Phone Bundles
Set your own per-transaction markup; we settle in USDC
## What's in the catalog
**35 carriers Β· 379 services**
Top up prepaid phone balance for any major Mexican carrier. Your users pay in USDC, the carrier sees a normal recharge.
β¦and 27 more carriers (FlashMobile, OUI, RediCoppel, FRC Mobile, ABIB, Beneleit, Megamovil, and others).
```bash theme={null}
curl -G "https://api.chipipay.com/v1/skus" \
--data-urlencode "chipiCategory=RECARGAS" \
--data-urlencode "carrierName=Telcel" \
--data-urlencode "limit=20" \
-H "x-api-key: $CHIPI_PUBLIC_KEY" \
-H "Authorization: Bearer $CHIPI_CUSTOMER_JWT"
```
Response is a paginated `{ data, total, page, limit, totalPages }` where each entry in `data` is an SKU (`{ id, name, chipiName, fixedAmount, currency, carrierName, ... }`). Pass an `id` to `POST /v1/sku-purchases` to charge β see the [Node guide](/services/bills/node).
**41 brands Β· 142 services**
Sell digital gift cards funded with crypto. Codes are delivered instantly after settlement.
β¦and 33 more brands (Innvictus, PUBG Mobile, Amazon Prime Video, and others).
```bash theme={null}
curl -G "https://api.chipipay.com/v1/skus" \
--data-urlencode "chipiCategory=GIFT_CARDS" \
--data-urlencode "carrierName=Amazon Gift Card" \
-H "x-api-key: $CHIPI_PUBLIC_KEY" \
-H "Authorization: Bearer $CHIPI_CUSTOMER_JWT"
```
**88 providers Β· 141 services**
Utility bills, toll roads, government services, cable / streaming subscriptions, beauty brand orders.
β¦plus water utilities (28 cities), state government services, and 60+ other providers.
```bash theme={null}
curl -G "https://api.chipipay.com/v1/skus" \
--data-urlencode "chipiCategory=GENERAL" \
--data-urlencode "carrierName=CFE" \
-H "x-api-key: $CHIPI_PUBLIC_KEY" \
-H "Authorization: Bearer $CHIPI_CUSTOMER_JWT"
```
**7 carriers Β· 48 services**
Postpaid plans, internet packages, and combo bundles.
**Logos** are hot-linked from the production catalog β when admin updates a logo, this page reflects it on the next docs build with no code change. **Carrier and SKU counts** are a static snapshot taken on **2026-05-19**; the live catalog continues to grow.
## Prerequisites
Before your first bill purchase you need three things in place:
1. **A Chipi org with an API key.** Get yours from `dashboard.chipipay.com` β API Keys. Use `pk_dev_...` while integrating (sandboxed, see below) and `pk_prod_...` for live traffic.
2. **A pre-funded credits balance.** Deposit USDC to your org's Chipi credits address (visible in the dashboard's Billing tab). Each PROD purchase debits this balance, not an end-user wallet. DEV purchases never touch it.
3. **A JWKS rule registered for your API key.** Every endpoint on this page (catalog reads, purchase POST, status polling) is guarded by Chipi's `BearerTokenGuard` and requires *both* an `x-api-key` header *and* a customer JWT in the `Authorization: Bearer` header. The JWT is issued by your auth provider; Chipi validates it against the JWKS URL you register (typically your auth provider's `.well-known/jwks.json`, e.g. `https://clerk.yourdomain.com/.well-known/jwks.json`).
## How it works
1. **Browse** the catalog with `GET /v1/skus` β filter by `category` + `carrierName` to find what you need.
2. **Buy** with `POST /v1/sku-purchases` β pass `skuId`, `skuReference` (phone number, account, etc.), `currencyAmount`, and any non-empty string as `transactionHash` (it's used as the idempotency key, not as an on-chain hash). Chipi debits your credits balance, returns a `PENDING` transaction immediately.
3. **Track** with `GET /v1/sku-purchases/:id` β poll until status is `SUCCESS` or `FAILED`. Most settle in under 5 seconds.
Full code (auth + the three endpoints + polling) is on the [Node guide](/services/bills/node).
## DEV sandbox
Every API key has a DEV (`pk_dev_...`) and PROD (`pk_prod_...`) variant. **DEV is a true sandbox**: every purchase succeeds deterministically, no real credits are debited, and the carrier is never called. Synthetic markers identify sandbox calls:
| Field | DEV value | PROD value |
| --------------- | -------------------------- | ---------------------------------------------- |
| `ledgerEntryId` | starts with `le-dev-` | real `LedgerEntry` row id |
| `skuFileNumber` | starts with `dev-sandbox-` | the carrier's actual fulfillment receipt |
| `status` | always `SUCCESS` | `PENDING` β `SUCCESS` or `FAILED` |
| `OrgBalance` | never mutated | debited by `currencyAmount` (converted to USD) |
Integrate against DEV freely β your credits balance is untouched and your test phone numbers will never receive an actual recharge. When you're ready to go live, swap the key prefix to `pk_prod_...` and the same code path runs against the real carrier.
## What you charge your users
How and how much you charge end users is up to you β Chipi never sees the end-user's payment. We settle the provider in MXN and debit your Chipi credits in USDC (FX rate captured at the time of the call). The optional `orgMarkup` field on the purchase body lets you record the markup you charged this end-user, which Chipi surfaces in your dashboard analytics.
> β
Verified against the live API on **2026-05-19** with a real production purchase: Virgin \$20 MXN recharge to a live phone, settled SUCCESS with TET file number returned in under 5 seconds.