Cómo integrar una pasarela de pagos cripto White Label con OxaPay

Integrar una pasarela de pagos cripto White Label no consiste únicamente en conectarse a una API. Significa añadir un flujo completo de pagos cripto a tu sitio web o aplicación manteniendo el control de la experiencia del cliente.

Con OxaPay White Label, tu empresa puede mostrar la dirección de pago, el código QR, el importe, la red y el estado del pago dentro de su propia interfaz. Mientras tanto, OxaPay gestiona la infraestructura de pago subyacente, incluida la generación del pago, el monitoreo de la blockchainy las actualizaciones de la transacción.

Este enfoque permite a las empresas ofrecer pagos con criptomonedas bajo su propia marca sin construir ni mantener internamente una infraestructura de pagos blockchain.

En esta guía explicamos cómo integrar la pasarela White Label de OxaPay, qué necesita tu empresa antes de comenzar y qué situaciones de pago deben tenerse en cuenta antes de pasar a producción.

¿White Label es adecuado para tu empresa?

Antes de comenzar la integración, es importante decidir si una solución White Label es la opción adecuada para tu flujo de pago.

Una página de pago cripto alojada suele ser suficiente para empresas que quieren empezar a aceptar criptomonedas rápidamente. En este modelo, los clientes son redirigidos a una página de pago proporcionada por la pasarela para completar la transacción.

White Label es más adecuado cuando la experiencia de pago es una parte importante de tu producto o del recorrido del cliente. En lugar de redirigir a los clientes a una página de pago externa, muestras la información de pago dentro de tu propio sitio web, aplicación, plataforma o checkout.

Esta solución es especialmente útil para empresas que quieren:

• mantener una identidad de marca coherente durante todo el checkout
• mantener a los clientes dentro de su propia plataforma
• controlar cómo se muestran las instrucciones y los estados de pago
• conectar los pagos cripto con su proceso de pedidos existente
• evitar construir desde cero una infraestructura de pagos blockchain

La principal diferencia es el nivel de control. Tu empresa gestiona la experiencia de cara al cliente, mientras que OxaPay gestiona la infraestructura de pago que hay detrás.

Qué necesitas antes de empezar

Una integración White Label requiere cierta preparación, pero tu empresa no necesita operar nodos blockchain ni construir su propio sistema de monitoreo de transacciones.

Tu sitio web o aplicación debe contar con un backend que pueda comunicarse de forma segura con la API de OxaPay, almacenar la información de pago y vincular cada pago con el pedido correcto.

También necesitas un endpoint de callback que pueda recibir actualizaciones de pago de OxaPay. Estas actualizaciones permiten que tu sistema sepa cuándo un cliente ha empezado a pagar y cuándo se ha completado el pago.

Por último, tu interfaz de pago debe poder mostrar información esencial como:

• el importe del pago
• la criptomoneda seleccionada
• la red blockchain
• la dirección de pago
• el código QR
• el tiempo de pago restante
• el estado de pago más reciente

La interfaz debe mostrar estos datos con claridad, especialmente la red seleccionada y el tiempo de expiración, porque los errores en estos puntos pueden provocar problemas de pago.

Integración de una pasarela de pagos cripto White Label con OxaPay

1. Crea una cuenta Merchant de OxaPay

El primer paso es crear una cuenta de OxaPay y acceder al panel para merchants.

Desde el panel puedes gestionar tu Merchant API Key, la configuración de pagos, las monedas compatibles, los registros de transacciones y otras herramientas para merchants.

En esta etapa preparas tu cuenta comercial para comunicarse con OxaPay. No necesitas crear wallets blockchain individuales para cada pedido ni desarrollar tu propio sistema de monitoreo de transacciones.

2. Genera tu Merchant API Key

A continuación, genera una Merchant API Key desde tu cuenta de OxaPay.

Esta clave permite que tu sistema autentique las solicitudes de pago enviadas a la API de OxaPay. Siempre debe almacenarse de forma segura en tu servidor backend.

La Merchant API Key no debe colocarse en código frontend, repositorios públicos, scripts del navegador ni en ningún otro lugar al que puedan acceder los clientes.

