Phạm vi API

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

Các ví dụ cURL và Node tập trung vào sản xuất cho thanh toán stablecoin, tạo đơn hàng và theo dõi giao hàng.

Được đề cập trong hướng dẫn này

  • Thẻ quà tặng
  • Nạp tiền di động
  • Mua eSIM

Không được đề cập ở đây

  • Chuyến bay
  • Chỗ ở

Cần bối cảnh tích hợp rộng hơn trước khi đi vào các điểm cuối?

Mở tổng quan về tích hợp
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'
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"
  }'
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"
        }
      }
    ],
    "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"
    }
  }'

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