Cryptanio
Cuenta

Cómo aceptar pagos en USDC en tu sitio web

Configura el pago de un pedido en USDC en una red elegida de antemano: verifica el token exacto, conecta una dirección al proyecto, crea una factura y confirma el resultado en el servidor.

Actualizado:

Para aceptar USDC en tu sitio web, vincula el pedido a una factura Cryptanio y determina de antemano la red y el token exacto. Tomaremos una tienda que ha acordado cobrar en USDC en Ethereum. El servidor crea una factura independiente, el comprador recibe una página de pago y el pedido se confirma tras comprobar el resultado. Los fondos llegan a tu dirección.

Es un escenario de activo fijo: el comprador debe enviar la versión de USDC indicada, no cualquier moneda con un nombre parecido. La elección general entre un enlace de pago y una integración de servidor se explica en la guía para aceptar criptomonedas en un sitio web.

1. Determina qué USDC aceptas

Compara la red y el identificador del token con el directorio oficial de Circle. El nombre USDC y el logotipo de la cartera no bastan por sí solos. Que Circle admita una red no demuestra que esa ruta esté habilitada en tu proyecto Cryptanio.

Circle distingue native USDC, emitido por el propio emisor en la red, de bridged USDC, creado por un puente de terceros. No consideres estas formas intercambiables para tu factura; sus diferencias se describen en el material de Circle. Aquí se elige el USDC de Circle admitido en Ethereum. Para otra red, vuelve a comprobar su token y disponibilidad.

La palabra native en native USDC no significa la moneda nativa de la blockchain. En Ethereum, USDC sigue siendo un token y la moneda nativa es ETH. Esta diferencia importa al configurar la dirección.

2. Prepara la dirección para el activo correcto

Necesitas un proyecto con el servicio «Pagos» activo, la dirección pública de tu propia cartera y permisos para configurar el proyecto. Abre «Pagos», selecciona el proyecto y «Direcciones», y después «Agregar direcciones». En la pestaña «Manualmente», selecciona Ethereum e indica una dirección que controles.

Elige «Un activo» y rellena «Activo» con el identificador del USDC admitido en esa red, comprobado en el directorio de Circle. El campo vacío significa la moneda nativa, no native USDC. Mantén «Entrando» activado, añade la dirección y comprueba que la conexión esté activa y la red disponible. Guardar la dirección en la libreta no conecta por sí solo la recepción al servicio necesario.

Para un pool manual, prepara una dirección libre con la que emitir los datos de pago. No entregues la clave privada ni la frase semilla: no son necesarias para conectar una dirección pública. Las bases para comprobar la ruta se explican en Qué diferencia hay entre red y token.

3. Crea una factura para el pedido

Prepara una clave API de producción en el servidor con acceso a este proyecto, a la sección invoices («Invocaciones» en la interfaz) y el permiso «Lee y escriba». Guarda tu propio número de pedido antes de la solicitud. No entregues la clave al comprador.

A continuación tienes un ejemplo admitido de la API v1 para un activo fijo. Comprueba en la solicitud generada la red, el activo y el importe de tu pedido. Un importe en USDC es una cantidad de tokens, no un ingreso de dólares en una cuenta bancaria:

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"chain":"ethereum","asset":"USDC","amount":"12.50","reference":"order-42","expires_in":60,"customer":{"id":"customer-42"},"metadata":{"order":"42"}}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Descargar ejemplo

Indica tu proyecto y los datos del pedido. Utiliza un Idempotency-Key único para una operación nueva; conserva la misma clave al repetir la misma solicitud después de un fallo. Guarda la relación del pedido con el ID de la factura creada, la checkout_url recibida y los datos exactos de la respuesta. No redondees el importe devuelto ni lo sustituyas por la cifra de tu lista de precios.

4. Entrega al cliente la página de pago

Abre la checkout_url recibida desde el pedido de tu sitio web. No construyas la URL a partir del ID de la factura ni sustituyas los datos emitidos por una dirección permanente de la cartera. En este escenario ya están elegidos la red y el activo: el cliente debe comprobarlos en su cartera antes de enviar.

Pide el envío del importe exacto, teniendo en cuenta las reglas de comisiones de la cartera y el vencimiento del pago. Si el cliente tiene otra versión de USDC, cambiar el nombre del token no hará que la transferencia sea válida. Acordad primero la ruta correcta; no prometas intercambio ni puente automáticos por parte de Cryptanio.

5. Confirma el pedido y comprueba todo el proceso

El servidor debe consultar el estado actual de la factura mediante un webhook o consultas a la API. Entrega el pedido cuando esté en paid, manteniendo la protección contra la entrega duplicada. Una transacción detectada, una captura de pantalla o el regreso del comprador al sitio no sustituyen esta comprobación.

Gestiona los pagos insuficientes o excesivos, los ingresos tardíos y las reversiones según el estado de esa factura. En caso de duda, conserva el TXID y usa la guía de diagnóstico de pedidos no pagados. No asignes otro activo a este pedido solo porque el importe sea parecido.

Comprueba el proceso completo con un pedido propio: datos de pago, envío, confirmación y entrega. En modo de producción se usan fondos reales y comisiones de red. Comprobar únicamente la apariencia de la página o eventos artificiales no demuestra que el USDC elegido llegue realmente y se contabilice correctamente.

Artículos relacionados