Cryptorefills developer API reference: Stablecoin checkout integration

1

Authentication

Every API request requires these headers. After creating a Cryptorefills account, you can find your Partner ID on your account information page.

Open your account information page

bash

# Required headers for every API request
-H 'X-Cr-Application: YOUR_PARTNER_ID'
-H 'X-Cr-Version: YOUR_APP_VERSION'
-H 'X-Forwarded-For: END_USER_IP'
-H 'User-Agent: END_USER_AGENT'
-H 'Content-Type: application/json'

2

Payment methods

GET/v3/payment_vias

Fetch all supported coins and blockchain networks. Returns USDC, USDT on Solana, Ethereum, Base, Arbitrum, Polygon, and more.

bash

curl -X GET 'https://api.cryptorefills.com/v3/payment_vias' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

Recommended: USDC on Solana offers the lowest fees and fastest settlement.

3

Brand catalog

GET/v2/brands?country_code={countryCode}

(Optional) List all available brands for a country. Great for building brand directory or search features.

bash

curl -X GET 'https://api.cryptorefills.com/v2/brands?country_code=US' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

Logo URL variants

Each brand returns a logo_url (default) and a logo_base_url. Append a suffix to logo_base_url to fetch optimized sizes and formats.

.webpRecommended

{logo_base_url}.webp
{logo_base_url}_500x318.webp
{logo_base_url}_300x190.webp

.jpg

{logo_base_url}.jpg
{logo_base_url}_500x318.jpg
{logo_base_url}_300x190.jpg

Example: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp

Supported country codes

233GET https://cryptorefills.com/api/available-countries

4

Homepage feed

GET/v2/homepage?country_code={countryCode}

(Optional) Fetch a curated homepage feed for a country. Useful for displaying trending or featured gift cards.

bash

curl -X GET 'https://api.cryptorefills.com/v2/homepage?country_code=US' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

5

Browse products

GET/v5/products/country/{countryCode}

List all available gift cards for a brand and country. Supports fixed denominations and custom amounts (ranges).

bash

curl -X GET 'https://api.cryptorefills.com/v5/products/country/US?family_name=airbnb&coin=USDC&lang=en' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

6

Get crypto price

GET/v4/products/price

Convert any gift card value to stablecoin amount. Use this to show users the exact crypto amount before they confirm purchase.

bash

curl -X GET 'https://api.cryptorefills.com/v4/products/price?brand_name=Airbnb&country_code=US&face_value=100&coin=USDC' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

7

Validate order

POST/v5/orders/validations

(Recommended) Check for issues before creating the order. Use the real end-user email in email/beneficiary_account, since Cryptorefills delivers to that recipient.

bash

curl -X POST 'https://api.cryptorefills.com/v5/orders/validations' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT' \
  -d '{
    "email": "END_USER_EMAIL",
    "payment": {
      "type": "via",
      "payment_via": "USER_WALLET",
      "coin": "USDC"
    },
    "deliveries": [
      {
        "beneficiary_account": "END_USER_EMAIL",
        "brand_name": "Airbnb",
        "country_code": "US",
        "denomination": "100 USD"
      }
    ],
    "lang": "en"
  }'

Possible errors

The response returns a problems array. Each entry has the shape { problem, moreDetails? }, and multiple problems can be returned at once. Top-level HTTP errors (suspensions) come back as { status, detail, moreDetails? } instead.

Order amount & limits

AMOUNT_LESS_THEN_MINIMUM_ALLOWEDOrder total is below the minimum coin amount allowed.
MAXIMUM_AMOUNT_PER_ORDER_EXCEEDEDOrder total exceeds the per-order maximum.
DAILY_SPENDING_LIMIT_EXCEEDEDUser has hit the daily spending limit for their tier.
MONTHLY_SPENDING_LIMIT_EXCEEDEDUser has hit the monthly spending limit for their tier.
PRODUCT_COUNT_EXCEEDEDCart contains more products than the per-order maximum.
MULTIPLE_LIMITED_PRODUCT_SAME_ORDEROrder contains more than one rate-limited product.

Product availability

NOT_AVAILABLE_PRODUCTProduct is no longer in the catalogue.
OUT_OF_STOCKProduct is currently out of stock.
NOT_ACTIVEProduct is inactive or paused.
INVALID_BENEFICIARY_ACCOUNTBeneficiary account is invalid — e.g. phone number for a mobile topup or email for a gift card.

Payment method & network

NOT_ALLOWED_PAYMENT_VIASelected payment_via is not allowed for this order. moreDetails lists allowed kinds.
UNSUPPORTED_PROTOCOL_COIN_COMBINATIONChosen protocol + coin pair is not supported. moreDetails lists supported combinations.

Authentication

