Partner Integration Guide

Bitrefill sells gift cards, phone top-ups and eSIMs for crypto, cards and account balance. Our MCP server lets an AI agent do the whole job: find a product, check the price, buy it and read the result. This guide explains how to connect your agent or MCP client, how guest checkout works when the buyer has no Bitrefill account, how affiliate attribution pays you, and how to test without spending real money.

It is written for developers at partner companies. You need to know what MCP (Model Context Protocol) is and how HTTP and OAuth work. Everything else is explained here. If you only want to connect a desktop client to your own account, the eCommerce MCP Server page and the Setup Guides are the shorter read.

At a glance

Quick start

📘

In short

Point an MCP client at https://api.bitrefill.com/mcp, log in when the client asks, and call search-products. Add ?ref=<code> to the URL if you have an affiliate code.

Connect a client

Most MCP clients only need the URL. Claude, ChatGPT, Cursor and Claude Code discover our OAuth server automatically and open the Bitrefill login and consent screen in a browser.

claude mcp add --transport http bitrefill "https://api.bitrefill.com/mcp?ref=YOURCODE"

If your product has no browser, or your users have no Bitrefill account, use a client-credentials token instead. If your own company is the buyer, an API key is the simplest option. Both are described in The three modes in detail.

First request with curl

curl -s https://api.bitrefill.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Accept header must contain both application/json and text/event-stream. Without both you get HTTP 400.

The purchase flow

Every purchase follows the same four tool calls.

A guest purchase of a 10 USD Amazon gift card paid in Bitcoin:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "buy-products",
    "arguments": {
      "cart_items": [{ "product_id": "amazon_com-usa", "package_value": "10" }],
      "payment_method": "bitcoin",
      "email": "[email protected]"
    }
  }
}

The email argument only exists for guests. Logged-in buyers get the receipt on their account email.

How the server behaves

📘

In short

One authenticated HTTP POST per JSON-RPC message, no sessions, compact text responses, 30 requests per minute.

Stateless transport. Each POST is handled on its own. There is no Mcp-Session-Id header. GET /mcp and DELETE /mcp answer HTTP 405, because there are no server-initiated streams and no sessions to close. JSON-RPC notifications receive HTTP 202 with an empty body.

Every request is authenticated. The bearer token decides who the buyer is and which tools appear in tools/list. Do not cache the tool list across different tokens.

Response format. Read tools return TOON (Token-Oriented Object Notation), a compact text format built for language models. It reads like indented key-value lines and uses about 40 percent fewer tokens than JSON. buy-products returns plain JSON so payment details can be parsed exactly. Errors are always JSON with isError: true (see Errors).

Rate limit. 30 requests per minute per bearer token, or per IP address when there is no token. Over the limit you get HTTP 429 with the body below. Back off for the rest of the minute.

{ "status": "rate_limit_reached", "message": "You have reached your request quota, if you need a higher quota please contact us" }

Country. The server reads the country from the IP address of the caller. When an AI vendor proxies the traffic, that is the vendor's IP. The country is used for fiat payment rules on some product categories. Crypto payments are not affected.

Attribution data. Every invoice created through MCP records the channel, your OAuth client and, when present, your affiliate id. That is what Bitrefill uses to report on your integration.

Authentication

📘

In short

Three ways in. OAuth login gives you the user's own account. OAuth client credentials give you a guest. An API key gives you your own account.

OAuth discovery

Our authorization server follows the MCP authorization specification (OAuth 2.1). Start from the protected resource metadata and let it lead you to the rest:

GET https://api.bitrefill.com/.well-known/oauth-protected-resource

It names the authorization server, https://api.bitrefill.com/oauth/mcp. The authorization server metadata (RFC 8414) lists the endpoints. Today they are:

Read them from the metadata instead of hard-coding them.

Facts that matter when you build your own client:

