Xác thực
# Required headers for every API request
-H 'X-Cr-Application: YOUR_PARTNER_ID'
-H 'X-Cr-Version: YOUR_APP_VERSION'
-H 'X-Forwarded-For: END_USER_IP'
-H 'User-Agent: END_USER_AGENT'
-H 'Content-Type: application/json'Phương thức thanh toán
/v3/payment_viascurl -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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Được khuyến nghị: USDC trên Solana cung cấp phí thấp nhất và thanh toán nhanh nhất.
Danh mục thương hiệu
/v2/brands?country_code={countryCode}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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Biến thể URL logo
Mỗi thương hiệu trả về một logo_url (mặc định) và một logo_base_url. Thêm một hậu tố vào logo_base_url để lấy các kích thước và định dạng tối ưu.
.webpĐược khuyến nghị
{logo_base_url}.webp{logo_base_url}_500x318.webp{logo_base_url}_300x190.webp
.jpg
{logo_base_url}.jpg{logo_base_url}_500x318.jpg{logo_base_url}_300x190.jpg
Ví dụ: https://cdn.cryptorefills.com/logos_v2/esim_500x318.webp
Mã quốc gia được hỗ trợ
231GET https://cryptorefills.com/api/available-countriesAXÅland IslandsALAlbaniaDZAlgeriaASAmerican SamoaADAndorraAOAngolaAIAnguillaAQAntarcticaAGAntigua and BarbudaARArgentinaAMArmeniaAWArubaAUAustraliaATAustriaAZAzerbaijanBSBahamasBHBahrainBDBangladeshBBBarbadosBEBelgiumBZBelizeBJBeninBMBermudaBTBhutanBOBoliviaBQBonaire, Sint Eustatius and SabaBABosnia and HerzegovinaBWBotswanaBVBouvet IslandBRBrazilIOBritish Indian Ocean TerritoryBNBrunei DarussalamBGBulgariaBFBurkina FasoCVCabo VerdeKHCambodiaCMCameroonCACanadaKYCayman IslandsTDChadCLChileCNChinaCXChristmas IslandCCCocos (Keeling) IslandsCOColombiaKMComorosCGCongoCKCook IslandsCRCosta RicaCICôte d'IvoireHRCroatiaCWCuraçaoCYCyprusCZCzechiaDKDenmarkDJDjiboutiDMDominicaDODominican RepublicECEcuadorEGEgyptSVEl SalvadorGQEquatorial GuineaEREritreaEEEstoniaSZEswatiniETEthiopiaFKFalkland IslandsFOFaroe IslandsFJFijiFIFinlandFRFranceGFFrench GuianaPFFrench PolynesiaTFFrench Southern TerritoriesGAGabonGMGambiaGEGeorgiaDEGermanyGHGhanaGIGibraltarGRGreeceGLGreenlandGDGrenadaGPGuadeloupeGUGuamGTGuatemalaGGGuernseyGNGuineaGWGuinea-BissauGYGuyanaHTHaitiHMHeard Island and McDonald IslandsHNHondurasHKHong KongHUHungaryISIcelandINIndiaIDIndonesiaIEIrelandIMIsle of ManILIsraelITItalyJMJamaicaJPJapanJEJerseyJOJordanKZKazakhstanKEKenyaKIKiribatiXKKosovoKWKuwaitKGKyrgyzstanLALaosLVLatviaLBLebanonLSLesothoLRLiberiaLILiechtensteinLTLithuaniaLULuxembourgMOMacaoMGMadagascarMWMalawiMYMalaysiaMVMaldivesMTMaltaMHMarshall IslandsMQMartiniqueMRMauritaniaMUMauritiusYTMayotteMXMexicoFMMicronesiaMDMoldovaMCMonacoMNMongoliaMEMontenegroMSMontserratMAMoroccoMZMozambiqueNANamibiaNRNauruNPNepalNLNetherlandsNCNew CaledoniaNZNew ZealandNINicaraguaNENigerNGNigeriaNUNiueNFNorfolk IslandMKNorth MacedoniaMPNorthern Mariana IslandsNONorwayOMOmanPKPakistanPWPalauPSPalestinePAPanamaPGPapua New GuineaPYParaguayPEPeruPHPhilippinesPNPitcairnPLPolandPTPortugalPRPuerto RicoQAQatarRERéunionRORomaniaRWRwandaBLSaint BarthélemySHSaint HelenaKNSaint Kitts and NevisLCSaint LuciaMFSaint Martin (French part)PMSaint Pierre and MiquelonVCSaint Vincent and the GrenadinesWSSamoaSMSan MarinoSTSao Tome and PrincipeSASaudi ArabiaSNSenegalRSSerbiaSCSeychellesSLSierra LeoneSGSingaporeSXSint MaartenSKSlovakiaSISloveniaSBSolomon IslandsZASouth AfricaGSSouth Georgia and the South Sandwich IslandsKRSouth KoreaESSpainLKSri LankaSRSurinameSJSvalbard and Jan MayenSESwedenCHSwitzerlandTWTaiwanTJTajikistanTZTanzaniaTHThailandTLTimor-LesteTGTogoTKTokelauTOTongaTTTrinidad and TobagoTNTunisiaTRTürkiyeTMTurkmenistanTCTurks and Caicos IslandsTVTuvaluUGUgandaUAUkraineAEUnited Arab EmiratesGBUnited KingdomUSUnited StatesUMUnited States Minor Outlying IslandsUYUruguayUZUzbekistanVUVanuatuVAVatican CityVNVietnamVGVirgin Islands (British)VIVirgin Islands (U.S.)WFWallis and FutunaEHWestern SaharaYEYemenZMZambia
Nguồn cấp trang chủ
/v2/homepage?country_code={countryCode}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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Duyệt sản phẩm
/v5/products/country/{countryCode}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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Lấy giá tiền điện tử
/v4/products/pricecurl -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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Xác thực đơn hàng
/v5/orders/validationscurl -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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT' \
-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"
}
],
"lang": "en"
}'Các lỗi có thể xảy ra
Phản hồi trả về một mảng vấn đề. Mỗi mục có hình dạng { vấn đề, chi tiết thêm? }, và nhiều vấn đề có thể được trả về cùng một lúc. Các lỗi HTTP cấp cao (tạm ngưng) được trả về dưới dạng { trạng thái, chi tiết, chi tiết thêm? } thay vào đó.
Order amount & limits
AMOUNT_LESS_THEN_MINIMUM_ALLOWEDOrder total is below the minimum coin amount allowed.MAXIMUM_AMOUNT_PER_ORDER_EXCEEDEDOrder total exceeds the per-order maximum.DAILY_SPENDING_LIMIT_EXCEEDEDUser has hit the daily spending limit for their tier.MONTHLY_SPENDING_LIMIT_EXCEEDEDUser has hit the monthly spending limit for their tier.PRODUCT_COUNT_EXCEEDEDCart contains more products than the per-order maximum.MULTIPLE_LIMITED_PRODUCT_SAME_ORDEROrder contains more than one rate-limited product.
Product availability
NOT_AVAILABLE_PRODUCTProduct is no longer in the catalogue.OUT_OF_STOCKProduct is currently out of stock.NOT_ACTIVEProduct is inactive or paused.INVALID_BENEFICIARY_ACCOUNTBeneficiary account is invalid — e.g. phone number for a mobile topup or email for a gift card.
Payment method & network
NOT_ALLOWED_PAYMENT_VIASelected payment_via is not allowed for this order. moreDetails lists allowed kinds.UNSUPPORTED_PROTOCOL_COIN_COMBINATIONChosen protocol + coin pair is not supported. moreDetails lists supported combinations.
Authentication
LOGIN_REQUIREDOne or more products require a signed-in user.COUPON_REQUIRES_LOGINThe coupon can only be redeemed by a signed-in user.
Coupon codes
COUPON_NOT_FOUNDCoupon code does not exist.COUPON_NOT_ACTIVECoupon is not yet active.COUPON_ALREADY_SPENTCoupon has already been redeemed by this user.COUPON_MAX_USAGE_REACHEDCoupon has reached its overall usage cap.COUPON_EXPIREDCoupon is past its validity date.COUPON_BELOW_MIN_AMOUNTOrder total is below the coupon’s minimum amount.COUPON_NOT_VALID_FOR_USERCoupon is not valid for this user.COUPON_NOT_VALID_FOR_CATEGORYCoupon does not apply to the selected product categories.COUPON_NOT_VALID_FOR_KINDCoupon does not apply to the selected product kind.COUPON_NOT_VALID_FOR_BRANDCoupon does not apply to the selected brands.COUPON_NOT_VALID_FOR_COUNTRYCoupon is not valid in the order country.COUPON_NOT_VALID_FOR_STORECoupon is not valid for the requested store or region.
Compliance & identity verification
KYC_MISSINGOne or more products require a verified account, or the user has exceeded the spending limit for unverified accounts. Direct the user to their Cryptorefills account to complete identity verification before retrying.KYC_PENDINGIdentity verification is already in progress for this account. This typically completes within 20 minutes but may take up to 48 hours.VERIFICATION_REQUIREDCryptorefills requires additional verification for this account before the order can proceed. Contact Cryptorefills support if this persists.
HTTP-level errors (top-level detail field)
SUSPENDED_COINThe selected coin is temporarily suspended.SUSPENDED_NETWORKThe selected network is temporarily suspended.
Tạo đơn hàng
/v5/ordersChỉ tạo đơn hàng mà người dùng của bạn dự định thanh toán
Đừng tạo đơn hàng để kiểm tra tích hợp của bạn, kiểm tra giá cả, hoặc xác thực đầu vào. Đó là những gì xác thực đơn hàng để làm — nó thực hiện cùng các kiểm tra sản phẩm, giới hạn và tuân thủ mà không bao giờ tạo ra một đơn hàng.
Mỗi đơn hàng được tạo đều tính vào khóa đối tác của bạn. Tỷ lệ cao các đơn hàng được tạo nhưng không bao giờ được thanh toán sẽ được coi là lạm dụng và có thể kích hoạt giới hạn tự động và tạm thời đình chỉ khóa của bạn.
Sử dụng xác thực đơn hàng để kiểm tra và chạy thử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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT' \
-d '{
"deliveries": [
{
"brand_name": "Airbnb",
"country_code": "US",
"denomination": "100 USD",
"beneficiary_account": "END_USER_EMAIL"
}
],
"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"
}
}'Range product example
For products with a flexible amount (e.g. open-value gift cards), set denomination to "range" and pass the desired value in product_value.
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' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT' \
-d '{
"payment": {
"payment_via": "USER_WALLET",
"coin": "USDC",
"type": "via",
"network": "POLYGON (MATIC)"
},
"deliveries": [
{
"beneficiary_account": "END_USER_EMAIL",
"brand_name": "Everything Apple",
"country_code": "US",
"denomination": "range",
"product_value": 12
}
],
"lang": "en"
}'Tài khoản người thụ hưởng
Mỗi lần giao hàng phải bao gồm một beneficiary_account trong sản phẩm giao hàng của nó, đó là nơi Cryptorefills giao sản phẩm. Định dạng yêu cầu phụ thuộc vào loại sản phẩm.
- Thẻ quà tặng và eSIM: sử dụng địa chỉ email của người dùng cuối — ví dụ
user@example.com. - Nạp tiền di động: sử dụng số điện thoại của người nhận theo định dạng E.164, bao gồm dấu + ở đầu và mã quốc gia — ví dụ
+14155551234.
Dùng email của chính khách hàng
Truyền một email mà chỉ khách hàng của bạn truy cập được vào user.email. Chúng tôi gửi đơn hàng đến đó và dùng nó để xác nhận đúng là họ khi hoàn tiền hoặc hỗ trợ: chúng tôi chỉ chia sẻ chi tiết đơn hàng hoặc sắp xếp hoàn tiền qua địa chỉ đó. Nếu bạn truyền địa chỉ của nền tảng mình, các yêu cầu hỗ trợ của khách hàng sẽ phải đi qua bạn.
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.
Lưu token đơn hàng
Phản hồi cũng bao gồm order_token. Token chỉ được trả về trong phản hồi này. Hãy lưu nó trên máy chủ cùng ID đơn hàng và gửi dưới dạng ?ot= khi đọc đơn hàng hoặc stream của đơn. Đừng ghi nó vào log hoặc đưa vào liên kết bạn chia sẻ.
Theo dõi đơn hàng (API stream)
/api/orders/{orderId}/subscribe- Tuyến API nhận
/api/orders/{orderId}/subscribevà 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ủ
// app/api/orders/[orderId]/subscribe/route.ts
// The order_token saved at creation, read on the server, never from the browser
const orderToken = await getOrderToken(params?.orderId);
let upstream: Response;
try {
upstream = await fetch(
`https://api.cryptorefills.com/v5/orders/${params?.orderId}/subscribe?ot=${encodeURIComponent(orderToken)}`,
{
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
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();
});
// Access refused: reconnecting will not help
es.addEventListener('auth_required', () => {
stopForever();
next(new Error('Order access refused'));
});
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?ot=${orderToken}. 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.
Quyền truy cập đơn hàng
ID đơn hàng chỉ dùng để nhận diện đơn, không cấp quyền truy cập. Hãy thêm ?ot=ORDER_TOKEN vào mọi lần đọc đơn hàng và stream của đơn. Nếu thiếu, API trả về 403.
Đối tác có API auth token có thể gửi header X-CR-API-Auth-Token để đọc đơn hàng của storefront của chính mình.
Stream bị từ chối không trả về lỗi HTTP. Nó gửi một sự kiện auth_required rồi đóng lại. Hãy ngừng kết nối lại khi nhận được sự kiện này.
Theo dõi đơn hàng (polling)
/v5/orders/{orderId}curl -X GET 'https://api.cryptorefills.com/v5/orders/ord_abc123xyz?ot=ORDER_TOKEN' \
-H 'Content-Type: application/json' \
-H 'X-Cr-Application: YOUR_PARTNER_ID' \
-H 'X-Cr-Version: YOUR_APP_VERSION' \
-H 'X-Forwarded-For: END_USER_IP' \
-H 'User-Agent: END_USER_AGENT'Quyền truy cập đơn hàng
ID đơn hàng chỉ dùng để nhận diện đơn, không cấp quyền truy cập. Hãy thêm ?ot=ORDER_TOKEN vào mọi lần đọc đơn hàng và stream của đơn. Nếu thiếu, API trả về 403.
Đối tác có API auth token có thể gửi header X-CR-API-Auth-Token để đọc đơn hàng của storefront của chính mình.
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
- Created
- Order has been created but no payment activity yet. Initial state right after checkout.
- WaitingForPayment
- Order is awaiting the customer's crypto payment. The payment window is open and countdown is running.
- PaymentStarted
- Customer has initiated a payment (transaction broadcast) but it hasn't been confirmed/received yet.
- PartialPaymentStarted
- A partial payment has been detected — the customer paid less than the required amount.
- PaymentReceived
- Payment has been received and confirmed on-chain, but delivery hasn't started yet.
- WaitingForDelivery
- Payment is confirmed; the order is queued for delivery.
- WaitingForManualAction
- Order requires manual intervention by the team (e.g. verification, supplier issue, edge case).
- Done
- Order is fully completed and delivered to the customer. Terminal success state.
- Expired
- Payment window elapsed without a valid payment being received. Terminal state.
- PaymentFailed
- The payment attempt failed (e.g. on-chain failure, rejected transaction).
- PaymentSetupFailed
- The payment couldn't even be set up (e.g. provider/quote failure before the user could pay).
- Refunded
- Order was refunded to the customer.