LOGIN_REQUIREDOne or more products require a signed-in user.
COUPON_REQUIRES_LOGINThe coupon can only be redeemed by a signed-in user.

Coupon codes

COUPON_NOT_FOUNDCoupon code does not exist.
COUPON_NOT_ACTIVECoupon is not yet active.
COUPON_ALREADY_SPENTCoupon has already been redeemed by this user.
COUPON_MAX_USAGE_REACHEDCoupon has reached its overall usage cap.
COUPON_EXPIREDCoupon is past its validity date.
COUPON_BELOW_MIN_AMOUNTOrder total is below the coupon’s minimum amount.
COUPON_NOT_VALID_FOR_USERCoupon is not valid for this user.
COUPON_NOT_VALID_FOR_CATEGORYCoupon does not apply to the selected product categories.
COUPON_NOT_VALID_FOR_KINDCoupon does not apply to the selected product kind.
COUPON_NOT_VALID_FOR_BRANDCoupon does not apply to the selected brands.
COUPON_NOT_VALID_FOR_COUNTRYCoupon is not valid in the order country.
COUPON_NOT_VALID_FOR_STORECoupon is not valid for the requested store or region.

Compliance & identity verification

KYC_MISSINGOne or more products require a verified account, or the user has exceeded the spending limit for unverified accounts. Direct the user to their Cryptorefills account to complete identity verification before retrying.
KYC_PENDINGIdentity verification is already in progress for this account. This typically completes within 20 minutes but may take up to 48 hours.
VERIFICATION_REQUIREDCryptorefills requires additional verification for this account before the order can proceed. Contact Cryptorefills support if this persists.

HTTP-level errors (top-level detail field)

SUSPENDED_COINThe selected coin is temporarily suspended.
SUSPENDED_NETWORKThe selected network is temporarily suspended.

8

Create order

POST/v5/orders

Create an order and receive a wallet address for payment. Use the real end-user email because Cryptorefills must deliver the product to that recipient. Payment window is 30 minutes.

Only create orders your users intend to pay

Don't create orders to test your integration, check pricing, or validate input. That's what the validate order endpoint is for — it runs the same product, limit, and compliance checks without ever generating an order.

Every created order counts against your partner key. A high ratio of orders that are created but never paid is treated as abuse and can trigger automatic rate limiting and temporary suspension of your key.

Use validate order for testing and dry runs

bash

curl -X POST 'https://api.cryptorefills.com/v5/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT' \
  -d '{
    "deliveries": [
      {
        "brand_name": "Airbnb",
        "country_code": "US",
        "denomination": "100 USD",
        "beneficiary_account": "END_USER_EMAIL"
      }
    ],
    "payment": {
      "type": "via",
      "coin": "USDC",
      "network": "Solana",
      "payment_via": "USER_WALLET"
    },
    "user": {
      "email": "END_USER_EMAIL",
      "has_accepted_newsletter": true
    },
    "lang": "en",
    "acquisition": {
      "utm_source": "your_platform"
    }
  }'

Range product example

For products with a flexible amount (e.g. open-value gift cards), set denomination to "range" and pass the desired value in product_value.

bash

curl -X POST 'https://api.cryptorefills.com/v5/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT' \
  -d '{
    "payment": {
      "payment_via": "USER_WALLET",
      "coin": "USDC",
      "type": "via",
      "network": "POLYGON (MATIC)"
    },
    "deliveries": [
      {
        "beneficiary_account": "END_USER_EMAIL",
        "brand_name": "Everything Apple",
        "country_code": "US",
        "denomination": "range",
        "product_value": 12
      }
    ],
    "lang": "en"
  }'

Beneficiary account

Each delivery must include a beneficiary_account in its deliverable that's where Cryptorefills delivers the product. The required format depends on the product kind.

Gift cards and eSIMs: use the end-user's email address — for example user@example.com.
Mobile topups: use the recipient's phone number in E.164 format, including the leading + and the country code — for example +14155551234.

Response includes wallet_address and coin_amount. Share these with your user.

9a

Track order (stream API)

GET/api/orders/{orderId}/subscribe

Implement this in two required pieces: a server-side SSE proxy route and a client-side stream hook.

API route receives/api/orders/{orderId}/subscribe and forwards to upstream/v5/orders/{orderId}/subscribe.
Client hook opensEventSource to the local API route, validates payloads, and reconnects with backoff when needed.

Server-Side Essential Code

javascript

// app/api/orders/[orderId]/subscribe/route.ts
let upstream: Response;

try {
  upstream = await fetch(
    `https://api.cryptorefills.com/v5/orders/${params?.orderId}/subscribe`,
    {
      method: 'GET',
      headers: {
        ...(await genHeader.server(session)),
        'User-Agent': user_agent,
        Accept: 'text/event-stream',
        Connection: 'keep-alive',
      },
    },
  );
} catch (err) {
  return NextResponse.json(
    { error: 'Failed to connect to upstream stream' },
    { status: 502 },
  );
}