Tu backend debe utilizar la clave al crear solicitudes de pago White Label. El frontend solo debe recibir la información de pago que necesita mostrar al cliente.

3. Crea una solicitud de pago White Label

Para generar un pago White Label, tu sistema envía una solicitud al siguiente endpoint:

POST https://api.oxapay.com/v1/payment/white-label

Los dos campos de pago obligatorios son:

• Importe: el valor del pago
• pay_currency: la criptomoneda utilizada para el pago

Se pueden añadir otros campos según tu flujo de pago.

Por ejemplo:

• divisa define la moneda utilizada para fijar el precio del pedido, como USD.
• Red selecciona la red blockchain cuando la criptomoneda está disponible en varias redes.
• order_id conecta el pago con un pedido de tu propio sistema.
• callback_url indica a OxaPay dónde debe enviar las actualizaciones de pago.
• toda la vida define durante cuánto tiempo permanece válido el pago.
• cobertura_mal_pagada define la diferencia aceptable entre el importe solicitado y el recibido.

La divisa, Red, order_id, y callback_url son opcionales en la API. Sin embargo, se recomienda encarecidamente utilizar un ID de pedido y una URL de callback para las empresas que necesitan un seguimiento fiable de los pedidos.

Cuando la solicitud se realiza correctamente, OxaPay crea una sesión de pago y devuelve la información que tu sistema necesita para presentar el pago.

4. Recibe la información de pago y muéstrala

Después de crear la solicitud de pago, OxaPay devuelve información de pago estructurada.

Puede incluir:

• un track_id
• el importe exacto del pago
• la criptomoneda del pago
• la red blockchain
• la dirección de pago
• un código QR
• el tiempo de expiración

Tu sistema debe almacenar el track_id y vincularlo con el pedido interno correcto. Este identificador ayuda a tu empresa a seguir el pago e investigarlo más adelante cuando sea necesario.

Tu frontend puede utilizar después la información devuelta para crear una página de pago con tu propia marca.

El cliente debe poder:

• escanear el código QR
• copiar la dirección de pago
• copiar el importe exacto
• ver la criptomoneda y la red requeridas
• comprobar cuánto tiempo queda
• seguir el estado actual del pago

Esta es la principal ventaja del modelo White Label. El cliente completa el pago dentro de una experiencia diseñada y personalizada con la marca de tu empresa.

La página de pago también debe advertir a los clientes que no envíen fondos después de que el pago haya expirado. Según la documentación de OxaPay, las direcciones White Label generadas solo son válidas durante el tiempo de vida especificado para el pago.

5. Sigue el estado del pago

Cuando el cliente envía la criptomoneda, OxaPay monitorea el pago e informa de su progreso.

Estados de pago de OxaPay pueden incluir estados como:

• esperando el pago
• pago en curso
• paid
• underpaid
• expired
• aceptado manualmente
• refunded

Tu empresa no necesita mostrar todos los estados internos al cliente. La interfaz puede convertirlos en mensajes sencillos como «Esperando el pago», «Pago detectado», «Pago completado» o «Pago expirado».

Lo importante es que tu sistema no complete el pedido demasiado pronto.

OxaPay envía una actualización paying cuando se ha detectado actividad de pago. Normalmente, tu sistema debe esperar al estado final paid antes de entregar el producto, activar el servicio o marcar el pedido como completado.

6. Recibe y valida las actualizaciones de pago

OxaPay envía las actualizaciones de pago al callback_url incluido en la solicitud de pago.

Estas notificaciones permiten que tu sistema:

• identifique el pago relacionado
• actualice el estado interno del pedido
• informe al cliente sobre el progreso
• complete el pedido después de un pago correcto

Como el endpoint de callback es accesible públicamente, tu sistema debe validar las notificaciones entrantes antes de realizar cualquier acción.

OxaPay proporciona una firma de seguridad con sus callbacks. Tu equipo técnico debe verificar esta firma y confirmar que la información del pago coincide con los datos del pedido almacenado.

Esto no tiene que ser visible para el cliente, pero es una parte importante de la protección del proceso de pago.

Tu sistema también debe estar preparado para recibir la misma actualización más de una vez. Un callback repetido no debe provocar una entrega duplicada del producto, un abono repetido de saldo ni múltiples confirmaciones del pedido.

