Bitrefill Payments API

openapi: 3.2.0
info:
  title: Bitrefill x402 Payments 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: Payments
  description: Invoice payment and status.
paths:
  /x402/invoice/pay:
    post:
      operationId: payInvoice
      summary: Pay a Bitrefill invoice with USDC (x402)
      description: Settle a price-locked invoice via x402 USDC on Base, Arbitrum, Polygon, or Solana. Create the invoice first with POST /x402/invoice/create.
      tags:
      - Payments
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.01'
          max: '1000'
        protocols:
        - x402: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invoice_id:
                  type: string
                  description: Invoice ID from POST /x402/invoice/create. Expired or already-settled IDs return 404 or 409.
              required:
              - invoice_id
            example:
              invoice_id: 63ceec2e-39ce-47e8-ab20-c54e08c595b6
      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
      responses:
        '200':
          description: Payment accepted and settled — returns { accepted, message, next_step }; poll invoice/status for the fulfillment outcome and redemption codes.
        '400':
          description: Invalid request — unsupported payment method or malformed payment payload.
        '402':
          description: Payment Required — per-invoice x402 requirements in PAYMENT-REQUIRED.
        '404':
          description: Invoice not found.
        '409':
          description: Invoice not payable (wrong status); poll invoice/status instead of retrying payment.
        '500':
          description: Unexpected server error.
  /x402/invoice/status:
    get:
      operationId: getInvoiceStatus
      summary: Invoice status and redemption codes
      description: 'Poll fulfillment status. Without SIWX: status only (micro-fee). With SIGN-IN-WITH-X or X-Access-Token from the paying wallet: includes redemption_info when complete.'
      tags:
      - Payments
      parameters:
      - name: invoice_id
        in: query
        required: true
        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
      - 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
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        protocols:
        - x402: {}
      responses:
        '200':
          description: status, delivery_status, optional redemption_info (when SIWX-proven), optional error_code for partial fulfillment.
        '400':
          description: Missing invoice_id.
        '402':
          description: Payment Required — x402 payment requirements in the PAYMENT-REQUIRED response header (and mirrored in the JSON body).
        '403':
          description: SIWX wallet does not match invoice payer.
        '404':
          description: Invoice not found.
        '500':
          description: Unexpected server error.