Riferimento API per sviluppatori Cryptorefills: Integrazione di checkout con stablecoin

1

Autenticazione

Ogni richiesta API richiede queste intestazioni. Dopo aver creato un account Cryptorefills, puoi trovare il tuo ID partner nella pagina delle informazioni del tuo account.

Apri la tua pagina delle informazioni dell'account

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

Metodi di pagamento

GET/v3/payment_vias

Recupera tutte le monete e le reti blockchain supportate. Restituisce USDC, USDT su Solana, Ethereum, Base, Arbitrum, Polygon e altro.

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'

Consigliato: USDC su Solana offre le commissioni più basse e il regolamento più veloce.

3

Catalogo marchi

GET/v2/brands?country_code={countryCode}

(Opzionale) Elenca tutti i marchi disponibili per un paese. Ottimo per costruire un directory di marchi o funzionalità di ricerca.

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'

Varianti dell'URL del logo

Ogni marchio restituisce un logo_url (predefinito) e un logo_base_url. Aggiungi un suffisso a logo_base_url per recuperare dimensioni e formati ottimizzati.

.webpConsigliato

{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

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

Codici paese supportati

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

4

Feed della homepage

GET/v2/homepage?country_code={countryCode}

(Opzionale) Recupera un feed curato per la homepage di un paese. Utile per visualizzare carte regalo in tendenza o in evidenza.

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

Sfoglia i prodotti

GET/v5/products/country/{countryCode}

Elenca tutte le carte regalo disponibili per un marchio e un paese. Supporta denominazioni fisse e importi personalizzati (intervalli).

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

Ottieni il prezzo delle criptovalute

GET/v4/products/price

Converti qualsiasi valore di carta regalo in un importo di stablecoin. Usa questo per mostrare agli utenti l'importo esatto in criptovaluta prima di confermare l'acquisto.

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

Convalida ordine

POST/v5/orders/validations

(Consigliato) Controlla eventuali problemi prima di creare l'ordine. Usa l'email reale dell'utente finale in email/beneficiary_account, poiché Cryptorefills consegna a quel destinatario.

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"
  }'

Errori possibili

La risposta restituisce un array di problemi. Ogni voce ha la forma { problema, moreDetails? }, e possono essere restituiti più problemi contemporaneamente. Gli errori HTTP di alto livello (sospensioni) vengono restituiti come { stato, dettaglio, moreDetails? } invece.

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

Crea ordine

POST/v5/orders

Crea un ordine e ricevi un indirizzo wallet per il pagamento. Usa l'email reale dell'utente finale perché Cryptorefills deve consegnare il prodotto a quel destinatario. La finestra di pagamento è di 30 minuti.

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"
  }'

Account beneficiario

Ogni consegna deve includere un beneficiary_account nel suo deliverable, è lì che Cryptorefills consegna il prodotto. Il formato richiesto dipende dal tipo di prodotto.

Gift card ed eSIM: usa l'indirizzo email dell'utente finale — per esempio user@example.com.
Ricariche mobili: usa il numero di telefono del destinatario nel formato E.164, inclusivo del + iniziale e del codice paese — per esempio +14155551234.

La risposta include wallet_address and coin_amount. Condividi questi con il tuo utente.

9a

Traccia ordine (stream API)

GET/api/orders/{orderId}/subscribe

Implementa questo in due parti richieste: un percorso proxy SSE lato server e un hook stream lato client.

Il percorso API riceve/api/orders/{orderId}/subscribe e inoltra a upstream/v5/orders/{orderId}/subscribe.
L'hook client apreEventSource al percorso API locale, convalida i payload e si riconnette con backoff quando necessario.

Codice essenziale lato server

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',
  },
});

Codice essenziale lato client

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>,
);

Percorso in questo repo

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

Lato server (percorso API)

Utilizza intestazioni server basate su sessione tramitegenHeader.server(session), quindi chiama upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. In caso di errore di connessione restituisce502.

Lato client (hook)

ApreEventSource a/api/orders/${referenceOrderId}/subscribe, convalida ogni payload conorderSchema.safeParse, gestiscestop eventi e si riconnette con backoff esponenziale.

9b

Traccia ordine (polling)

GET/v5/orders/{orderId}

Approccio di fallback: esegui il polling ogni 5-10 secondi fino a quando il pagamento non viene ricevuto. Il codice della carta regalo appare quando lo stato è 'Fatto'.

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'

Usa il polling quando

Non puoi mantenere aperta una connessione SSE, o il tuo ambiente client non supporta affidabilmente EventSource.

Stati tipici dell'ordine

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.