OxaPay puede volver a intentar un callback cuando tu sistema no confirma correctamente que lo ha recibido.

Gestión de pagos insuficientes

A veces, un cliente puede enviar menos que el importe de pago solicitado.

OxaPay ofrece una opción de tolerancia de pago insuficiente que permite al merchant definir una diferencia aceptable entre los importes esperado y recibido.

Si la diferencia está dentro del rango aceptado, el pago puede continuar según la política configurada. Si el importe está por debajo del umbral aceptado, el pago puede requerir otra acción.

Según tu modelo de negocio, puedes:

• pedir al cliente que complete el importe restante
• revisar el pago manualmente
• aceptar el pago según una política interna
• cancelar o reembolsar el pedido cuando corresponda

Los pagos insuficientes no deben tratarse automáticamente del mismo modo que los pagos fallidos. Deben seguir un proceso claro para que los clientes y los equipos de soporte sepan qué ocurrirá después.

7. Prueba el flujo de pago completo

Antes de lanzar la integración, prueba el recorrido completo del cliente desde la creación del pago hasta la finalización del pedido.

Las pruebas deben incluir:

• creación correcta del pago
• visualización correcta de la dirección y el código QR
• información precisa sobre el importe del pago y la red
• actualizaciones del estado de pago
• finalización correcta del pedido
• pagos expirados
• situaciones de pago insuficiente
• notificaciones de pago repetidas
• actualizaciones de pago retrasadas

También debes comprobar cómo funciona la página de pago en dispositivos móviles. Muchos clientes escanearán el código QR desde otro dispositivo o copiarán la dirección directamente en una wallet móvil.

Probar únicamente la solicitud inicial a la API no es suficiente. El proceso completo del pedido, incluidas las actualizaciones de pago y el fulfillment, debe funcionar de forma fiable antes de poner la integración a disposición de los clientes.

Consideraciones importantes de integración

Una experiencia de pago White Label fiable depende de algunos detalles prácticos.

Gestión de la expiración

Cuando un pago expira, tu sistema debe dejar de mostrarlo como activo. El cliente debe tener la opción de crear una nueva solicitud de pago en lugar de seguir utilizando la información del pago expirado.

Selección correcta de la red

Si una criptomoneda es compatible con más de una red, muestra claramente la red seleccionada.

Un cliente que envía fondos por la red equivocada puede tener que contactar con soporte, y la recuperación no siempre es posible. Unas instrucciones claras pueden evitar muchos de estos errores.

Instrucciones de pago claras

Los clientes deben entender de inmediato:

• qué criptomoneda enviar
• qué red utilizar
• cuánto enviar
• dónde enviarlo
• durante cuánto tiempo permanece válido el pago
• qué ocurre después del pago

Una página de pago clara reduce la confusión y crea una experiencia de checkout más fiable.

Flujo de integración White Label

El proceso completo puede resumirse en siete pasos:

1. Tu sistema crea un pedido interno.
2. Tu backend envía una solicitud de pago White Label a OxaPay.
3. OxaPay devuelve los detalles del pago.
4. Tu sitio web o aplicación muestra el pago dentro de su propia interfaz.
5. El cliente envía la criptomoneda solicitada.
6. OxaPay monitorea la transacción y envía actualizaciones de pago.
7. Tu sistema confirma el pago y completa el pedido.

Conclusión

Integrar la pasarela de pagos cripto White Label de OxaPay permite que una empresa controle su experiencia de pago sin construir la infraestructura blockchain subyacente por sí misma.

OxaPay gestiona la generación de pagos, el monitoreo de transacciones y las actualizaciones de pago. Tu empresa controla la marca, la interfaz del cliente, la gestión de pedidos y el fulfillment final.

La idea es sencilla: tu empresa controla la experiencia del cliente, mientras que OxaPay proporciona la infraestructura de pago que hay detrás.

Con una página de pago clara, un seguimiento fiable del estado y pruebas adecuadas, la integración White Label puede ofrecer a los clientes una experiencia de pago cripto coherente que permanezca totalmente conectada con tu sitio web o aplicación.