Crypto Payments

Bitrefill supports payments in various cryptocurrencies. This guide explains how to use them.

Supported Cryptocurrencies

Method	Code	Network
Bitcoin	`bitcoin`	On-chain
Lightning	`lightning`	Lightning Network
Ethereum	`ethereum`	Mainnet
Ethereum (Base)	`eth_base`	Base L2
Ethereum (Arbitrum)	`eth_arbitrum`	Arbitrum L2
USDC (ERC-20)	`usdc_erc20`	Ethereum
USDC (Polygon)	`usdc_polygon`	Polygon
USDC (Solana)	`usdc_solana`	Solana
USDC (Base)	`usdc_base`	Base L2
USDC (Arbitrum)	`usdc_arbitrum`	Arbitrum L2
USDT (TRC-20)	`usdt_trc20`	Tron
USDT (ERC-20)	`usdt_erc20`	Ethereum
USDT (Polygon)	`usdt_polygon`	Polygon
Litecoin	`litecoin`	On-chain
Dogecoin	`dogecoin`	On-chain
Dash	`dash`	On-chain
Solana	`solana`	Solana

Creating a Crypto Invoice

Specify the payment method and include a refund address:

const response = await fetch(`${BASE_URL}/invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    products: [{ product_id: 'amazon-us', value: 50 }],
    payment_method: 'bitcoin',
    refund_address: 'bc1q...'
  })
});

const { data: invoice } = await response.json();

console.log(`Send ${invoice.payment.price} ${invoice.payment.currency}`);
console.log(`To: ${invoice.payment.address}`);

Payment Details

The response includes everything needed for payment:

Field	Description
`payment.address`	Where to send funds
`payment.price`	Exact amount to send
`payment.currency`	Currency code

Send the exact amount to the exact address. Underpayment or wrong address may result in lost funds.

Payment Flow

sequenceDiagram
    participant Client
    participant Bitrefill
    participant Blockchain
    
    Client->>Bitrefill: POST /invoices (crypto)
    Bitrefill-->>Client: Invoice with payment address
    Client->>Blockchain: Send payment
    Blockchain->>Bitrefill: Payment detected
    Bitrefill->>Bitrefill: Wait for confirmations
    Bitrefill->>Client: Webhook (status: complete)
    Client->>Bitrefill: GET /orders/{id}
    Bitrefill-->>Client: Order with redemption info

Checking Payment Status

Poll the invoice or use webhooks. See Core Concepts for status definitions.

Lightning Payments

Lightning is faster and confirms instantly:

const response = await fetch(`${BASE_URL}/invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    products: [{ product_id: 'amazon-us', value: 50 }],
    payment_method: 'lightning'
  })
});

const { data: invoice } = await response.json();
// invoice.payment.address contains the BOLT11 invoice

Complete Example

async function purchaseWithCrypto(products, paymentMethod, refundAddress) {
  const response = await fetch(`${BASE_URL}/invoices`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      products,
      payment_method: paymentMethod,
      refund_address: refundAddress,
      webhook_url: 'https://your-server.com/webhook'
    })
  });
  
  const { data: invoice } = await response.json();
  
  return {
    invoiceId: invoice.id,
    address: invoice.payment.address,
    amount: invoice.payment.price,
    currency: invoice.payment.currency
  };
}

// Usage
const payment = await purchaseWithCrypto(
  [{ product_id: 'amazon-us', value: 50 }],
  'bitcoin',
  'bc1q...'
);

console.log(`Send ${payment.amount} ${payment.currency} to ${payment.address}`);

Confirmation Times

Method	Typical Time
Lightning	Instant
Bitcoin	10-60 minutes
Ethereum/L2	1-5 minutes
Stablecoins	Varies by network