Integración API RiskPayGo

Esta documentación explica cómo integrar RiskPayGo en tu web o aplicación para crear pagos, redirigir al comprador al checkout correcto y recibir la confirmación final del estado mediante webhook.

La integración debe realizarse desde tu backend. No se recomienda exponer credenciales ni lógica sensible en frontend.

Antes de empezar

Antes de comenzar, necesitas tener una cuenta de merchant aprobada y activa en RiskPayGo. También debes contar con tus credenciales de integración y asegurarte de que el dominio desde el que vas a cobrar esté aprobado dentro de tu cuenta.

Los datos que necesitarás son tu Merchant ID, tu API Token, tu Webhook Secret y la URL base de la API.

La URL base es la siguiente:

https://riskpaygo.com/portal/api/plugin

Autenticación

Todas las peticiones a la API deben enviarse autenticadas. Para ello, debes incluir el token privado en la cabecera Authorization y el identificador del merchant en la cabecera X-RPG-Merchant.

Las cabeceras necesarias son estas:

Accept: application/json
Content-Type: application/json
Authorization: Bearer TU_API_TOKEN
X-RPG-Merchant: TU_MERCHANT_ID

Estas credenciales deben usarse únicamente en servidor. No deben quedar visibles en JavaScript del navegador ni en código público.

Dominio aprobado

RiskPayGo valida el dominio que envías en el campo site.url. Esto significa que no basta con tener unas credenciales válidas: el dominio desde el que estás creando el cobro también debe estar registrado y aprobado en tu cuenta.

Si el dominio no coincide con uno de tus proyectos aprobados, la API rechazará la petición aunque el token sea correcto.

Por eso, antes de pasar a producción, conviene comprobar que la URL exacta de tu tienda o aplicación está dada de alta en el panel.

Cómo funciona la selección del checkout

RiskPayGo trabaja con dos checkout distintos según el país del comprador:

  • Si el país enviado en customer.country es US o CA, el comprador será enviado al checkout de USA/Canada.
  • Si el país es cualquier otro, el comprador será enviado al checkout internacional.

No necesitas enviar un campo adicional para elegir manualmente el checkout. La selección se realiza automáticamente usando el valor de customer.country.

Por eso es importante que el país del comprador se envíe correctamente en cada solicitud.

Crear un pago

Para iniciar un cobro debes hacer una petición POST al endpoint de creación de pagos.

POST https://riskpaygo.com/portal/api/plugin/payments/create

En esa petición debes enviar la información principal del pedido: el importe, la divisa, tus referencias internas, los datos básicos del comprador y las URLs de retorno y notificación.

Una petición típica incluirá campos como merchant_order_id, order_id, order_key, amount, currency, customer, site, notify_url, return_url y cancel_url.

Actualmente, en el bloque customer solo debes enviar estos datos del comprador:

  • first_name: nombre
  • last_name: apellidos
  • email: correo electrónico
  • country: país

Ya no es necesario enviar phone ni date_of_birth.

A continuación tienes un ejemplo completo del cuerpo que puedes enviar:

{
  "merchant_order_id": "PED-1001",
  "order_id": 1001,
  "order_key": "pedido_1001_key",
  "amount": "149.99",
  "currency": "USD",
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Nombre",
    "last_name": "Apellido",
    "country": "US"
  },
  "site": {
    "url": "https://tu-dominio.com/",
    "name": "Mi tienda",
    "platform": "custom",
    "plugin": "integracion-propia"
  },
  "notify_url": "https://tu-dominio.com/api/riskpaygo/webhook",
  "return_url": "https://tu-dominio.com/pago/completado",
  "cancel_url": "https://tu-dominio.com/pago/cancelado"
}

Ten en cuenta lo siguiente:

  • El campo amount debe ser mayor que cero.
  • La divisa se envía en currency.
  • En customer es obligatorio enviar first_name, last_name, email y country.
  • El valor de customer.country es el que determina qué checkout se mostrará al comprador.
  • En site.url debes enviar un dominio previamente aprobado en tu cuenta.
  • En notify_url indicas la URL en la que quieres recibir la confirmación del estado del pago.

Ejemplos de comportamiento por país

Si envías un país de USA/Canada:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "John",
    "last_name": "Smith",
    "country": "US"
  }
}

El comprador será dirigido al checkout de USA/Canada.

Si envías un país distinto:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Carlos",
    "last_name": "García",
    "country": "ES"
  }
}

El comprador será dirigido al checkout internacional.

Respuesta de la API

Si la solicitud es correcta, RiskPayGo devuelve una respuesta con la referencia interna del pago y la URL del checkout. Esa referencia te sirve para enlazar el cobro con tu pedido y para hacer seguimiento posterior.

La respuesta esperada tiene esta forma:

{
  "success": true,
  "data": {
    "payment_ref": "RPG-20260313-ABC12345",
    "checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260313-ABC12345",
    "fee_percent": 20,
    "plan_slug": "free"
  }
}

En cuanto recibas checkout_url, debes redirigir al comprador a esa dirección para que pueda completar el pago.

Aunque el checkout se seleccione según el país del comprador, para tu integración el flujo es el mismo: siempre debes usar la checkout_url devuelta por la API.

