# Fricopay API documentation

> One API key for airtime, data, bills, SMS, virtual numbers and more, plus Fricobiz to collect Mobile Money payments. Paid from a wallet in Ghana cedis (GHS).

Base URL: https://fricopay.com
Authentication: header `Authorization: Bearer fp_...` on every request (the developer key from https://fricopay.com/developer).
Machine-readable spec: https://fricopay.com/openapi.json
Human docs: https://fricopay.com/portal


---

FRICOPAY DEVELOPERS
# Build on Fricopay

One API key for airtime, data, bills, SMS and more, plus Fricobiz to collect Mobile Money payments. Paid from your wallet in cedis.

[Get your API key](https://fricopay.com/developer)[Quickstart](https://fricopay.com/portal#/overview/quickstart)

## Quickstart

Make your first request in about two minutes.

1. **Get your API key**: Open [Developer](https://fricopay.com/developer) in the Fricopay app. Your key is there, and starts with `fp_`.

2. **Fund your wallet**: On the same Developer page, tap **Get payment details**. Send Mobile Money to the number shown and put your unique reference in the Reference box. Your wallet is credited automatically a moment later.

3. **Send a request**: Pass the key as a Bearer token. This one is free and lists the data networks and prices:

```
curl https://fricopay.com/devapi/cheap-data/networks \
  -H "Authorization: Bearer YOUR_KEY"
```

1. **Listen for results**: Orders finish in seconds or minutes. Set a [webhook](https://fricopay.com/portal#/webhooks) and we tell you the moment one changes, or check the status yourself.

## The basics

| Base URL | `https://fricopay.com` |
| --- | --- |
| Format | JSON in, JSON out. Send `Content-Type: application/json` with a body. |
| Authentication | `Authorization: Bearer fp_xxx`. See Authentication. |
| Wallet | Fund it from Developer by Mobile Money. Calls that sell something are paid from it. |
| Currency | Everything is priced and charged in Ghana cedis (GHS). |
| Rate limit | 150 requests per minute per key. See errors. |
| Collecting payments | Use Fricobiz. It uses the same key and has its own webhook. |

## Explore the APIs

[Build with AIGive your AI assistant our docs and let it write the integration for you.](https://fricopay.com/portal#/ai)[FricobizCollect Mobile Money payments on your own number, with a hosted pay page, checkout and signed webhooks.](https://fricopay.com/portal#/fricobiz)[AirtimeSend airtime to MTN, Telecel and AirtelTigo numbers from your app, paid from your wallet.](https://fricopay.com/portal#/airtime)[Data bundlesList the bundles available for a number, then buy the one you want.](https://fricopay.com/portal#/data)[Cheap dataSell affordable data bundles at live wholesale prices, delivered in about a minute.](https://fricopay.com/portal#/cheapdata)[Bills and utilitiesPay TV subscriptions, ECG electricity and Ghana Water bills, and look up SIM owners.](https://fricopay.com/portal#/utilities)[Virtual numbersBuy a temporary phone number, wait for the SMS code, and read it from the API.](https://fricopay.com/portal#/virtual)[SMSSend transactional SMS to Ghana numbers with your own sender ID.](https://fricopay.com/portal#/sms)[Social boostSell followers, likes and views on TikTok, Instagram, YouTube and more.](https://fricopay.com/portal#/booster)[Result checkersSell WAEC and BECE result checkers and get the serial and PIN back.](https://fricopay.com/portal#/checker)[AFA registrationRegister customers for MTN AFA straight from your app.](https://fricopay.com/portal#/afa)[Football dataLive scores, results, fixtures and predictions for matches worldwide.](https://fricopay.com/portal#/football)[Bet code converterConvert a bet code from one bookie to another.](https://fricopay.com/portal#/betconverter)

---

# Authentication

Every request is signed with your API key. Here is how to get one, send it, and keep it safe.

## Get your API key

Your key identifies your account and decides which wallet is charged.

1. **Open Developer**: In the Fricopay app, open the menu and choose [Developer](https://fricopay.com/developer).
2. **Copy your key**: Tap the eye to reveal it, then Copy. A key looks like `fp_` followed by letters and numbers.
3. **Use it on your server**: Send it with every request, as shown below.

## Send the key

Add it as a Bearer token in the `Authorization` header.

```
curl https://fricopay.com/devapi/cheap-data/networks \
  -H "Authorization: Bearer YOUR_KEY"
```

The same key works for Fricobiz too. Only Fricobiz test mode has a separate test key, which starts with `fbt_`. See [Fricobiz](https://fricopay.com/portal#/fricobiz).

## Fund your wallet

Services you sell through the API are paid from your Fricopay wallet. Fund it without leaving Developer.

1. **Enter an amount**: On [Developer](https://fricopay.com/developer), choose how much to add, from GHS 10 to GHS 5,000.
2. **Send the money**: Send Mobile Money from any number to the number we show. Type your unique reference in the Reference box, exactly as shown.
3. **It is credited for you**: We match your payment and add it to your wallet automatically. No fee.

**Only send to the number we show**

Money sent to any other number, or without your reference, cannot be matched to your wallet. Payments of GHS 500 or more are checked by our team before they are credited.

## Test with your own key

Paste your key in the box at the bottom of the left menu and every sample on this site fills it in for you. It is saved only in this browser.

## Keep it safe

**Your key can spend your money**

Anyone with the key can make purchases from your wallet. Keep it on your server and never put it in a mobile app, a web page or a public repository.

- Call the API from your backend, not from the browser.
- Store the key in an environment variable or a secrets manager.
- If a key leaks, make a new one in Developer. The old key stops working straight away.

## Problems with your key

| Message | What it means |
| --- | --- |
| Missing API key | The `Authorization` header is missing or does not start with `Bearer `. |
| Invalid API key format | The key must start with `fp_`. |
| Invalid API key | No account has this key. Check for a copy and paste mistake. |
| API key revoked | The key was replaced or switched off. Use your current key from Developer. |

---

# Responses and errors

Every response is JSON. Success and failure follow the same simple shape.

## Response shape

Successful calls return the data you asked for with `"ok": true`. Failed calls return `"ok": false` and a plain `error` message you can show or log.

```
{
  "ok": true,
  "tx_id": "XNzAGOboUPPxeuKljGoJ",
  "status": "submitted"
}
```

```
{
  "ok": false,
  "error": "Invalid API key"
}
```

## HTTP status codes

| Status | Meaning |
| --- | --- |
| 200 | The request worked. Read the body for the result. |
| 400 | Something in your request is missing or invalid. The `error` message says which field. |
| 401 | Your API key is missing, wrong or revoked. See Authentication. |
| 402 | Your wallet balance is too low for this purchase. Add money and try again. |
| 404 | The order, reference or route was not found on your account. |
| 429 | Too many requests. Slow down and retry after the number of seconds in the `Retry-After` header. |
| 5xx | Something went wrong on our side, or a supplier is down. If you were charged for an order that did not go through, it is refunded. |

## Rate limits

Each key can make up to **150 requests per minute**. Go over and you get `429` with a `Retry-After` header. Some endpoints have their own, lower limits.

## Handling orders safely

- Orders are not always instant. Treat `pending` and `placed` as in progress, and wait for a final status.
- Use a [webhook](https://fricopay.com/portal#/webhooks) to learn about final status without polling.
- If a request times out, check the order status before sending it again, so you never buy twice.
- Where an endpoint takes an `external_order_id` or `user_reference`, send your own ID. It makes your records easy to match.

---

# Webhooks

Get a signed callback the moment an order or payment changes status, instead of polling.
HMAC-SHA256 signedAutomatic retriesOne page for everything

## Fricobiz payments

The webhook for collecting payments. We call you the moment a customer's payment is paid.

1. **Set your address**: In the Fricobiz section of the Fricopay app, save a webhook URL that starts with `https://`, and copy the signing secret. You can also pass a `callbackUrl` when you create a payment to use a different address for that one.
2. **Receive the call**: We `POST` JSON to your URL when a payment is paid.
3. **Check it, then reply**: Verify the signature, mark the order paid once, and reply with a `2xx` status.

| Event | Sent when |
| --- | --- |
| `payment.paid` | A payment was paid. This includes payments the owner confirmed by hand, which also carry `confirmedByOwner`. |

```
{
  "event": "payment.paid",
  "id": "9f2c1b7a4d5e6f708192a3b4",
  "reference": "order_12345",
  "amount": 50,
  "amountReceived": 50,
  "currency": "GHS",
  "payer": "AMA MENSAH",
  "network": "MTN",
  "paidAt": 1792500123456
}
```

| Header | Value |
| --- | --- |
| `X-Fricobiz-Signature` | `t=<unix seconds>,v1=<hex>`. The hex is an HMAC-SHA256 of `t + "." + rawBody` with your signing secret. |
| `X-Fricobiz-Event` | The event name, for example `payment.paid`. |
| `Content-Type` | `application/json` |
| `User-Agent` | `Fricobiz-Webhook/1` |

## Verify the signature

Compute the HMAC over the raw body, not over parsed JSON, and reject calls with an old timestamp.

```
import crypto from 'crypto';

// rawBody is the exact text we sent, before any JSON parsing.
export function isFromFricobiz(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t))  {
  if (!isFromFricobiz(req.body.toString(), req.get('X-Fricobiz-Signature') || '', process.env.FRICOBIZ_WEBHOOK_SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString());
  // event.event === 'payment.paid': mark the order paid, once
  res.sendStatus(200);
});
```

```
import hmac, hashlib, time

def is_from_fricobiz(raw_body: str, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    expected = hmac.new(secret.encode(), f"{parts.get('t')}.{raw_body}".encode(), hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts.get('t', 0))) - Reply with any `2xx` status within 8 seconds. Redirects are not followed.
- If we do not get one, we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours.
- The same event can arrive more than once, so make your handler safe to run twice. The payment `id` is a good key.
- Missed one? Call [Get a payment](https://fricopay.com/portal#/fricobiz) to see the current status.

## Order events

The services API (airtime, data, bills and more) sends its own events when one of your orders changes.

Set the address in [Developer](https://fricopay.com/developer) in the Fricopay app. It has its own signing secret.

| Event | Sent when |
| --- | --- |
| `order.placed` | An order was accepted and is being delivered. |
| `order.delivered` | An order was delivered. |
| `order.failed` | An order failed. Any charge is refunded to your wallet. |
| `order.refunded` | An order was refunded. |

```
{
  "event": "order.placed",
  "data": {
    "service": "cheap_data",
    "reference": "MN-XXXX",
    "networkKey": "YELLO",
    "recipient": "0240000000",
    "capacity": 1,
    "amount": 4,
    "status": "placed"
  },
  "timestamp": "2026-05-24T21:00:00.000Z"
}
```

Order events are sent with the headers `X-FricoPay-Signature` (a hex HMAC-SHA256 of the raw body) and `X-FricoPay-Event`. We make up to 3 attempts, one and two seconds apart.

```
import crypto from 'crypto';

// Order events are signed with a plain hex HMAC-SHA256 of the raw body, using your signing secret from Developer.
export function isFromFricopay(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

---

# Build with AI

Let your AI coding assistant read our docs and write the integration for you.

## How it works

Works with Claude, ChatGPT, Cursor, Copilot and any assistant that can open a link.

1. **Give it the docs**: Paste the link to `fricopay.com/llms-full.txt` into your assistant. It reads every endpoint, field and status in one go.
2. **Tell it what to build**: For example: sell data bundles, send airtime, or collect Mobile Money payments. Use a ready-made prompt below.
3. **Keep your key private**: The assistant writes code that reads your key from an environment variable. You never paste the key into the chat.

## Links for your assistant

Three plain files, always up to date with this site.

| File | What it is |
| --- | --- |
| `/llms.txt` | A short index of the docs. Good starting point for tools that browse. |
| `/llms-full.txt` | The whole documentation in one plain-text file. Best to paste into an assistant. |
| `/openapi.json` | The API spec in the OpenAPI format. Use it to generate a client or import into Postman. |

## Ready-made prompts

Copy one, change the last line to what you need, and paste it into your assistant.

**Any task**

```
You are helping me build on the Fricopay API.
Read https://fricopay.com/llms-full.txt first. It is the full documentation.
The machine-readable spec is https://fricopay.com/openapi.json.

Rules:
- Base URL is https://fricopay.com. Authenticate every request with the header Authorization: Bearer .
- Read my API key from the environment variable FRICOPAY_API_KEY. Never write the key into code, logs or chat.
- Call the API from my server only, never from a browser or mobile app.
- Amounts are in Ghana cedis (GHS). Phone numbers are 10 digits starting with 0.
- Use the order reference to check status, and verify webhook signatures as the docs describe.

Task:
```

**Sell data bundles**

```
Read https://fricopay.com/llms-full.txt, then add data bundle sales to my app using the Cheap data API.
1. Call GET /devapi/cheap-data/networks to list networks and prices, and show them to my customer.
2. When they choose one, call POST /devapi/cheap-data/purchase with networkKey, recipient and capacity.
3. Save the reference from the reply, then check GET /devapi/cheap-data/orders/:reference or listen for the webhook.
4. Treat placed and processing as in progress, success as delivered, and failed as refunded.
Read the key from FRICOPAY_API_KEY. Never hard-code it.
```

**Collect payments**

```
Read https://fricopay.com/llms-full.txt, then add Mobile Money checkout to my website using Fricobiz Collect.
1. On my server, call POST /fbapi/v1/payments with the amount and my own order reference.
2. Send the customer to the payUrl in the reply.
3. Receive the signed webhook, verify its signature, and only then mark the order as paid. Never trust the browser.
4. Use my test key (fbt_) while building so no real money moves.
Read the key from FRICOPAY_API_KEY. Never hard-code it.
```

## Stay safe

**Your key can spend your money**

An assistant that reads our docs cannot spend anything. Only your own code with your key can. Do not paste your key into an AI chat.

- Put the key in an environment variable such as `FRICOPAY_API_KEY`.
- Test with a small amount first, and read the code before you run it.
- Ask the assistant to protect purchases from being sent twice: check the order reference before retrying.
- If a key is exposed, make a new one in [Developer](https://fricopay.com/developer). The old one stops working at once.

---

# Fricobiz

Collect Mobile Money payments on your own number, with a hosted pay page, checkout and signed webhooks.
Mobile Money collectionsTest mode, no real moneySigned webhooks

## How it works

Fricobiz turns your own phone into a payment gateway. Customers send Mobile Money to your number, the Fricobiz app reads the confirmation, and your site is told the payment is paid.

1. **Set up Fricobiz**: Open [Fricobiz](https://fricopay.com/fricobiz) in the Fricopay app, subscribe, install the Fricobiz app on the phone that receives the money, and connect and verify your number.

2. **Create a payment**: From your server, call `POST /fbapi/v1/payments`. You get back a unique `code` and a hosted pay page.

3. **The customer pays**: They send the amount to your number with the code as the reference, or open the pay page, which shows them exactly what to do.

4. **We tell your site**: When the money arrives, the payment becomes `paid` and we send a signed [webhook](https://fricopay.com/portal#/webhooks). Credit the order from that, never from the browser.

## Your keys

| Key | Looks like | Use it for |
| --- | --- | --- |
| Live | `fp_` + 48 characters | Real payments. This is your Fricopay API key, the same one every other API uses. Money goes to your verified number. |
| Test | `fbt_` + 48 characters | Trying your whole flow with no money. Test payments are marked `sandbox`. |

Find both in the Fricobiz section of the app. Keys that start with `fb_` were issued earlier and still work. Send either one as `Authorization: Bearer ...`. Keep keys on your server. A key stops working if your Fricobiz plan has ended, until you renew.

## Endpoints

### Create a payment

Creates a payment that waits for the customer. It is valid for **30 minutes**. Amounts are between GHS 1 and GHS 10,000.

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | number | Required. In cedis, for example `50`. |
| `reference` | string | Your own order or customer ID. Returned to you everywhere. Up to 64 characters. |
| `customerName` | string | Optional. Used to compare against the name on the Mobile Money message. |
| `callbackUrl` | string | Optional, https only. Where to send the webhook for this payment instead of your default. |
| `returnUrl` | string | Optional, https only. Where the pay page sends the customer afterwards. |

Send an `Idempotency-Key` header so a retry never creates a second payment. The same key always returns the same payment.

```
curl -X POST https://fricopay.com/fbapi/v1/payments \
  -H "Authorization: Bearer fp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{"amount": 50, "reference": "order_12345", "customerName": "Ama Mensah", "callbackUrl": "https://yoursite.com/webhooks/fricobiz", "returnUrl": "https://yoursite.com/thanks"}'
```

**Response**

```
{
  "ok": true,
  "payment": {
    "id": "9f2c1b7a4d5e6f708192a3b4",
    "reference": "order_12345",
    "amount": 50,
    "status": "pending",
    "code": "K7M2QX",
    "expiresAt": 1792500000000,
    "business": "Ama Stores",
    "payTo": [{ "number": "0241234567", "network": "MTN", "name": "Ama Stores" }],
    "payUrl": "https://fricopay.com/pay/9f2c1b7a4d5e6f708192a3b4"
  }
}
```

### Get a payment

Returns the payment with its current status. Use it to check on demand, for example if a webhook never arrived.

```
curl https://fricopay.com/fbapi/v1/payments/PAYMENT_ID \
  -H "Authorization: Bearer fp_YOUR_KEY"
```

## Payment statuses

| Status | Meaning |
| --- | --- |
| `pending` | Waiting for the customer to pay. |
| `paid` | The money arrived and was matched. Safe to deliver the order. |
| `review` | Money arrived, but something did not match (wrong amount, a late payment, an amount of GHS 500 or more). The owner confirms it in the Fricobiz app, and it then becomes `paid` or `rejected`. |
| `rejected` | The owner declined it. |
| `expired` | No payment arrived in time. Late money is still kept for the owner to confirm. |

## Checkout

Show the hosted pay page on top of your own site, without sending the customer away.

Create the payment on your server, pass its `payUrl` to the page, then open it:

```

  // payment.payUrl comes from POST /fbapi/v1/payments, created on YOUR SERVER
  Fricobiz.checkout({
    payUrl: payment.payUrl,
    onSuccess: function (p) { /* p = { id, reference, amount, status } */ },
    onClose: function () { /* the customer closed it */ }
  });

```

Or add the pay link to any button or link:

```
[Pay with Mobile Money](#)
```

**Never trust the browser**

`onSuccess` is only a convenience for your page. Credit the order from the [webhook](https://fricopay.com/portal#/webhooks), or by calling **Get a payment** from your server.

The pay page shows the number to pay and the reference, counts down the time left, and lets the customer confirm with the transaction ID from their Mobile Money message if the match is slow. It also has a help box for questions about the payment.

## Test mode

Use your `fbt_` key to try the whole flow with no money.

- Create payments with the test key. They work exactly like live ones, and are marked `sandbox`.
- Open the pay page of a test payment and use the buttons there to pretend the customer paid, or that it needs review.
- Your webhook fires as normal, with `"sandbox": true` in the body.

## Chat widget

Add a live chat bubble to your site. Messages reach you in the Fricobiz app.

Paste this before the closing `</body>` tag. Your widget ID is in the Chat settings of the Fricobiz app.

```

```

---

# Airtime

Send airtime to MTN, Telecel and AirtelTigo numbers from your app, paid from your wallet.

## Networks

Pass one of these in the `network` field:

| Value | Network |
| --- | --- |
| `MTN` | MTN Ghana |
| `TELECEL` | Telecel Ghana (Vodafone) |
| `AT` | AirtelTigo Ghana |

## Endpoints

### Send MTN airtime

```
curl -X POST https://fricopay.com/devapi/v1/airtime \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"MTN","phone":"233241234567","amount":5,"user_reference":"u_123"}'
```

### Send Telecel airtime

```
curl -X POST https://fricopay.com/devapi/v1/airtime \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"TELECEL","phone":"233201234567","amount":5,"user_reference":"u_123"}'
```

### Send AirtelTigo airtime

```
curl -X POST https://fricopay.com/devapi/v1/airtime \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"AT","phone":"233271234567","amount":5,"user_reference":"u_123"}'
```

### Check status

Use only if your callback didn't fire after 5 minutes. `reference` is returned from the buy call.

```
curl https://fricopay.com/devapi/v1/status/REFERENCE \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Data bundles

List the bundles available for a number, then buy the one you want.

## Networks

Pass one of these in the `network` field:

| Value | Network |
| --- | --- |
| `MTN` | MTN Ghana |
| `TELECEL` | Telecel Ghana (Vodafone) |
| `AT` | AirtelTigo Ghana |

## Step 1 — List bundles for a number

### MTN bundles

```
curl "https://fricopay.com/devapi/v1/data/bundles?network=MTN&phone=233241234567" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Telecel bundles

```
curl "https://fricopay.com/devapi/v1/data/bundles?network=TELECEL&phone=233201234567" \
  -H "Authorization: Bearer YOUR_KEY"
```

### AirtelTigo bundles

```
curl "https://fricopay.com/devapi/v1/data/bundles?network=AT&phone=233271234567" \
  -H "Authorization: Bearer YOUR_KEY"
```

## Step 2 — Buy the chosen bundle

### Buy MTN bundle

Use the `bundle_id` and matching `price` from Step 1 as `amount`.

```
curl -X POST https://fricopay.com/devapi/v1/data \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"MTN","phone":"233241234567","bundle_id":"data_bundle_1","amount":0.5,"user_reference":"u_123"}'
```

### Buy Telecel bundle

```
curl -X POST https://fricopay.com/devapi/v1/data \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"TELECEL","phone":"233201234567","bundle_id":"DATANVSTRDLY","amount":0.5,"user_reference":"u_123"}'
```

### Buy AirtelTigo bundle

```
curl -X POST https://fricopay.com/devapi/v1/data \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"AT","phone":"233271234567","bundle_id":"db_BigTime_Data_51MB_1GHC","amount":1,"user_reference":"u_123"}'
```

## Status

### Check status

Use only if your callback didn't fire after 5 minutes. `reference` is returned from the buy call.

```
curl https://fricopay.com/devapi/v1/status/REFERENCE \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Cheap data

Sell affordable data bundles at live wholesale prices, delivered in about a minute.
MTN 1GB from GHS 4.00MTN 1GB from GHS 4.00Auto-refund on failureAuto-refund on failureOrder status lookupOrder status lookup- Live prices, refreshed regularly
- 4 networks: MTN, AT iShare, AT BigTime, Telecel
- Reseller-grade reliability

## Endpoints

### List networks & packages

`GET /devapi/cheap-data/networks` · FREE

```
curl https://fricopay.com/devapi/cheap-data/networks \
  -H "Authorization: Bearer YOUR_KEY"
```

### Check beneficiary (MTN only)

`POST /devapi/cheap-data/verify-beneficiary` · FREE

```
curl -X POST https://fricopay.com/devapi/cheap-data/verify-beneficiary \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "networkKey": "YELLO",
    "recipient": "0241234567"
  }'
```

### Purchase data bundle

`POST /devapi/cheap-data/purchase` · Paid (see /networks for prices)

```
curl -X POST https://fricopay.com/devapi/cheap-data/purchase \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "networkKey": "YELLO",
    "recipient": "0241234567",
    "capacity": 1
  }'
```

### Check order status

`GET /devapi/cheap-data/orders/:reference` · FREE

```
curl https://fricopay.com/devapi/cheap-data/orders/REFERENCE \
  -H "Authorization: Bearer YOUR_KEY"
```

### Orders by recipient phone

`GET /devapi/cheap-data/orders/by-phone/:phone` · FREE

```
curl https://fricopay.com/devapi/cheap-data/orders/by-phone/0241234567 \
  -H "Authorization: Bearer YOUR_KEY"
```

### Your purchase history

`GET /devapi/cheap-data/transactions` · FREE

```
curl https://fricopay.com/devapi/cheap-data/transactions \
  -H "Authorization: Bearer YOUR_KEY"
```

## Order flow

What to expect after you buy.

| Status | Meaning |
| --- | --- |
| `placed` | Your order is accepted and on its way to the customer. |
| `processing` | Your order is received and waiting its turn. It is sent again by itself until it goes through. |
| `success` | The data was delivered. |
| `failed` | The order could not be delivered. Your wallet is refunded automatically. |

- Your wallet is charged when you buy. A failed order is refunded.
- Use the `reference` from the purchase reply to check the status, or set a [webhook](https://fricopay.com/portal#/webhooks) and we tell you when it changes.
- Delivery usually takes a few minutes. Large bundles can take longer.

**Network keys**

| Key | Network |
| --- | --- |
| `YELLO` | MTN data |
| `AT_PREMIUM` | AirtelTigo iShare |
| `AT_BIGTIME` | AirtelTigo BigTime |
| `TELECEL` | Telecel data |

---

# Bills and utilities

Pay TV subscriptions, ECG electricity and Ghana Water bills, and look up SIM owners.

## DSTV / GOtv / Telecel Broadband

### Step 1 — Verify account holder

`service`: `DSTV`, `GOTV`, or `BROADBAND`. Returns `account_name` and `amount_due`.

```
curl "https://fricopay.com/devapi/v1/utility/verify?service=DSTV&account=8226349986" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Step 2 — Pay the bill

```
curl -X POST https://fricopay.com/devapi/v1/utility \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"DSTV","account":"8226349986","amount":50,"user_reference":"u_123"}'
```

## ECG Electricity

### Step 1 — List meters linked to a phone

ECG registers meters against a Ghana mobile number. Returns all meters with current balances.

```
curl "https://fricopay.com/devapi/v1/ecg/meters?phone=233246912184" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Step 2 — Top up a meter

Use the `meter_number` from Step 1.

```
curl -X POST https://fricopay.com/devapi/v1/ecg \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"233246912184","meter":"13334792","amount":20,"user_reference":"u_123"}'
```

## Ghana Water

### Step 1 — Verify water account

Returns `account_name`, `amount_due`, and a `session_id` — required for the payment call.

```
curl "https://fricopay.com/devapi/v1/water/verify?meter=091019010006&phone=233242825109" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Step 2 — Pay water bill

`session_id` must be fresh from the verify call — can't reuse across transactions.

```
curl -X POST https://fricopay.com/devapi/v1/water \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"233242825109","meter":"091019010006","session_id":"FROM_VERIFY_CALL","email":"user@example.com","amount":10,"user_reference":"u_123"}'
```

## SIM Owner Verify

### Look up registered SIM owner name

Returns the legal name the SIM was registered with. Useful for KYC and fraud prevention before sending money or airtime.

```
curl "https://fricopay.com/devapi/v1/msisdn/verify?phone=233246912184" \
  -H "Authorization: Bearer YOUR_KEY"
```

## Status

### Check transaction status

Use only if your callback didn't fire after 5 minutes. `reference` is returned from the buy call.

```
curl https://fricopay.com/devapi/v1/status/REFERENCE \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Virtual numbers

Buy a temporary phone number, wait for the SMS code, and read it from the API.

## Endpoints

### List services

Returns available services for a country with cheapest operator and price in GHS.

```
curl https://fricopay.com/devapi/virtual/services?country=usa \
  -H "Authorization: Bearer YOUR_KEY"
```

### Buy a number

Rents a number and returns the phone. Charges your wallet. Use `operator: "any"` for cheapest available.

```
curl -X POST https://fricopay.com/devapi/virtual/buy \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"usa","service":"whatsapp","operator":"any"}'
```

### Check for SMS

Polls 5SIM for incoming SMS. Returns array of received messages.

```
curl https://fricopay.com/devapi/virtual/order/123456 \
  -H "Authorization: Bearer YOUR_KEY"
```

### Cancel + refund

Cancels the order and refunds the full amount to your wallet. Only allowed before SMS arrives.

```
curl -X POST https://fricopay.com/devapi/virtual/cancel/123456 \
  -H "Authorization: Bearer YOUR_KEY"
```

### Finish (close order)

Closes the order after you've received and verified the SMS. No refund.

```
curl -X POST https://fricopay.com/devapi/virtual/finish/123456 \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# SMS

Send transactional SMS to Ghana numbers with your own sender ID.

**Sender ID activation required**

Before you can send SMS, your sender ID (the name recipients see) must be approved. Send your sender ID to our team on WhatsApp to get it activated.

[Contact us on WhatsApp](https://wa.me/233500109197?text=Hi,%20please%20activate%20my%20SMS%20sender%20ID:%20)

## Endpoints

### Send SMS

Send an SMS. Sender ID max 11 chars. SMS body max 480 chars (3 segments). Set `unicode` to `"1"` for non-Latin characters.

```
curl -X POST https://fricopay.com/devapi/sms/send \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"0241234567","from":"MyApp","sms":"Hello from my app","unicode":"0"}'
```

### List sent messages

Returns your recent SMS sends with cost breakdown.

```
curl https://fricopay.com/devapi/sms/orders \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Social boost

Sell followers, likes and views on TikTok, Instagram, YouTube and more.

## Endpoints

### List services

```
curl https://fricopay.com/devapi/booster/services \
  -H "Authorization: Bearer YOUR_KEY"
```

### Get price quote

```
curl -X POST https://fricopay.com/devapi/booster/quote \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 1234, "quantity": 1000}'
```

### Place an order

```
curl -X POST https://fricopay.com/devapi/booster/order \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 1234,
    "link": "https://tiktok.com/@user/video/123",
    "quantity": 1000
  }'
```

### Check order status

```
curl https://fricopay.com/devapi/booster/order/ORDER_ID \
  -H "Authorization: Bearer YOUR_KEY"
```

### List your orders

```
curl https://fricopay.com/devapi/booster/orders \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Result checkers

Sell WAEC and BECE result checkers and get the serial and PIN back.

## Endpoints

### List products

```
curl https://fricopay.com/devapi/checker/products \
  -H "Authorization: Bearer YOUR_KEY"
```

### Buy a checker

Returns Serial & PIN instantly when supplier has stock. If queued, response includes `queued: true` — check status with the order endpoint.

```
curl -X POST https://fricopay.com/devapi/checker/buy \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkerType": "BECE",
    "phoneNumber": "0241234567"
  }'
```

### Check order status

```
curl https://fricopay.com/devapi/checker/order/REFERENCE \
  -H "Authorization: Bearer YOUR_KEY"
```

### List your orders

```
curl https://fricopay.com/devapi/checker/orders \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# AFA registration

Register customers for MTN AFA straight from your app.

## Endpoints

### Submit registration

Charges GHS 11 from your wallet. Submits to the AFA network and returns immediately — check status separately if needed.

Response:

```
curl -X POST https://fricopay.com/devapi/afa/register \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ama Mensah",
    "phone_number": "0240000000",
    "id_type": "Ghana Card",
    "id_number": "GHA-000000000-0",
    "dob": "1995-06-15",
    "location": "Accra",
    "occupation": "Trader",
    "external_order_id": "SHOP-10001"
  }'
```

**Response**

```
{
  "ok": true,
  "tx_id": "XNzAGOboUPPxeuKljGoJ",
  "afa_id": 2980,
  "status": "submitted",
  "total_paid_ghs": 11,
  "currency": "GHS"
}
```

### Check registration status

Use the `tx_id` returned when you submitted the registration.

```
curl https://fricopay.com/devapi/afa/registrations/TX_ID \
  -H "Authorization: Bearer YOUR_KEY"
```

### List your registrations

Returns your last 50 AFA registrations, newest first.

```
curl https://fricopay.com/devapi/afa/registrations \
  -H "Authorization: Bearer YOUR_KEY"
```

---

# Football data

Live scores, results, fixtures and predictions for matches worldwide.

**Pricing**

**7 days free · then GHS 100/month**

After trial expires, GHS 100 is auto-debited from your Fricopay wallet monthly. If your balance is low, we retry daily until sufficient.

## Endpoints

### Check subscription status

Returns current subscription state: `not_started`, `trial`, `active`, or `pending_renewal` (when wallet is low). Includes trial expiry / next charge date.

```
curl https://fricopay.com/devapi/football/status \
  -H "Authorization: Bearer YOUR_KEY"
```

### Get all matches

All matches with scores and status. Supports `?when=today` (default), `yesterday`, or `tomorrow`. Each match returns home, away, time, score, status (scheduled/live/finished), plus `homeLogo` and `awayLogo` (team crest URLs served from our domain).

```
curl "https://fricopay.com/devapi/football/livescores?when=today" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Get a specific match result

Look up the score for any specific match by team names. Required: `home`, `away`. Optional: `when` (today / yesterday / tomorrow). Returns teams, score, and status (FT, HT, live, not_started).

```
curl "https://fricopay.com/devapi/football/match?home=Real+Madrid&away=Oviedo&when=today" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Get full match detail NEW

Rich detail for a single match by team names. Required: `home`, `away`. Optional: `when` (today / yesterday / tomorrow). Returns team names with crest logos, score, status, a full **events timeline** (goals, cards, substitutions with player & minute), **bookmaker odds** (1 / X / 2 across multiple bookmakers), the predicted outcome, and a match analysis. Cached ~3 min. Matches are findable while in the today / yesterday / tomorrow windows - use the matching `when` value (a finished match moves from `today` to `yesterday`).

```
curl "https://fricopay.com/devapi/football/match-detail?home=Castellon&away=Almeria" \
  -H "Authorization: Bearer YOUR_KEY"
```

### Team logos

Team crest images are served directly from our domain (no auth required, safe to use in `<img>` tags). The `homeLogo`/`awayLogo` fields in `livescores` and `match-detail` already contain ready-to-use URLs. If a crest is unavailable, a clean placeholder with the team initials is returned automatically.

### Get predictions and betting tips

Correct-score predictions plus betting tips for each match. Each entry includes home, away, kickoff time, league, predicted correct_score (e.g. `2:0`), and a derived tip (e.g. , ). Supports `?when=today/yesterday/tomorrow`.

```
curl "https://fricopay.com/devapi/football/predictions?when=today" \
  -H "Authorization: Bearer YOUR_KEY"
```

## Sample responses

**Match detail example**

```
{
  "ok": true,
  "teams": "Castellón vs Almeria",
  "homeTeam": { "name": "Castellón", "logo": "https://fricopay.com/football/logo/castellón.png" },
  "awayTeam": { "name": "Almeria", "logo": "https://fricopay.com/football/logo/almeria.png" },
  "score": "1 - 1",
  "status": "FT",
  "events": [
    { "minute": "5'", "type": "yellow_card", "player": "J. Morcillo", "side": "away" },
    { "minute": "44'", "type": "goal", "player": "F. Brignani", "side": "home" }
  ],
  "odds": [
    { "bookmaker": "Megapari", "home": "1.81", "draw": "3.78", "away": "4.45" }
  ],
  "prediction": "Castellón",
  "analysis": "Teams Castellón and Almeria will try to find out who is the best..."
}
```

**Predictions example**

```
{
  "ok": true,
  "when": "today",
  "count": 119,
  "matches": [
    {
      "kickoff": "16:00",
      "home": "Admira Wacker",
      "away": "Floridsdorfer AC",
      "correct_score": "1:0",
      "tip": "Under 4.5",
      "league": "Austria 2. Liga"
    }
  ]
}
```

---

# Bet code converter

Convert a bet code from one bookie to another.
GHS 1.50 per conversionGHS 1.50 per conversionLookup is FREELookup is FREE10 free conversions · 7-day trial10 free conversions · 7-day trial- Auto-refund on conversion failure
- 17 bookies supported (SportyBet, 1xBet, Betika, Odibet, MSport, Betpawa, 22bet & more)
- Same provider used by Fricopay's consumer feature

## Endpoints

### List supported bookies

`GET /devapi/bet-converter/bookies` · FREE

```
curl https://fricopay.com/devapi/bet-converter/bookies \
  -H "Authorization: Bearer YOUR_KEY"
```

### Lookup & preview a bet code

`POST /devapi/bet-converter/lookup` · FREE

```
curl -X POST https://fricopay.com/devapi/bet-converter/lookup \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originBookie": "sportybet:gh",
    "code": "8CJFR6"
  }'
```

### Convert bet code

`POST /devapi/bet-converter/convert` · GHS 1.50 per call

```
curl -X POST https://fricopay.com/devapi/bet-converter/convert \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originBookie": "sportybet:gh",
    "destBookie": "1xbet:gh",
    "code": "8CJFR6"
  }'
```

### List your conversion history

`GET /devapi/bet-converter/history` · FREE

```
curl https://fricopay.com/devapi/bet-converter/history \
  -H "Authorization: Bearer YOUR_KEY"
```

**Sample success response (convert)**

```
{
  "ok": true,
  "destinationCode": "FCA88",
  "originOdds": 8.78,
  "odds": 9.01,
  "noOfEntries": 2,
  "charged": 1.50,
  "currency": "GHS"
}
```