Referencia de API para desarrolladores de Cryptorefills: Integración de pago con stablecoin

Autenticación

Cada solicitud de API requiere estos encabezados. Después de crear una cuenta de Cryptorefills, puedes encontrar tu ID de socio en la página de información de tu cuenta.

Abrir la página de información de tu cuenta

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'

Métodos de pago

GET/v3/payment_vias

Obtén todas las monedas y redes blockchain soportadas. Devuelve USDC, USDT en Solana, Ethereum, Base, Arbitrum, Polygon y más.

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 en Solana ofrece las tarifas más bajas y la liquidación más rápida.

Catálogo de marcas

GET/v2/brands?country_code={countryCode}

(Opcional) Enumera todas las marcas disponibles para un país. Ideal para construir un directorio de marcas o características de búsqueda.

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'

Feed de la página de inicio

GET/v2/homepage?country_code={countryCode}

(Opcional) Obtén un feed curado para la página de inicio de un país. Útil para mostrar tarjetas de regalo en tendencia o destacadas.

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'

Explorar productos

GET/v5/products/country/{countryCode}

Enumera todas las tarjetas de regalo disponibles para una marca y un país. Soporta denominaciones fijas y montos personalizados (rangos).

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'

Obtener precio de criptomonedas

GET/v4/products/price

Convierte cualquier valor de tarjeta de regalo a un monto en stablecoin. Usa esto para mostrar a los usuarios el monto exacto en criptomonedas antes de que confirmen la 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'

Validar pedido

POST/v5/orders/validations

(Recomendado) Verifica si hay problemas antes de crear el pedido. Usa el correo electrónico real del usuario final en email/beneficiary_account, ya que Cryptorefills entrega a ese destinatario.

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"
  }'

Crear pedido

POST/v5/orders

Crea un pedido y recibe una dirección de billetera para el pago. Usa el correo electrónico real del usuario final porque Cryptorefills debe entregar el producto a ese destinatario. La ventana de pago es 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"
    }
  }'

La respuesta incluye wallet_address and coin_amount. Comparte esto con tu usuario.

Rastrear pedido (API de stream)

GET/api/orders/{orderId}/subscribe

Implementa esto en dos piezas requeridas: una ruta de proxy SSE del lado del servidor y un hook de stream del lado del cliente.

La ruta de la API recibe/api/orders/{orderId}/subscribe y reenvía a upstream/v5/orders/{orderId}/subscribe.
El hook del cliente abreEventSource a la ruta de la API local, valida las cargas útiles y se reconecta con retroceso cuando sea necesario.

Código Esencial del Lado del 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 Esencial del Lado del 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>,
);

Ruta en este repositorio

app/api/orders/[orderId]/subscribe/route.ts

Lado del servidor (ruta de API)

Usa encabezados de servidor basados en sesión a través degenHeader.server(session), luego llama a upstream${process.env.API_URL}/v5/orders/${params?.orderId}/subscribe. En caso de fallo de conexión, devuelve502.

Lado del cliente (hook)

AbreEventSource a/api/orders/${referenceOrderId}/subscribe, valida cada carga útil conorderSchema.safeParse, manejastop eventos y se reconecta con retroceso exponencial.

Rastrear pedido (polling)

GET/v5/orders/{orderId}

Enfoque de respaldo: consulta cada 5-10 segundos hasta que se reciba el pago. El código de la tarjeta de regalo aparece cuando el estado es 'Hecho'.

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'

Usa polling cuando

No puedes mantener una conexión SSE abierta, o tu entorno cliente no soporta EventSource de manera confiable.

Estados típicos del pedido

WaitingForPayment -> WaitingForDelivery -> Done