Cryptorefills Geliştirici API Referansı: Stablecoin Ödeme Entegrasyonu

1

Kimlik doğrulama

Her API isteği bu başlıkları gerektirir. Cryptorefills hesabı oluşturduktan sonra, Ortak ID'nizi hesap bilgileri sayfanızda bulabilirsiniz.

Hesap bilgileri sayfanızı açın

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

Ödeme yöntemleri

GET/v3/payment_vias

Tüm desteklenen coinleri ve blockchain ağlarını alın. Solana, Ethereum, Base, Arbitrum, Polygon ve daha fazlasında USDC, USDT döner.

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'

Tavsiye edilen: Solana'daki USDC, en düşük ücretleri ve en hızlı yerleşimi sunar.

3

Marka kataloğu

GET/v2/brands?country_code={countryCode}

(Opsiyonel) Bir ülke için mevcut tüm markaları listeleyin. Marka dizini veya arama özellikleri oluşturmak için harika.

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 varyantları

Her marka bir logo_url (varsayılan) ve bir logo_base_url döner. Optimize edilmiş boyutlar ve formatlar almak için logo_base_url'ye bir ek ekleyin.

.webpTavsiye edilen

{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

Örnek: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp

Desteklenen ülke kodları

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

4

Ana sayfa akışı

GET/v2/homepage?country_code={countryCode}

(Opsiyonel) Bir ülke için küratörlü bir ana sayfa akışı alın. Trend olan veya öne çıkan hediye kartlarını görüntülemek için kullanışlı.

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

Ürünleri gözden geçirin

GET/v5/products/country/{countryCode}

Bir marka ve ülke için mevcut tüm hediye kartlarını listeleyin. Sabit tutarları ve özel miktarları (aralıkları) destekler.

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

Kripto fiyatını al

GET/v4/products/price

Herhangi bir hediye kartı değerini stabilcoin miktarına dönüştürün. Kullanıcılara satın alma onaylamadan önce tam kripto miktarını göstermek için bunu kullanın.

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

Siparişi doğrula

POST/v5/orders/validations

(Tavsiye edilir) Siparişi oluşturmadan önce sorunları kontrol edin. Gerçek son kullanıcı e-posta adresini email/beneficiary_account içinde kullanın, çünkü Cryptorefills bu alıcıya teslimat yapar.

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

Olası hatalar

Yanıt, bir problems dizisi döner. Her giriş { problem, moreDetails? } şeklindedir ve birden fazla problem aynı anda dönebilir. Üst düzey HTTP hataları (askıya alma) { status, detail, moreDetails? } şeklinde geri döner.

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

Sipariş oluştur

POST/v5/orders

Bir sipariş oluşturun ve ödeme için bir cüzdan adresi alın. Gerçek son kullanıcı e-posta adresini kullanın çünkü Cryptorefills ürünü bu alıcıya teslim etmelidir. Ödeme penceresi 30 dakikadır.

Sadece kullanıcılarınızın ödemek istediği siparişleri oluşturun

Entegrasyonunuzu test etmek, fiyatları kontrol etmek veya girişi doğrulamak için sipariş oluşturmayın. Bunun için siparişi doğrulama son noktasıdır — bu, asla bir sipariş oluşturmadan aynı ürün, limit ve uyum kontrollerini gerçekleştirir.

Oluşturulan her sipariş, ortak anahtarınıza karşı sayılır. Oluşturulan ancak asla ödenmeyen siparişlerin yüksek oranı, kötüye kullanım olarak değerlendirilir ve otomatik oran sınırlaması ve anahtarınızın geçici askıya alınmasını tetikleyebilir.

Test ve deneme çalışmaları için siparişi doğrulama kullanın

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

Alıcı hesabı

Her teslimat bir beneficiary_account içermelidir; bu, Cryptorefills'in ürünü teslim ettiği yerdir. Gerekli format, ürün türüne bağlıdır.

Hediye kartları ve eSIM'ler: son kullanıcıya ait e-posta adresini kullanın — örneğin user@example.com.
Mobil yüklemeler: alıcının telefon numarasını E.164 formatında, baştaki + ve ülke kodunu da dahil ederek kullanın — örneğin +14155551234.

Yanıt içerir wallet_address and coin_amount. Bunları kullanıcılarınızla paylaşın.

9a

Siparişi takip et (stream API)

GET/api/orders/{orderId}/subscribe

Bunu iki gerekli parçaya uygulayın: bir sunucu tarafı SSE proxy rotası ve bir istemci tarafı akış kancası.

API rotası alır/api/orders/{orderId}/subscribe ve yukarıya iletir/v5/orders/{orderId}/subscribe.
İstemci kancası açarEventSource yerel API rotasına, yükleri doğrular ve gerektiğinde geri bağlantı yapar.

Sunucu Tarafı Temel Kod

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

İstemci Tarafı Temel Kod

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

Bu repodaki rota

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

Sunucu tarafı (API rotası)

Oturum tabanlı sunucu başlıklarını kullanırgenHeader.server(session), ardından yukarıya çağrılar yapar${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. Bağlantı hatası durumunda döner502.

İstemci tarafı (kanca)

AçarEventSource şu adrese/api/orders/${referenceOrderId}/subscribe, her yükü doğrularorderSchema.safeParse, işlemleri yönetirstop olayları ve üstel geri bağlantı yapar.

9b

Siparişi takip et (polling)

GET/v5/orders/{orderId}

Yedek yaklaşım: Ödeme alınana kadar her 5-10 saniyede bir sorgulayın. Hediye kartı kodu 'Tamamlandı' durumunda görünür.

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'

Sorgulamayı kullanın

Bir SSE bağlantısını açık tutamıyorsanız veya istemci ortamınız EventSource'u güvenilir bir şekilde desteklemiyorsa.

Tipik sipariş durumları

ÖdemeBekliyor -> TeslimatBekliyor -> Tamamlandı

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.

Geliştirici API referansı

Kimlik doğrulama

Ödeme yöntemleri

Marka kataloğu

Ana sayfa akışı

Ürünleri gözden geçirin

Kripto fiyatını al

Siparişi doğrula

Olası hatalar

Order amount & limits

Product availability

Payment method & network

Authentication

Coupon codes

Compliance & identity verification

HTTP-level errors (top-level detail field)

Sipariş oluştur

Sadece kullanıcılarınızın ödemek istediği siparişleri oluşturun

Alıcı hesabı

Siparişi takip et (stream API)

Siparişi takip et (polling)