Tài liệu API Nhà phát triển Cryptorefills: Tích hợp Thanh toán Stablecoin

1

Xác thực

Mỗi yêu cầu API đều yêu cầu các tiêu đề này. Sau khi tạo tài khoản Cryptorefills, bạn có thể tìm thấy ID đối tác của mình trên trang thông tin tài khoản.

Mở trang thông tin tài khoản của bạn

bash

# Required headers for every API request
-H 'X-Cr-Application: YOUR_PARTNER_ID'
-H 'X-Cr-Version: YOUR_APP_VERSION'
-H 'X-Country-ISO-Code: US'
-H 'Content-Type: application/json'

2

Phương thức thanh toán

GET/v3/payment_vias

Lấy tất cả các đồng tiền và mạng lưới blockchain được hỗ trợ. Trả về USDC, USDT trên Solana, Ethereum, Base, Arbitrum, Polygon và nhiều hơn nữa.

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'

Được khuyến nghị: USDC trên Solana cung cấp phí thấp nhất và thanh toán nhanh nhất.

3

Danh mục thương hiệu

GET/v2/brands?country_code={countryCode}

(Tùy chọn) Liệt kê tất cả các thương hiệu có sẵn cho một quốc gia. Rất tốt để xây dựng thư mục thương hiệu hoặc các tính năng tìm kiếm.

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'

Biến thể URL logo

Mỗi thương hiệu trả về một logo_url (mặc định) và một logo_base_url. Thêm một hậu tố vào logo_base_url để lấy các kích thước và định dạng tối ưu.

.webpĐược khuyến nghị

{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

Ví dụ: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp

Mã quốc gia được hỗ trợ

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

4

Nguồn cấp trang chủ

GET/v2/homepage?country_code={countryCode}

(Tùy chọn) Lấy nguồn cấp trang chủ được chọn lọc cho một quốc gia. Hữu ích để hiển thị thẻ quà tặng đang thịnh hành hoặc nổi bật.

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'

5

Duyệt sản phẩm

GET/v5/products/country/{countryCode}

Liệt kê tất cả các thẻ quà tặng có sẵn cho một thương hiệu và quốc gia. Hỗ trợ các mệnh giá cố định và số tiền tùy chỉnh (khoảng).

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'

6

Lấy giá tiền điện tử

GET/v4/products/price

Chuyển đổi bất kỳ giá trị thẻ quà tặng nào sang số tiền stablecoin. Sử dụng điều này để hiển thị cho người dùng số tiền tiền điện tử chính xác trước khi họ xác nhận mua hàng.

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'

7

Xác thực đơn hàng

POST/v5/orders/validations

(Được khuyến nghị) Kiểm tra các vấn đề trước khi tạo đơn hàng. Sử dụng email của người dùng cuối thực tế trong email/tài khoản người thụ hưởng, vì Cryptorefills giao hàng cho người nhận đó.

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' \
  -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",
        "localized_denomination": "$100"
      }
    ],
    "lang": "en"
  }'

Các lỗi có thể xảy ra

Phản hồi trả về một mảng vấn đề. Mỗi mục có hình dạng { vấn đề, chi tiết thêm? }, và nhiều vấn đề có thể được trả về cùng một lúc. Các lỗi HTTP cấp cao (tạm ngưng) được trả về dưới dạng { trạng thái, chi tiết, chi tiết thêm? } thay vào đó.

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.

HTTP-level errors (top-level detail field)

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

8

Tạo đơn hàng

POST/v5/orders

Tạo một đơn hàng và nhận địa chỉ ví để thanh toán. Sử dụng email của người dùng cuối thực tế vì Cryptorefills phải giao sản phẩm cho người nhận đó. Thời gian thanh toán là 30 phút.

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' \
  -d '{
    "deliveries": [
      {
        "kind": "giftcard",
        "quantity": 1,
        "deliverable": {
          "brand_name": "Airbnb",
          "country_code": "US",
          "denomination": "100",
          "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"
    }
  }'

Tài khoản người thụ hưởng

Mỗi lần giao hàng phải bao gồm một beneficiary_account trong sản phẩm giao hàng của nó, đó là nơi Cryptorefills giao sản phẩm. Định dạng yêu cầu phụ thuộc vào loại sản phẩm.

Thẻ quà tặng và eSIM: sử dụng địa chỉ email của người dùng cuối — ví dụ user@example.com.
Nạp tiền di động: sử dụng số điện thoại của người nhận theo định dạng E.164, bao gồm dấu + ở đầu và mã quốc gia — ví dụ +14155551234.

Phản hồi bao gồm wallet_address and coin_amount. Chia sẻ những điều này với người dùng của bạn.

9a

Theo dõi đơn hàng (API stream)

GET/api/orders/{orderId}/subscribe

Triển khai điều này trong hai phần cần thiết: một tuyến proxy SSE phía máy chủ và một hook stream phía khách hàng.

Tuyến API nhận/api/orders/{orderId}/subscribe và chuyển tiếp đến upstream/v5/orders/{orderId}/subscribe.
Hook khách hàng mởEventSource đến tuyến API cục bộ, xác thực payload, và kết nối lại với backoff khi cần thiết.

Mã cần thiết phía máy chủ

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

Mã cần thiết phía khách hàng

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

Tuyến trong repo này

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

Phía máy chủ (tuyến API)

Sử dụng tiêu đề máy chủ dựa trên phiên thông quagenHeader.server(session), sau đó gọi upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. Khi kết nối thất bại, nó trả về502.

Phía khách hàng (hook)

MởEventSource đến/api/orders/${referenceOrderId}/subscribe, xác thực từng payload vớiorderSchema.safeParse, xử lýstop sự kiện, và kết nối lại với backoff theo cấp số nhân.

9b

Theo dõi đơn hàng (polling)

GET/v5/orders/{orderId}

Cách tiếp cận dự phòng: polling mỗi 5-10 giây cho đến khi thanh toán được nhận. Mã thẻ quà tặng xuất hiện khi trạng thái là 'Hoàn thành'.

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'

Sử dụng polling khi

Bạn không thể giữ kết nối SSE mở, hoặc môi trường khách hàng của bạn không hỗ trợ EventSource một cách đáng tin cậy.

Các trạng thái đơn hàng điển hình

WaitingForPayment -> WaitingForDelivery -> Done

Tài liệu API cho nhà phát triển

Xác thực

Phương thức thanh toán

Danh mục thương hiệu

Nguồn cấp trang chủ

Duyệt sản phẩm

Lấy giá tiền điện tử

Xác thực đơn hàng

Các lỗi có thể xảy ra

Order amount & limits

Product availability

Payment method & network

Authentication

Coupon codes

HTTP-level errors (top-level detail field)

Tạo đơn hàng

Tài khoản người thụ hưởng

Theo dõi đơn hàng (API stream)

Theo dõi đơn hàng (polling)