API para comercios de CardV

#Documentación

#Entornos

Sandbox es una copia de CardV separada, solo para pruebas, con dinero de prueba. Las claves, los saldos, los pedidos y los IDs de producto son distintos en cada entorno.

#Primeros pasos

1. Solicita una cuenta de comercio en el Portal y confirma tu correo.

2. Espera la aprobación. CardV revisa los datos de tu empresa. Luego recibes tu Merchant ID (número de comercio), por ejemplo M00000001.

3. Entra a Sandbox. Inicia sesión en el Portal y elige Sandbox en la parte superior. Recibes 1,000 USD de dinero de prueba.

4. Crea una clave de API. En el Portal, ve a Integrations → API keys. Crea una clave. El Portal muestra el key ID y el secreto de firma una sola vez. Guarda el secreto en tu gestor de secretos.

5. Consulta tu saldo:

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

6. Busca un producto:

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

   Elige uno con "availability": "available" y anota su sku_id.

7. Consulta el precio:

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

   Anota merchant_price. Es lo que pagas por unidad.

8. Haz el pedido. Fírmalo como cualquier llamada. Usa uno de los ejemplos de Autenticación con este cuerpo:

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.25"}
     ]
   }

   Recibes HTTP 201 con un ID de pedido de CardV, como O-00001234.

9. Lee los códigos. Llama a GET/api/v1/orders/O-00001234 hasta que el estado sea succeeded. Los códigos están en items[].deliveries[]: card_number, pin_code y redeem_url. También puedes recibir un webhook cuando el pedido termine.

10. Sal a producción después de completar la lista de verificación de Sandbox.

Los IDs y precios de arriba son ejemplos. Usa los valores que te devuelva tu propio catálogo.

#La API en resumen

Hay dieciséis endpoints. Todas las rutas empiezan con /api/v1.

Cualquier otro endpoint responde HTTP 403 si lo llamas con una clave de API:

{"detail": "This operation is only available in the Merchant Portal."}

Las recargas de celular se explican en Recargas de celular.

#IDs

Guarda los IDs como texto. No intentes interpretarlos. Consulta Convenciones.

#Lo que se hace en el Merchant Portal

• Agregar fondos a tu billetera y la alerta por correo de saldo bajo
• Historial de pedidos, búsqueda y exportación a CSV
• Facturas de pedidos
• Movimientos de la billetera y conciliación
• Configuración de webhooks, historial de envíos y reenvíos
• Claves de API
• Lista de IPs permitidas
• Miembros del equipo y roles
• Registro de auditoría
• Verificación en dos pasos (2FA)
• Cambio entre Live y Sandbox

#Compatibilidad y soporte

Podemos agregar campos nuevos a las respuestas y nuevos valores de estado sin previo aviso. Ignora los campos que no conozcas. Si un pedido tiene un estado desconocido, trátalo como "todavía no terminado". No dependas del texto exacto de los mensajes de error.

Escribe a [email protected] con tu Merchant ID, el entorno, los IDs de pedido, la hora (UTC) y el código HTTP. Nunca envíes claves de API, firmas, secretos de webhook ni códigos de tarjetas.