> ## 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.

> [!NOTE]
>
> 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

> **700+ services**
>
> Live SKUs across all 4 categories

> **170+ brands**
>
> Direct integrations with major Mexican carriers and providers

> **4 categories**
>
> Phone, Gift Cards, Bills, Phone Bundles

> **Earn a markup**
>
> Set your own per-transaction markup; we settle in USDC

## What's in the catalog

**📱 Phone Recharges**

**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.

> **Telcel**
>
> ![Telcel](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/1__logotipo.png)

> **AT\&T**
>
> ![AT\&T (Iusacell - Nextel)](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/5__logotipo.png)

> **Movistar**
>
> ![Movistar](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/2__logotipo.png)

> **BAIT**
>
> ![BAIT](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/239__logotipo.png)

> **Mimovil**
>
> ![Mimovil](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/243__logotipo.png)

> **ULTRACEL**
>
> ![ULTRACEL](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/337__logotipo.png.png)

> **Axios Mobile**
>
> ![Axios Mobile](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/498__logotipo.png)

> **VALOR TELECOM**
>
> ![VALOR TELECOM](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/660__logotipo.png)

…and 27 more carriers (FlashMobile, OUI, RediCoppel, FRC Mobile, ABIB, Beneleit, Megamovil, and others).

> **See the integration code (Telcel example)**
>
> ```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).

**🎁 Gift Cards**

**41 brands · 142 services**

Sell digital gift cards funded with crypto. Codes are delivered instantly after settlement.

> **Amazon**
>
> ![Amazon Gift Card](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/166__logotipo.png)

> **Cinepolis**
>
> ![Cinepolis](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/148__logotipo.png)

> **Nintendo**
>
> ![Nintendo](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/80__logotipo.png)

> **Netflix**
>
> ![Netflix](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/87__logotipo.png)

> **Google Play**
>
> ![Google Play](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/211__logotipo.png)

> **Free Fire**
>
> ![FREE FIRE](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/342__logotipo.png.svg)

> **Cinemex**
>
> ![CINEMEX](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/613__logotipo)

> **Gandhi**
>
> ![GANDHI](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/348__logotipo.png.jpg)

…and 33 more brands (Innvictus, PUBG Mobile, Amazon Prime Video, and others).

> **See the integration code (Amazon example)**
>
> ```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"
> ```

**🧾 Bills & Services**

**88 providers · 141 services**

Utility bills, toll roads, government services, cable / streaming subscriptions, beauty brand orders.

> **CFE**
>
> ![CFE](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/7__logotipo.png)

> **Telmex**
>
> ![Telmex](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/6__logotipo.png)

> **Megacable**
>
> ![Megacable](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/18__logotipo.png)

> **Dish**
>
> ![Dish](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/19__logotipo.png)

> **Infonavit**
>
> ![Infonavit](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/17__logotipo.png)

> **Televia**
>
> ![Televia](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/41__logotipo.png)

> **IAVE**
>
> ![IAVE](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/644__logotipo.png)

> **Pase Urbano**
>
> ![Pase Urbano](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/653__logotipo.jpg)

…plus water utilities (28 cities), state government services, and 60+ other providers.

> **See the integration code (CFE example)**
>
> ```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"
> ```

**📞 Phone Bundles**

**7 carriers · 48 services**

Postpaid plans, internet packages, and combo bundles.

> **Telcel Internet Amigo**
>
> ![Telcel Internet Amigo](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/32__logotipo.png)

> **Paquetes BAIT**
>
> ![Paquetes BAIT](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/240__logotipo.png)

> **Paquete Amigo Sin Limite**
>
> ![Paquete Amigo Sin Limite](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/33__logotipo.png)

> **WimoTelecom Internet**
>
> ![WimoTelecom Internet](https://3wgrdw4bsjfmvg3p.public.blob.vercel-storage.com/logos/181__logotipo.png)

> [!TIP]
>
> **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.