if (!upstream.ok || !upstream.body) {
  return NextResponse.json(
    { error: 'Upstream returned an error' },
    { status: upstream.status || 502 },
  );
}

// stream = ReadableStream that proxies upstream SSE events
return new Response(stream, {
  status: 200,
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache, no-transform',
    Connection: 'keep-alive',
    'X-Accel-Buffering': 'no',
  },
});

Client-Side Essential Code

javascript


const { data: lastEvent, error } = useSWRSubscription<TOrderSchema>(
  referenceOrderId ? `orders-info-stream-${referenceOrderId}` : null,
  ((key, { next }) => {
    let es: EventSource | null = null;
    let stopped = false;
    let shouldReconnect = true;
    let retryTimeout: number | null = null;
    let retryDelay = 1000;

    const cleanup = () => {
      if (es) {
        es.close();
        es = null;
      }
      if (retryTimeout !== null) {
        window.clearTimeout(retryTimeout);
        retryTimeout = null;
      }
    };

    const stopForever = () => {
      shouldReconnect = false;
      stopped = true;
      cleanup();
    };

    const connect = () => {
      if (stopped) return;
      cleanup();
      es = new EventSource(`/api/orders/${referenceOrderId}/subscribe`);

      es.addEventListener('message', (ev) => {
        try {
          const raw = JSON.parse(ev.data);
          const parsed = orderSchema.safeParse(raw);
          if (!parsed.success) return;
          retryDelay = 1000;
          next(null, parsed.data as TOrderSchema);
        } catch (err) {
          next(err as Error);
        }
      });

      es.addEventListener('stop', () => {
        stopForever();
      });

      es.onerror = () => {
        if (stopped || !shouldReconnect) return;
        cleanup();
        retryTimeout = window.setTimeout(() => {
          retryDelay = Math.min(retryDelay * 2, 30000);
          connect();
        }, retryDelay);
      };
    };

    connect();

    return () => {
      stopped = true;
      cleanup();
    };
  }) as SubscriptionCallback<TOrderSchema>,
);

Route in this repo

app/api/orders/[orderId]/subscribe/route.ts

Server side (API route)

Uses session-based server headers viagenHeader.server(session), then calls upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. On connection failure it returns502.

Client side (hook)

OpensEventSource to/api/orders/${referenceOrderId}/subscribe, validates each payload withorderSchema.safeParse, handlesstop events, and reconnects with exponential backoff.

9b

Track order (polling)

GET/v5/orders/{orderId}

Fallback approach: poll every 5-10 seconds until payment is received. Gift card code appears when status is 'Done'.

bash

curl -X GET 'https://api.cryptorefills.com/v5/orders/ord_abc123xyz' \
  -H 'Content-Type: application/json' \
  -H 'X-Cr-Application: YOUR_PARTNER_ID' \
  -H 'X-Cr-Version: YOUR_APP_VERSION' \
  -H 'X-Forwarded-For: END_USER_IP' \
  -H 'User-Agent: END_USER_AGENT'

Use polling when

You cannot keep an SSE connection open, or your client environment does not support EventSource reliably.

Typical order states

WaitingForPayment -> WaitingForDelivery -> Done

Created: Order has been created but no payment activity yet. Initial state right after checkout.
WaitingForPayment: Order is awaiting the customer's crypto payment. The payment window is open and countdown is running.
PaymentStarted: Customer has initiated a payment (transaction broadcast) but it hasn't been confirmed/received yet.
PartialPaymentStarted: A partial payment has been detected — the customer paid less than the required amount.
PaymentReceived: Payment has been received and confirmed on-chain, but delivery hasn't started yet.
WaitingForDelivery: Payment is confirmed; the order is queued for delivery.
WaitingForManualAction: Order requires manual intervention by the team (e.g. verification, supplier issue, edge case).
Done: Order is fully completed and delivered to the customer. Terminal success state.
Expired: Payment window elapsed without a valid payment being received. Terminal state.
PaymentFailed: The payment attempt failed (e.g. on-chain failure, rejected transaction).
PaymentSetupFailed: The payment couldn't even be set up (e.g. provider/quote failure before the user could pay).
Refunded: Order was refunded to the customer.

Developer API reference

Authentication

Payment methods

Brand catalog

Homepage feed

Browse products

Get crypto price

Validate order

Possible errors

Order amount & limits

Product availability

Payment method & network

Authentication

Coupon codes

Compliance & identity verification

HTTP-level errors (top-level detail field)

Create order

Only create orders your users intend to pay

Beneficiary account

Track order (stream API)

Track order (polling)