Cryptorefills 开发者 API 参考：稳定币结账集成

身份验证

每个 API 请求都需要这些请求头。在创建 Cryptorefills 账户后，您可以在账户信息页面找到您的合作伙伴 ID。

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'

支付方式

GET/v3/payment_vias

获取所有支持的币种和区块链网络。返回 Solana、以太坊、Base、Arbitrum、Polygon 等上的 USDC、USDT。

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'

推荐： Solana 上的 USDC 提供最低费用和最快的结算。

品牌目录

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'

主页动态

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'

浏览产品

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'

获取加密货币价格

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'

验证订单

POST/v5/orders/validations

(推荐) 在创建订单之前检查问题。使用真实的最终用户电子邮件在 email/beneficiary_account 中，因为 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' \
  -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"
  }'

创建订单

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

响应包括 wallet_address and coin_amount. 与您的用户分享这些。

跟踪订单（流 API）

GET/api/orders/{orderId}/subscribe

将此实现为两个必需部分：服务器端 SSE 代理路由和客户端流钩子。

API 路由接收/api/orders/{orderId}/subscribe 并转发到上游/v5/orders/{orderId}/subscribe.
客户端钩子打开EventSource 到本地 API 路由，验证有效负载，并在需要时以退避方式重新连接。

服务器端基本代码

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

服务器端（API 路由）

通过会话基础的服务器头使用genHeader.server(session)，然后调用上游${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. 在连接失败时返回502.

客户端（钩子）

打开EventSource 到/api/orders/${referenceOrderId}/subscribe, 使用验证每个有效负载orderSchema.safeParse, 处理stop 事件，并以指数退避方式重新连接。

跟踪订单（轮询）

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'

在以下情况下使用轮询

您无法保持 SSE 连接打开，或者您的客户端环境不可靠地支持 EventSource。

典型订单状态

等待付款 -> 等待交付 -> 完成