Documentación / Integración

Página de pago

La página de pago la ponemos nosotros. Su servidor solo tiene que redirigir al cliente a ella mediante el checkout_url de la respuesta de creación de la factura.

Qué ve el cliente

El importe del pedido y el temporizador del plazo de la factura.
La elección de moneda: solo los activos de la factura disponibles en ese momento.
Tras elegir: el código QR, el importe exacto con un botón «Copiar», la dirección, el aviso de red y el enlace «Abrir en la billetera» (BIP21, EIP-681, Solana Pay, TRON).
El estado se actualiza solo: «Pago detectado» → «Confirmaciones 7/20» → «Pago recibido».
El botón «Volver a la tienda», que lleva a su return_url.

Mientras no se haya pagado nada, el cliente puede cambiar de moneda. Tras el primer pago, la moneda queda fijada. Para un activo volátil corre el temporizador del tipo de cambio (20 minutos); cuando vence, el importe y la dirección se ocultan.

La página está en ruso e inglés, con tema claro u oscuro según la configuración del dispositivo.

Cómo abrirla

Dónde	Cómo
Web	Navegación en la misma pestaña: `303 See Other` desde su servidor o `location.href`
iOS	`ASWebAuthenticationSession` o `SFSafariViewController`
Android	Chrome Custom Tabs (`androidx.browser`)
Bot de Telegram	Botón inline con un enlace a `checkout_url`
No utilizar	`iframe`, `WKWebView`, `WebView`: no hay barra de direcciones (el phishing es indistinguible) y los enlaces a billeteras no funcionan de forma fiable. La página prohíbe que se inserte en otras (`frame-ancestors 'none'`)

Apps móvilesLa app no llama directamente a la API de Coinetic ni guarda el secreto de la clave: se puede extraer de la compilación en minutos. Su servidor crea la factura a petición de la app y a esta solo le devuelve el checkout_url.

El regreso del cliente

El cliente puede volver antes de pagar, durante las confirmaciones o no volver nunca. La página del pedido no debe depender de ello.
En return_url puede incluir el número de pedido, pero tome el estado de su propia base de datos, que actualiza el webhook. Si el pedido aún no figura como pagado, vuelva a consultar GET /v1/invoices/{id}.
Para apps, pase un enlace universal (Universal Links / App Links): https://shop.example/app/orders/ORDER-1001. No se aceptan esquemas propios (myapp://).

Situaciones habituales

Situación	Qué hacer
El cliente cerró la pestaña	Ofrezca en el pedido un enlace «Ir al pago» a `checkout_url`: la factura es válida hasta `expires_at`
La factura venció	Una factura nueva con un `order_id` nuevo (por ejemplo, `ORDER-1001-2`) y un `Idempotency-Key` nuevo
Pago insuficiente	«Pague el resto a la misma dirección»: la página de pago muestra el importe pendiente
Pago fuera de plazo	El dinero se ha recibido y la decisión es suya: entregar el pedido o tramitar un reembolso
Verificación AML	Informe al cliente de que el pago está en revisión y espere a `invoice.paid`