1
Autenticação
Cada solicitação da API requer esses cabeçalhos. Após criar uma conta no Cryptorefills, você pode encontrar seu ID de parceiro na página de informações da sua conta.
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
Métodos de pagamento
GET
/v3/payment_viasBusque todas as moedas e redes blockchain suportadas. Retorna USDC, USDT na Solana, Ethereum, Base, Arbitrum, Polygon e mais.
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'Recomendado: USDC na Solana oferece as taxas mais baixas e a liquidação mais rápida.
3
Catálogo de marcas
GET
/v2/brands?country_code={countryCode}(Opcional) Liste todas as marcas disponíveis para um país. Ótimo para construir um diretório de marcas ou recursos de busca.
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
Feed da página inicial
GET
/v2/homepage?country_code={countryCode}(Opcional) Busque um feed da página inicial curado para um país. Útil para exibir cartões-presente em alta ou em destaque.
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
Navegar por produtos
GET
/v5/products/country/{countryCode}Liste todos os cartões-presente disponíveis para uma marca e país. Suporta denominações fixas e valores personalizados (intervalos).
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
Obter preço de criptomoeda
GET
/v4/products/priceConverta qualquer valor de cartão-presente em um valor de stablecoin. Use isso para mostrar aos usuários o valor exato em criptomoeda antes de confirmarem a compra.
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
Validar pedido
POST
/v5/orders/validations(Recomendado) Verifique se há problemas antes de criar o pedido. Use o e-mail real do usuário final em email/beneficiary_account, já que a Cryptorefills entrega ao destinatário.
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
Criar pedido
POST
/v5/ordersCrie um pedido e receba um endereço de carteira para pagamento. Use o e-mail real do usuário final porque a Cryptorefills deve entregar o produto a esse destinatário. A janela de pagamento é de 30 minutos.
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"
}
}'A resposta inclui wallet_address and coin_amount. Compartilhe isso com seu usuário.
9a
Rastrear pedido (API de stream)
GET
/api/orders/{orderId}/subscribeImplemente isso em duas partes obrigatórias: uma rota de proxy SSE do lado do servidor e um hook de stream do lado do cliente.
- A rota da API recebe
/api/orders/{orderId}/subscribee encaminha para o upstream/v5/orders/{orderId}/subscribe. - O hook do cliente abre
EventSourcepara a rota da API local, valida os payloads e reconecta com backoff quando necessário.
Código Essencial do Lado do Servidor
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',
},
});Código Essencial do Lado do Cliente
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>,
);Rota neste repositório
app/api/orders/[orderId]/subscribe/route.ts
Lado do servidor (rota da API)
Usa cabeçalhos de servidor baseados em sessão viagenHeader.server(session), então chama o upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. Em caso de falha de conexão, retorna502.
Lado do cliente (hook)
AbreEventSource para/api/orders/${referenceOrderId}/subscribe, valida cada payload comorderSchema.safeParse, manipulastop eventos e reconecta com backoff exponencial.
9b
Rastrear pedido (polling)
GET
/v5/orders/{orderId}Abordagem de fallback: faça polling a cada 5-10 segundos até que o pagamento seja recebido. O código do cartão-presente aparece quando o status é 'Concluído'.
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'Use polling quando
Você não pode manter uma conexão SSE aberta, ou seu ambiente cliente não suporta EventSource de forma confiável.
Estados típicos do pedido
AguardandoPagamento -> AguardandoEntrega -> Concluído