Qué hacer con el checkout

El pago se realiza en un checkout hospedado por RiskPayGo. Tu sistema no debe considerar el pedido como pagado únicamente por haber obtenido la URL del checkout o porque el usuario haya regresado a la web.

Lo recomendable es seguir este flujo:

  1. Crear el pago desde tu backend.
  2. Guardar la referencia payment_ref en tu sistema.
  3. Redirigir al comprador a checkout_url.
  4. Esperar la confirmación definitiva mediante webhook.

La return_url sirve para devolver al usuario a tu sitio después del pago, pero el estado final debe basarse siempre en la notificación que recibas en notify_url.

Webhook de confirmación

Cuando el estado del pago cambie, RiskPayGo enviará una petición POST a la URL indicada en notify_url. Esa notificación incluye una firma en la cabecera X-RPG-Signature.

Debes validar esa firma utilizando tu Webhook Secret. La validación debe hacerse sobre el cuerpo original exacto de la petición, no sobre un JSON reserializado.

La cabecera que debes comprobar es esta:

X-RPG-Signature: <firma_base64_hmac_sha256>

La notificación de RiskPayGo puede incluir información como el merchant, la referencia del pedido, la referencia del pago, el estado y el identificador de transacción. Un ejemplo sería este:

{
  "merchant_id": "TU_MERCHANT_ID",
  "order_id": 1001,
  "order_key": "pedido_1001_key",
  "payment_ref": "RPG-20260313-ABC12345",
  "transaction_id": "RPG-20260313-ABC12345",
  "status": "paid",
  "provider_status": "success",
  "provider_event": "payment_succeeded",
  "source": "payera_webhook"
}

Lo importante aquí es que:

  • Primero valides la firma.
  • Después compruebes el valor de status.
  • Y finalmente actualices el pedido en tu sistema con ese estado.

No debes marcar un pedido como pagado solamente porque el usuario volvió a la web o porque llegó a la página de éxito. La fuente principal de verdad debe ser el webhook.

Estados del pago

Durante la integración debes contemplar cuatro estados principales:

  • pending: el pago ha sido iniciado pero todavía no está confirmado.
  • paid: el pago ha sido confirmado correctamente. Este es el estado con el que normalmente debes marcar el pedido como abonado.
  • failed: el pago ha fallado o ha sido rechazado.
  • cancelled: el pago ha sido cancelado o ha expirado.

La recomendación general es usar el webhook como fuente principal de verdad y considerar el pedido pagado solo cuando recibas status = paid.

Errores frecuentes

Merchant no autorizado

Si la API responde con un error de autorización, revisa estos puntos:

  • Que el valor enviado en Authorization sea correcto.
  • Que el valor enviado en X-RPG-Merchant coincida con ese token.
  • Que la cuenta del merchant esté aprobada y activa.

Dominio no aprobado

Si el problema está en el dominio, revisa el valor enviado en site.url y comprueba que ese dominio exista como proyecto aprobado dentro del panel de RiskPayGo.

País incorrecto o checkout no esperado

Si el comprador ve un checkout distinto del esperado, revisa el valor enviado en customer.country.

  • Si envías US o CA, se usará el checkout de USA/Canada.
  • Si envías cualquier otro país, se usará el checkout internacional.

Un valor de país incorrecto puede hacer que el comprador sea enviado al checkout equivocado.

Importe no válido

Si la API rechaza el importe, asegúrate de que amount se envía correctamente y tiene un valor mayor que cero.

Datos incompletos del comprador

Si la solicitud falla por datos del cliente, verifica que en customer estés enviando al menos estos campos:

first_name
last_name
email
country

Recuerda que phone y date_of_birth ya no son necesarios en esta integración.

Firma de webhook inválida

Si tu sistema no consigue validar la notificación, revisa que estés usando el Webhook Secret correcto y que el cálculo de la firma se haga sobre el cuerpo original exacto de la petición.

Uso con WooCommerce

Si utilizas el plugin oficial de WooCommerce, los mismos datos de integración siguen siendo necesarios. Tendrás que configurar la URL base, el merchant, el token y el secreto del webhook.

Los valores principales a introducir son estos:

API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRET

La URL del webhook en WordPress suele tener esta forma:

https://tu-dominio.com/wp-json/riskpaygo/v1/webhook

Si el flujo del plugin utiliza el país del comprador para generar el pago, la selección entre checkout USA/Canada y checkout internacional seguirá la misma lógica descrita anteriormente.

Recomendaciones finales

Antes de pasar a producción, conviene verificar todo lo siguiente:

  • Que el dominio enviado en site.url está aprobado en RiskPayGo.
  • Que tu notify_url responde correctamente por HTTPS.
  • Que guardas payment_ref en tu sistema para poder relacionar el pago con el pedido.
  • Que envías correctamente customer.country, ya que ese valor decide qué checkout verá el comprador.
  • Que solo marcas los pedidos como pagados cuando llega la confirmación final por webhook con status = paid.

Con esta estructura ya tienes una base clara y segura para integrar RiskPayGo en una web propia, una aplicación personalizada o una tienda WooCommerce.

Scroll al inicio