Dokumentacja API Dewelopera Cryptorefills: Integracja Płatności Stablecoin

1

Autoryzacja

Każde żądanie API wymaga tych nagłówków. Po utworzeniu konta Cryptorefills możesz znaleźć swoje ID partnera na stronie informacji o koncie.

Otwórz stronę informacji o koncie

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

Metody płatności

GET/v3/payment_vias

Pobierz wszystkie obsługiwane monety i sieci blockchain. Zwraca USDC, USDT na Solanie, Ethereum, Base, Arbitrum, Polygon i inne.

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'

Zalecane: USDC na Solanie oferuje najniższe opłaty i najszybsze rozliczenia.

3

Katalog marek

GET/v2/brands?country_code={countryCode}

(Opcjonalnie) Wymień wszystkie dostępne marki dla kraju. Doskonałe do budowania katalogu marek lub funkcji wyszukiwania.

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'

Warianty URL logo

Każda marka zwraca logo_url (domyślny) oraz logo_base_url. Dodaj sufiks do logo_base_url, aby pobrać zoptymalizowane rozmiary i formaty.

.webpZalecane

{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

Przykład: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp

Obsługiwane kody krajów

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

4

Kanał na stronie głównej

GET/v2/homepage?country_code={countryCode}

(Opcjonalnie) Pobierz kuratorowany kanał na stronie głównej dla kraju. Przydatne do wyświetlania trendujących lub wyróżnionych kart podarunkowych.

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

Przeglądaj produkty

GET/v5/products/country/{countryCode}

Wymień wszystkie dostępne karty podarunkowe dla marki i kraju. Obsługuje stałe nominały i niestandardowe kwoty (zakresy).

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

Uzyskaj cenę kryptowaluty

GET/v4/products/price

Przekształć wartość dowolnej karty podarunkowej na kwotę stablecoina. Użyj tego, aby pokazać użytkownikom dokładną kwotę kryptowaluty przed potwierdzeniem zakupu.

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

Zatwierdź zamówienie

POST/v5/orders/validations

(Zalecane) Sprawdź problemy przed utworzeniem zamówienia. Użyj prawdziwego adresu e-mail końcowego użytkownika w email/beneficiary_account, ponieważ Cryptorefills dostarcza do tego odbiorcy.

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

Możliwe błędy

Odpowiedź zwraca tablicę problemów. Każdy wpis ma kształt { problem, moreDetails? }, a wiele problemów może być zwróconych jednocześnie. Błędy HTTP na najwyższym poziomie (zawieszenia) są zwracane jako { status, detail, moreDetails? } zamiast tego.

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

Utwórz zamówienie

POST/v5/orders

Utwórz zamówienie i otrzymaj adres portfela do płatności. Użyj prawdziwego adresu e-mail końcowego użytkownika, ponieważ Cryptorefills musi dostarczyć produkt do tego odbiorcy. Okno płatności wynosi 30 minut.

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

Konto beneficjenta

Każda dostawa musi zawierać beneficiary_account w swoim dostarczanym produkcie, to tam Cryptorefills dostarcza produkt. Wymagany format zależy od rodzaju produktu.

Karty podarunkowe i eSIM-y: użyj adresu e-mail końcowego użytkownika — na przykład user@example.com.
Doładowania mobilne: użyj numeru telefonu odbiorcy w formacie E.164, w tym wiodącego + i kodu kraju — na przykład +14155551234.

Odpowiedź zawiera wallet_address and coin_amount. Podziel się tymi z użytkownikiem.

9a

Śledź zamówienie (API strumieniowe)

GET/api/orders/{orderId}/subscribe

Zaimplementuj to w dwóch wymaganych częściach: serwerowej trasie proxy SSE i klienckim hooku strumieniowym.

Trasa API otrzymuje/api/orders/{orderId}/subscribe i przekazuje do upstream/v5/orders/{orderId}/subscribe.
Hook klienta otwieraEventSource do lokalnej trasy API, waliduje ładunki i ponownie łączy się z opóźnieniem, gdy to konieczne.

Kod niezbędny po stronie serwera

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

Kod niezbędny po stronie klienta

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

Trasa w tym repozytorium

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

Strona serwera (trasa API)

Używa nagłówków serwera opartych na sesji przezgenHeader.server(session), a następnie wywołuje upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. W przypadku awarii połączenia zwraca502.

Strona klienta (hook)

OtwieraEventSource do/api/orders/${referenceOrderId}/subscribe, waliduje każdy ładunek zorderSchema.safeParse, obsługujestop zdarzenia i ponownie łączy się z wykładniczym opóźnieniem.

9b

Śledź zamówienie (polling)

GET/v5/orders/{orderId}

Podejście awaryjne: sprawdzaj co 5-10 sekund, aż płatność zostanie odebrana. Kod karty podarunkowej pojawia się, gdy status to 'Zrobione'.

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'

Użyj polling, gdy

Nie możesz utrzymać otwartego połączenia SSE lub twoje środowisko klienckie nie obsługuje EventSource niezawodnie.

Typowe stany zamówienia

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.

Dokumentacja API dla deweloperów

Autoryzacja

Metody płatności

Katalog marek

Kanał na stronie głównej

Przeglądaj produkty

Uzyskaj cenę kryptowaluty

Zatwierdź zamówienie

Możliwe błędy

Order amount & limits

Product availability

Payment method & network

Authentication

Coupon codes

Compliance & identity verification

HTTP-level errors (top-level detail field)

Utwórz zamówienie

Konto beneficjenta

Śledź zamówienie (API strumieniowe)

Śledź zamówienie (polling)