Documentación / Referencia

Bibliotecas cliente

Cada cliente es un único archivo sin dependencias externas. Cópielo en su proyecto y tendrá firma de solicitudes, creación y consulta de facturas y verificación de webhooks.

Node.js

Node 22+. Clases CoineticClient y CoineticError, función verifyWebhook.

Descargar cryptopay.js ↓

PHP

PHP 8.1+, extensiones curl y json. \Cryptopay\Client, \Cryptopay\verify_webhook.

Descargar Cryptopay.php ↓

Python

Python 3.9+, solo la biblioteca estándar. CoineticClient, verify_webhook.

Descargar cryptopay.py ↓

Go

Go 1.22+, solo la biblioteca estándar. Paquete cryptopayclient.

Descargar cryptopay.go ↓

Qué incluyen

Función	Node.js	PHP	Python	Go
Firmar una solicitud	`signRequest`	`sign_request`	`sign_request`	`SignRequest`
Crear una factura	`createInvoice`	`createInvoice`	`create_invoice`	`CreateInvoice`
Consultar una factura	`getInvoice`	`getInvoice`	`get_invoice`	`GetInvoice`
Verificar un webhook	`verifyWebhook`	`verify_webhook`	`verify_webhook`	`VerifyWebhook`
Estados que permiten entregar	`PAID_STATUSES`	`PAID_STATUSES`	`PAID_STATUSES`	`PaidStatuses`

Los nombres técnicos de archivos y clases (cryptopay.*, CryptopayClient) son históricos y no cambian; en Node.js y Python existen los alias CoineticClient y CoineticError.

Los cuatro, verificados con las mismas referencias

Las firmas de solicitudes y webhooks de todos los clientes coinciden con los valores de referencia. Si escribe un cliente en otro lenguaje, consiga primero que coincida con ellos: es la forma más rápida de encontrar un error en la firma.

Flujo mínimo

pseudocódigo

invoice = client.createInvoice({order_id, price_amount: "3.00", price_currency: "USD",
                                return_url: "https://shop.example/orders/42"},
                               idempotencyKey = "order-42")
redirect(invoice.checkout_url)

on POST /webhooks/coinetic (raw body!):
    event = verifyWebhook(WEBHOOK_SECRET, headers, rawBody)   # si no, 400/401
    if seen(event.id): return 200                             # entrega repetida
    inv = client.getInvoice(event.data.invoice_id)            # nueva comprobación
    if inv.status in PAID_STATUSES: grantOnce(inv.order_id)
    return 200

Qué no hacen los clientes

No guardan secretos: la clave y el secreto se pasan desde fuera, desde variables de entorno o un gestor de secretos.
No guardan los X-Webhook-Id procesados: eso corresponde a su base de datos.
No convierten los importes en números: todos los importes son cadenas.
No reintentan las solicitudes por su cuenta: reintente con el mismo Idempotency-Key ante 429, 5xx y errores de red.
No funcionan en el navegador ni en apps móviles, solo en el servidor: ahí es donde reside el secreto.