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, Ethereum, 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

(권장) 주문을 생성하기 전에 문제를 확인합니다. 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를 안정적으로 지원하지 않습니다.

일반적인 주문 상태

결제 대기 -> 배송 대기 -> 완료