مرجع واجهة برمجة التطبيقات لمطوري Cryptorefills: دمج الدفع بالعملات المستقرة

1

المصادقة

كل طلب واجهة برمجة التطبيقات يتطلب هذه الرؤوس. بعد إنشاء حساب Cryptorefills، يمكنك العثور على معرف الشريك الخاص بك في صفحة معلومات حسابك.

فتح صفحة معلومات حسابك

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

طرق الدفع

GET/v3/payment_vias

استرجع جميع العملات وشبكات البلوكشين المدعومة. تعود USDC، USDT على Solana، Ethereum، Base، Arbitrum، Polygon، والمزيد.

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'

موصى به: يوفر USDC على Solana أقل الرسوم وأسرع تسوية.

3

كتالوج العلامات التجارية

GET/v2/brands?country_code={countryCode}

(اختياري) قائمة بجميع العلامات التجارية المتاحة لدولة معينة. رائع لبناء دليل العلامات التجارية أو ميزات البحث.

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'

متغيرات عنوان URL للشعار

تُرجع كل علامة تجارية logo_url (افتراضي) و logo_base_url. أضف لاحقة إلى logo_base_url للحصول على أحجام وصيغ محسّنة.

.webpموصى به

{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

مثال: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp

رموز الدول المدعومة

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

4

تغذية الصفحة الرئيسية

GET/v2/homepage?country_code={countryCode}

(اختياري) جلب تغذية صفحة رئيسية منسقة لدولة معينة. مفيد لعرض بطاقات الهدايا الرائجة أو المميزة.

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

تصفح المنتجات

GET/v5/products/country/{countryCode}

قائمة بجميع بطاقات الهدايا المتاحة لعلامة تجارية ودولة معينة. يدعم القيم الثابتة والمبالغ المخصصة (النطاقات).

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/v4/products/price

تحويل أي قيمة بطاقة هدايا إلى مبلغ عملة مستقرة. استخدم هذا لعرض المبلغ الدقيق للعملة المشفرة للمستخدمين قبل تأكيد الشراء.

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

تحقق من الطلب

POST/v5/orders/validations

(موصى به) تحقق من المشكلات قبل إنشاء الطلب. استخدم البريد الإلكتروني الحقيقي للمستخدم النهائي في البريد الإلكتروني/حساب المستفيد، حيث أن Cryptorefills تسلم إلى ذلك المستلم.

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

الأخطاء المحتملة

تعيد الاستجابة مصفوفة مشاكل. كل عنصر يتخذ الشكل { problem, moreDetails? }، ويمكن إرجاع عدة مشاكل في وقت واحد. أخطاء HTTP على المستوى الأعلى (الإيقافات) تعود بالشكل { status, detail, moreDetails? } بدلاً من ذلك.

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

إنشاء طلب

POST/v5/orders

إنشاء طلب واستلام عنوان محفظة للدفع. استخدم البريد الإلكتروني الحقيقي للمستخدم النهائي لأن Cryptorefills يجب أن تسلم المنتج إلى ذلك المستلم. نافذة الدفع هي 30 دقيقة.

قم بإنشاء الطلبات التي ينوي مستخدموك دفعها فقط

لا تقم بإنشاء طلبات لاختبار تكاملتك، أو التحقق من الأسعار، أو التحقق من المدخلات. هذا ما هو عليه التحقق من الطلب — حيث يقوم بإجراء نفس فحوصات المنتج والحدود والامتثال دون إنشاء طلب أبدًا.

كل طلب تم إنشاؤه يُحتسب ضد مفتاح شريكك. يتم اعتبار نسبة عالية من الطلبات التي تم إنشاؤها ولكن لم يتم دفعها كإساءة ويمكن أن تؤدي إلى تقييد تلقائي في المعدل وتعليق مؤقت لمفتاحك.

استخدم التحقق من الطلب للاختبار والتجارب

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 في تسليمها، حيث تقوم Cryptorefills بتسليم المنتج. يعتمد التنسيق المطلوب على نوع المنتج.

بطاقات الهدايا و eSIMs: استخدم عنوان البريد الإلكتروني للمستخدم النهائي — على سبيل المثال user@example.com.
إعادة شحن الهواتف المحمولة: استخدم رقم هاتف المستلم بتنسيق E.164، بما في ذلك + ورمز الدولة — على سبيل المثال +14155551234.

الاستجابة تشمل wallet_address and coin_amount. شارك هذه مع المستخدم الخاص بك.

9a

تتبع الطلب (واجهة برمجة التطبيقات المتدفقة)

GET/api/orders/{orderId}/subscribe

قم بتنفيذ ذلك في جزئين مطلوبين: مسار وكيل SSE على جانب الخادم ووصلة تدفق على جانب العميل.

مسار واجهة برمجة التطبيقات يستقبل/api/orders/{orderId}/subscribe ويعيد توجيهه إلى المصدر/v5/orders/{orderId}/subscribe.
وصلة العميل تفتحEventSource إلى مسار واجهة برمجة التطبيقات المحلي، تتحقق من الحمولة، وتعيد الاتصال مع التراجع عند الحاجة.

كود أساسي على جانب الخادم

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

كود أساسي على جانب العميل

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

المسار في هذا المستودع

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

الجانب الخادم (مسار واجهة برمجة التطبيقات)

يستخدم رؤوس الخادم المعتمدة على الجلسة عبرgenHeader.server(session), ثم يستدعي المصدر${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. عند فشل الاتصال، يعيد502.

الجانب العميل (وصلة)

يفتحEventSource إلى/api/orders/${referenceOrderId}/subscribe, يتحقق من كل حمولة معorderSchema.safeParse, يتعامل معstop الأحداث، ويعيد الاتصال مع التراجع الأسي.

9b

تتبع الطلب (الاستطلاع)

GET/v5/orders/{orderId}

نهج احتياطي: الاستطلاع كل 5-10 ثوانٍ حتى يتم استلام الدفع. يظهر رمز بطاقة الهدايا عندما تكون الحالة 'تم'.

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'

استخدم الاستطلاع عندما

لا يمكنك الحفاظ على اتصال SSE مفتوح، أو أن بيئة العميل الخاصة بك لا تدعم EventSource بشكل موثوق.

حالات الطلب النموذجية

انتظار الدفع -> انتظار التسليم -> تم

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.

مرجع واجهة برمجة التطبيقات للمطورين

المصادقة

طرق الدفع

كتالوج العلامات التجارية

تغذية الصفحة الرئيسية

تصفح المنتجات

احصل على سعر العملات المشفرة

تحقق من الطلب

الأخطاء المحتملة

Order amount & limits

Product availability

Payment method & network

Authentication

Coupon codes

Compliance & identity verification

HTTP-level errors (top-level detail field)

إنشاء طلب

قم بإنشاء الطلبات التي ينوي مستخدموك دفعها فقط

حساب المستفيد

تتبع الطلب (واجهة برمجة التطبيقات المتدفقة)

تتبع الطلب (الاستطلاع)

أسئلة

مجتمع