• Scope. Request mcp.
• Resource indicator. Send resource=https://api.bitrefill.com/mcp (RFC 8707) on authorize and token requests.
• PKCE with S256 is mandatory.
• Client identity. Two options. Client ID Metadata Documents (CIMD), where your client_id is an HTTPS URL to a JSON document you host, is the recommended one and the one Claude uses. Dynamic Client Registration (RFC 7591) at the register endpoint also works. A CIMD document must be public, served over HTTPS on a real hostname, and smaller than 10 KB. token_endpoint_auth_method is none for CIMD clients, and none or client_secret_post for registered clients.
• Redirect URIs must match exactly. Loopback URIs (http://127.0.0.1:<any port>/callback) are accepted for native apps.
• Token lifetime. Access tokens live 6 hours, refresh tokens 7 days. A refresh token is single use and the refresh response contains a new one. Revoking a refresh token also invalidates the access tokens from the same grant.
• Rate limits. The OAuth endpoints are rate limited per IP address. If many of your users share one egress IP, register your client once and reuse it, and spread token refreshes over time.

The three modes in detail

curl -s https://api.bitrefill.com/oauth/mcp/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d scope=mcp \
  -d resource=https://api.bitrefill.com/mcp

Authorization: Bearer <api key>

Authentication failures

A missing, invalid, expired or revoked credential gets HTTP 401 with a WWW-Authenticate: Bearer error="invalid_token" header. So does a disabled account. Compliant clients start the OAuth flow again when they see 401.

Guest accounts

📘

In short

A guest is a client-credentials token. Guests see 7 tools, must pass email to buy-products, pay with crypto or a payment link, and read their invoice with the invoice_access_token they received when buying. Keep that token safe.

What a guest is

A guest has no Bitrefill account. Bitrefill cannot tell one guest from another between requests. That has two consequences you must design for:

• A guest has no stable identity. The checkout email and the invoice access token are the only handles on a purchase. Store them on your side if you want to show the purchase again later.
• Ownership of an invoice is proven by its access token, not by who is calling. Anyone with invoice_id and invoice_access_token can read the invoice, including the codes. Store both like a password.

Build on email plus access token and do not assume anything about how guests are represented internally.

What guests can and cannot do

Login-only tools are not listed in tools/list for a guest token, so a well-behaved agent never sees them. Calling one anyway returns PERMISSION_DENIED. Asking for a balance payment as a guest returns INVALID_INPUT with the message "Paying with account balance requires you to be logged in".

A guest purchase, step by step

1. Search and check the product. get-product-details returns the accepted payment_methods for that product in three groups: address_based (crypto with an on-chain address), link_only (cards, Apple Pay, Google Pay, iDEAL, EPS, Przelewy24, Bancontact, Binance Pay, Kraken Pay) and balance.
2. Buy. Call buy-products with cart_items, payment_method and email. Fiat methods also need billing_address with at least country. fiat_card also needs city, postal_code and address_line1.
3. Store the response. The result is a JSON object with two keys. response holds the invoice: invoice_id, invoice_access_token, expiration_minutes, cart_items, and for crypto a payment_info block (address and amount), a payment_link to the web checkout and an x402_payment_url (see Paying an MCP invoice with x402). For link-only methods payment_link is the only way to pay. agent_instructions tells the agent what to do next in plain language.
4. Let the user pay. Crypto: send the exact amount to the address before the invoice expires. Cards and other links: open payment_link in a browser. The link contains the access token, so treat it as private.
5. Poll. Call get-invoice-by-id with invoice_id and invoice_access_token until invoice_status is complete. Poll every 10 to 30 seconds, not faster. Statuses move through unpaid, payment_detected, payment_confirmed and complete. blocked means a compliance review that the agent cannot resolve.
6. Deliver. Each order in the invoice reports status: delivered and redemption_info with the code, plus an access_link to its page on bitrefill.com. eSIM orders add esim_install_link. Do not rely on email for delivery. Read the codes from the tool response or send the user to the link.

To change the payment method, call buy-products again. The unpaid invoice simply expires.

Limits and checks that apply to guests

• Purchase limits apply to guest purchases. Exceeding them returns purchase_limit_reached.
• Fraud and compliance checks run on every invoice. A blocked invoice reports invoice_status: blocked. The errors verification_required and access_denied mean the buyer has to continue on the website. Do not retry.
• Product availability can differ between guests and logged-in users. Balance top-up products refuse guests with user_not_registered.

From guest to account

Guests often become customers. Two paths exist:

• Log in later through OAuth. New purchases land on the user's account. Guest invoices stay reachable with their id and access token, but they do not appear in list-invoices.
• Create an account from the receipt. The checkout and receipt pages on bitrefill.com (reached through payment_link and the order access_link) offer to create an account. Within 30 days of completion, the purchase and its cashback can be claimed by that account.

If your product cannot open a browser at all, talk to your Bitrefill contact about login options before you build a workaround.

Affiliate attribution

📘

In short

Get an affiliate code from Bitrefill, append ?ref=<code> to the server URL, and every purchase made through that connection is attributed to you. Commission accrues in BTC per delivered order and is paid out from your Bitrefill account.

Getting a code

Affiliate status is a Bitrefill account type. Apply at bitrefill.com/integrate or ask your Bitrefill contact. After a short business verification, your account becomes an affiliate account and receives an affiliate code, shown in your account.

Passing the code

MCP. Configure the server URL as:

https://api.bitrefill.com/mcp?ref=YOURCODE

The code is read from the URL on every request, with every authentication mode (OAuth login, client credentials, API key). It must therefore be part of the URL your client stores, not something you send once.

x402 REST API. Send the header X-Bitrefill-Affiliate-Id: YOURCODE on POST /x402/invoice/create (see The x402 REST API).

Rules:

• Codes are 6 to 16 letters and digits. Anything else is ignored.
• Attribution fails open. An unknown or malformed code never fails the purchase. It is dropped silently and the purchase goes through without attribution. Test your attribution explicitly (see Test plan).
• A coupon_code is a different thing. Coupons change the price for the buyer. Affiliate codes change who receives commission. Both can be present on one purchase.

What is recorded and how commission works

• The invoice and each of its orders store your affiliate id.
• Commission is calculated per order at the rate agreed with Bitrefill, which can differ per product. Some products are excluded from the program and earn no commission.
• Commission counts once the order is paid and delivered. Refunded or failed orders earn nothing.
• Attribution does not depend on who pays or how: guest or logged-in buyer, crypto, card or balance.
• The commission report and payouts (withdrawals) are available from your Bitrefill affiliate account.

Testing

📘

In short

Read tools need no setup. For purchases, ask us to enable test products on your account: their invoices confirm automatically and nothing is charged. Test guest flows on staging or with one small real purchase. Verify affiliate attribution with a separate, non-affiliate account.

Environments

Discovery tools (search-products, get-product-details, help articles) are free to call on production with any token, including a guest token. Start there.

Test products

Bitrefill has a family of test products from a test provider. Their slugs end in -syldavia. Examples:

All of them belong to the test country KN, so search-products with country: "KN" lists them.

Two rules make them useful:

1. They are hidden until Bitrefill enables them for your account. Ask your Bitrefill contact to enable test products on the account behind your API key or OAuth login. Until then, get-product-details and buy-products answer product_not_found, even if search listed the product.
2. Invoices made only of test products confirm automatically when paid with a crypto or link-only method. No payment is needed and nothing is charged. Delivery then runs normally, so you can test the loop all the way to redemption_info. Test products that exist to simulate failures, such as failcorp-syldavia, are never confirmed automatically. Your Bitrefill contact can tell you how to exercise them.

🚧

Do not pay test products from balance

A balance payment debits your real balance, also for a test product. Use a crypto or link-only method, which is confirmed automatically for test products.

Test products are enabled per account, so a guest token cannot use them. To test a guest flow end to end, use staging, or make one small real purchase on production (for example the cheapest denomination of a gift card you can use yourself).

Interactive testing

claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp

Test plan

When something fails

Send us the invoice_id, the tool name, the UTC timestamp, your OAuth client_id or API key name (never the key itself) and the full error object. That is enough to find the request in our logs.

Errors

📘

In short

Tool errors come back as isError: true with a JSON body { error, code, details }. Retry only SERVICE_UNAVAILABLE. Never retry PAYMENT_UNCERTAIN.

{
  "error": "Invalid denomination '7' for product 'amazon_com-usa'. Available denominations: 5, 10, 25, 50, 100",
  "code": "INVALID_INPUT",
  "details": { "status": "invalid_package" }
}

❗️

Never retry PAYMENT_UNCERTAIN

A second buy-products call after PAYMENT_UNCERTAIN can charge the balance twice. Poll get-invoice-by-id instead and let the invoice settle.

The details.status values you will meet most often: product_not_found, product_not_available, invalid_package, number_missing, payment_method_not_accepted, invalid_payment_method, purchase_limit_reached, balance_too_low, bill_payment_id_missing, coupon_invalid, verification_required, access_denied, user_not_registered, missing_fiat_payment_info, invalid_billing_country.

HTTP-level errors are separate: 400 for a bad Accept header, 401 for authentication, 405 for GET or DELETE, 429 for the rate limit.

Tool reference

Payment methods accepted by buy-products:

Fiat methods are charged in the method's standard currency, for example USD for cards. The tool description lists the currency per method. A cart holds up to 15 items. Add the same product twice for two units. Any item can be sent as a gift by email with cart_items[].gift (recipient_name, recipient_email, sender_name, optional message, send_date between 12 hours and 6 months ahead, and theme).

Paying an MCP invoice with x402

buy-products returns x402_payment_url (https://api.bitrefill.com/x402/invoice/pay) for crypto invoices. A wallet that speaks x402 can settle a USDC invoice with two HTTP calls instead of a manual transfer to the address:

1. POST /x402/invoice/pay with the body { "invoice_id": "<id>" }. The answer is HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON describing amount, asset and networks).
2. Sign the payment with your x402 client and repeat the POST with a PAYMENT-SIGNATURE header. HTTP 200 means the payment is accepted and being settled. Poll get-invoice-by-id, or GET /x402/invoice/status?invoice_id=<id>, for delivery.

Conditions: the invoice was created with a USDC method (usdc_base, usdc_arbitrum, usdc_polygon or usdc_solana) and is younger than 15 minutes, which is the price lock. The @x402/core and @x402/mcp npm packages implement the client side.

The x402 REST API

For agents that hold a wallet but no Bitrefill account, Bitrefill also exposes a wallet-native REST API on https://api.bitrefill.com. Identity is the wallet. Calls are paid per request in USDC (0.001 to 0.002 USD), or made free by signing in with the wallet (Sign In With X). It covers the same catalog as MCP with fewer options: crypto only, no gifts, no coupons.

Glossary