1
Autoryzacja
Każde żądanie API wymaga tych nagłówków. Po utworzeniu konta Cryptorefills możesz znaleźć swoje ID partnera na stronie informacji o koncie.
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
Metody płatności
GET
/v3/payment_viasPobierz wszystkie obsługiwane monety i sieci blockchain. Zwraca USDC, USDT na Solanie, Ethereum, Base, Arbitrum, Polygon i inne.
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'Zalecane: USDC na Solanie oferuje najniższe opłaty i najszybsze rozliczenia.
3
Katalog marek
GET
/v2/brands?country_code={countryCode}(Opcjonalnie) Wymień wszystkie dostępne marki dla kraju. Doskonałe do budowania katalogu marek lub funkcji wyszukiwania.
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
Kanał na stronie głównej
GET
/v2/homepage?country_code={countryCode}(Opcjonalnie) Pobierz kuratorowany kanał na stronie głównej dla kraju. Przydatne do wyświetlania trendujących lub wyróżnionych kart podarunkowych.
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
Przeglądaj produkty
GET
/v5/products/country/{countryCode}Wymień wszystkie dostępne karty podarunkowe dla marki i kraju. Obsługuje stałe nominały i niestandardowe kwoty (zakresy).
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
Uzyskaj cenę kryptowaluty
GET
/v4/products/pricePrzekształć wartość dowolnej karty podarunkowej na kwotę stablecoina. Użyj tego, aby pokazać użytkownikom dokładną kwotę kryptowaluty przed potwierdzeniem zakupu.
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
Zatwierdź zamówienie
POST
/v5/orders/validations(Zalecane) Sprawdź problemy przed utworzeniem zamówienia. Użyj prawdziwego adresu e-mail końcowego użytkownika w email/beneficiary_account, ponieważ Cryptorefills dostarcza do tego odbiorcy.
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
Utwórz zamówienie
POST
/v5/ordersUtwórz zamówienie i otrzymaj adres portfela do płatności. Użyj prawdziwego adresu e-mail końcowego użytkownika, ponieważ Cryptorefills musi dostarczyć produkt do tego odbiorcy. Okno płatności wynosi 30 minut.
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"
}
}'Odpowiedź zawiera wallet_address and coin_amount. Podziel się tymi z użytkownikiem.
9a
Śledź zamówienie (API strumieniowe)
GET
/api/orders/{orderId}/subscribeZaimplementuj to w dwóch wymaganych częściach: serwerowej trasie proxy SSE i klienckim hooku strumieniowym.
- Trasa API otrzymuje
/api/orders/{orderId}/subscribei przekazuje do upstream/v5/orders/{orderId}/subscribe. - Hook klienta otwiera
EventSourcedo lokalnej trasy API, waliduje ładunki i ponownie łączy się z opóźnieniem, gdy to konieczne.
Kod niezbędny po stronie serwera
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',
},
});Kod niezbędny po stronie klienta
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>,
);Trasa w tym repozytorium
app/api/orders/[orderId]/subscribe/route.ts
Strona serwera (trasa API)
Używa nagłówków serwera opartych na sesji przezgenHeader.server(session), a następnie wywołuje upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. W przypadku awarii połączenia zwraca502.
Strona klienta (hook)
OtwieraEventSource do/api/orders/${referenceOrderId}/subscribe, waliduje każdy ładunek zorderSchema.safeParse, obsługujestop zdarzenia i ponownie łączy się z wykładniczym opóźnieniem.
9b
Śledź zamówienie (polling)
GET
/v5/orders/{orderId}Podejście awaryjne: sprawdzaj co 5-10 sekund, aż płatność zostanie odebrana. Kod karty podarunkowej pojawia się, gdy status to 'Zrobione'.
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'Użyj polling, gdy
Nie możesz utrzymać otwartego połączenia SSE lub twoje środowisko klienckie nie obsługuje EventSource niezawodnie.
Typowe stany zamówienia
WaitingForPayment -> WaitingForDelivery -> Done