Bitrefill Checkout API

openapi: 3.2.0
info:
  title: Bitrefill x402 Checkout API
  description: Buy gift cards, eSIMs, mobile top-ups and prepaid cards with USDC via x402. 10,000+ brands across 180+ countries. No API keys or Bitrefill account required — wallet payment and optional SIWX sign-in only.
  version: 1.0.0
  contact:
    name: Bitrefill
    email: miguelmorales@bitrefill.com
  x-guidance: 'Agent checkout flow: search (gift-cards/esims/topups) → GET /x402/products/detail?slug=… → POST /x402/invoice/create with items → POST /x402/invoice/pay with invoice_id → GET /x402/invoice/status?invoice_id=… (SIWX with the paying wallet to retrieve codes). Pay each micro-fee via x402 (PAYMENT-SIGNATURE header) or mint a session at POST /x402/connect (SIGN-IN-WITH-X) and send X-Access-Token on later calls. Full guide: bitrefill.com/agents/SKILL.md'
servers:
- url: https://api.bitrefill.com
tags:
- name: Checkout
  description: Product details and invoice creation.
paths:
  /x402/products/detail:
    get:
      operationId: getProductDetails
      summary: Product details and purchasable packages
      description: Fetch packages, recipient requirements, and a suggested line item for invoice creation.
      tags:
      - Checkout
      parameters:
      - name: slug
        in: query
        required: true
        description: Product slug from search results (e.g. amazon-us).
        schema:
          type: string
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: x402 payment payload (base64). Required to settle a 402 challenge. v1 clients may send x-payment instead.
        schema:
          type: string
      - name: X-Access-Token
        in: header
        required: false
        description: Session JWT from POST /x402/connect. Bypasses micro-fees and SIWX re-signing until expiry.
        schema:
          type: string
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
        - x402: {}
      responses:
        '200':
          description: Product metadata with next_step to POST /x402/invoice/create.
        '400':
          description: Missing slug.
        '402':
          description: Payment Required — x402 payment requirements in the PAYMENT-REQUIRED response header (and mirrored in the JSON body).
        '404':
          description: Product not found (may include suggestions).
        '500':
          description: Unexpected server error.
  /x402/invoice/create:
    post:
      operationId: createInvoice
      summary: Create a price-locked invoice
      description: Quote cart items and lock the USDC price. Requires a resolved paying wallet (from the create micro-fee payer, SIWX, or X-Access-Token).
      tags:
      - Checkout
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: x402 payment payload (base64). Required to settle a 402 challenge. v1 clients may send x-payment instead.
        schema:
          type: string
      - name: X-Access-Token
        in: header
        required: false
        description: Session JWT from POST /x402/connect. Bypasses micro-fees and SIWX re-signing until expiry.
        schema:
          type: string
      - name: SIGN-IN-WITH-X
        in: header
        required: false
        description: Base64 JSON of decomposed SIWE fields (domain, address, uri, version, chainId, type, nonce, issuedAt, signature). Required on SIWX-only routes when no X-Access-Token is present.
        schema:
          type: string
      - name: X-Bitrefill-Affiliate-Id
        in: header
        required: false
        description: Public affiliate code (6-16 alphanumeric characters, case-sensitive) to credit for this purchase — the same code MCP accepts as ?ref=, never a user id. An unknown or malformed code is ignored rather than rejected.
        schema:
          type: string
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
        - x402: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 15
                  items:
                    type: object
                    properties:
                      product_id:
                        type: string
                        description: Product slug.
                      package_value:
                        type: string
                        description: Package denomination from product detail.
                      refill_input:
                        type: string
                        maxLength: 100
                        description: Recipient (phone, email, etc.) when the product requires it.
                    required:
                    - product_id
                    - package_value
              required:
              - items
            example:
              items:
              - product_id: amazon-us
                package_value: '50'
      responses:
        '200':
          description: invoice_id, price_usdc, price_usd, networks, expires_in_minutes, and next_step to POST /x402/invoice/pay.
        '400':
          description: MISSING_FIELD (items) or MISSING_IDENTITY (no paying wallet).
        '402':
          description: Payment Required — x402 payment requirements in the PAYMENT-REQUIRED response header (and mirrored in the JSON body).
        '500':
          description: Unexpected server error.