Phone Top-ups

Phone top-ups add airtime or data to mobile phones. Unlike gift cards, they don't return a code — the balance is added directly to the phone.

How Top-ups Work

User provides their phone number
You create an invoice with the phone number
Payment is processed
Balance is added to the phone automatically

No redemption code is needed — the top-up happens in the background.

Finding Operators

By Country

const response = await fetch(
  `${BASE_URL}/products?country=US&type=phone_refill`,
  { headers }
);
const { data: operators } = await response.json();

By Phone Number

Look up operators for a specific phone number:

const response = await fetch(
  `${BASE_URL}/check_phone_number?phone_number=%2B15551234567`,
  { headers }
);
const { data } = await response.json();

console.log(`Operators for ${data.phone_number}:`);
data.operators.forEach(op => console.log(`  ${op.id}: ${op.name}`));

Purchasing a Top-up

Include the phone_number in your invoice request:

const response = await fetch(`${BASE_URL}/invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    products: [{
      product_id: 'at-t-usa',
      package_id: 'at-t-usa<&>25',
      phone_number: '+15551234567',
      quantity: 1
    }],
    payment_method: 'balance',
    auto_pay: true
  })
});

Phone Number Format

Use E.164 format (international format with +):

Format	Example
US	+15551234567
UK	+447911123456
Germany	+4915123456789

Order Response

Phone top-ups don't return redemption codes:

{
  "data": {
    "id": "ord_xyz789",
    "status": "delivered",
    "product": {
      "id": "at-t-usa",
      "name": "AT&T",
      "value": 25
    },
    "phone_number": "+15551234567"
  }
}

When status is delivered, the top-up was successful.

Error Handling

Common top-up errors:

Error	Cause	Solution
`invalid_phone_number`	Wrong format or invalid number	Verify phone number
`unsupported_operator`	Number not supported	Check with `/check_phone_number`
`delivery_failed`	Provider error	Automatic refund