Esta documentación explica cómo integrar RiskPayGo en tu web o aplicación para crear pagos, redirigir al comprador al checkout 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/pluginAutenticació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_IDEstas 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.
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/createEn esa petición debes enviar la información principal del pedido: el importe, la divisa, tus referencias internas, los datos 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.
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",
"phone": "+34123456789",
"country": "ES",
"date_of_birth": "1990-05-20"
},
"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"
}El campo amount debe ser mayor que cero. La divisa se envía en currency. En customer conviene mandar, al menos, el email del comprador. En site.url debes enviar el dominio aprobado. En notify_url indicas dónde quieres recibir la notificación del estado del pago.
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.
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 guardar la referencia payment_ref, redirigir al comprador y esperar la confirmación definitiva por webhook.
La return_url sirve para devolver al usuario a tu sitio después del pago, pero el estado final debe basarse 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 valides la firma y, después, uses el valor de status para actualizar el pedido en tu sistema.
Estados del pago
Durante la integración debes contemplar cuatro estados principales.
pending indica que el pago ha sido iniciado pero todavía no está confirmado.
paid indica que el pago ha sido confirmado correctamente. Este es el estado con el que normalmente debes marcar el pedido como abonado.
failed indica que el pago ha fallado o ha sido rechazado.
cancelled indica que 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, lo primero que debes revisar es que el valor enviado en Authorization sea correcto y que el merchant enviado en X-RPG-Merchant coincida con ese token. También debes confirmar que la cuenta se encuentre 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.
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.
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_SECRETLa URL del webhook en WordPress suele tener esta forma:
https://tu-dominio.com/wp-json/riskpaygo/v1/webhookRecomendaciones finales
Antes de pasar a producción, conviene verificar que el dominio está aprobado, que tu notify_url responde correctamente por HTTPS, que guardas payment_ref en tu sistema y que solo marcas los pedidos como pagados cuando llega la confirmación final por webhook.
Con esta estructura ya tienes una base sólida para integrar RiskPayGo en una web propia, una aplicación personalizada o una tienda WooCommerce.