1
Otentikasi
Setiap permintaan API memerlukan header ini. Setelah membuat akun Cryptorefills, Anda dapat menemukan ID Mitra Anda di halaman informasi akun Anda.
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
Metode pembayaran
GET
/v3/payment_viasAmbil semua koin dan jaringan blockchain yang didukung. Mengembalikan USDC, USDT di Solana, Ethereum, Base, Arbitrum, Polygon, dan lainnya.
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'Direkomendasikan: USDC di Solana menawarkan biaya terendah dan penyelesaian tercepat.
3
Katalog merek
GET
/v2/brands?country_code={countryCode}(Opsional) Daftar semua merek yang tersedia untuk suatu negara. Bagus untuk membangun direktori merek atau fitur pencarian.
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
Umpan beranda
GET
/v2/homepage?country_code={countryCode}(Opsional) Ambil umpan beranda yang dikurasi untuk suatu negara. Berguna untuk menampilkan kartu hadiah yang sedang tren atau unggulan.
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
Jelajahi produk
GET
/v5/products/country/{countryCode}Daftar semua kartu hadiah yang tersedia untuk suatu merek dan negara. Mendukung denominasi tetap dan jumlah kustom (rentang).
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
Dapatkan harga kripto
GET
/v4/products/priceUbah nilai kartu hadiah apa pun menjadi jumlah stablecoin. Gunakan ini untuk menunjukkan kepada pengguna jumlah kripto yang tepat sebelum mereka mengonfirmasi pembelian.
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
Validasi pesanan
POST
/v5/orders/validations(Disarankan) Periksa masalah sebelum membuat pesanan. Gunakan email pengguna akhir yang sebenarnya di email/beneficiary_account, karena Cryptorefills mengirimkan kepada penerima tersebut.
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
Buat pesanan
POST
/v5/ordersBuat pesanan dan terima alamat dompet untuk pembayaran. Gunakan email pengguna akhir yang sebenarnya karena Cryptorefills harus mengirimkan produk kepada penerima tersebut. Jendela pembayaran adalah 30 menit.
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"
}
}'Respon mencakup wallet_address and coin_amount. Bagikan ini dengan pengguna Anda.
9a
Lacak pesanan (API stream)
GET
/api/orders/{orderId}/subscribeTerapkan ini dalam dua bagian yang diperlukan: rute proxy SSE sisi server dan hook stream sisi klien.
- Rute API menerima
/api/orders/{orderId}/subscribedan meneruskan ke hulu/v5/orders/{orderId}/subscribe. - Hook klien membuka
EventSourceke rute API lokal, memvalidasi payload, dan menyambung kembali dengan backoff saat diperlukan.
Kode Esensial Sisi Server
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',
},
});Kode Esensial Sisi Klien
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>,
);Rute di repositori ini
app/api/orders/[orderId]/subscribe/route.ts
Sisi server (rute API)
Menggunakan header server berbasis sesi melaluigenHeader.server(session), kemudian memanggil hulu${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. Pada kegagalan koneksi, ia mengembalikan502.
Sisi klien (hook)
MembukaEventSource ke/api/orders/${referenceOrderId}/subscribe, memvalidasi setiap payload denganorderSchema.safeParse, menanganistop peristiwa, dan menyambung kembali dengan backoff eksponensial.
9b
Lacak pesanan (polling)
GET
/v5/orders/{orderId}Pendekatan cadangan: polling setiap 5-10 detik sampai pembayaran diterima. Kode kartu hadiah muncul ketika status adalah 'Selesai'.
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'Gunakan polling ketika
Anda tidak dapat menjaga koneksi SSE tetap terbuka, atau lingkungan klien Anda tidak mendukung EventSource dengan andal.
Status pesanan yang umum
MenungguPembayaran -> MenungguPengiriman -> Selesai