Integra RiskPayGo con el nuevo flujo Premium.
Esta guía explica cómo crear pagos por API, qué datos completos del comprador debes enviar y cómo funciona la ruta Premium con FTD para los dos primeros depósitos pagados del mismo cliente y Trusted desde el tercer depósito.
Integración directa
Usa la API desde WooCommerce, Laravel, PHP, Node.js o cualquier sistema propio capaz de enviar peticiones HTTPS.
Checkout alojado
Tu web crea el pago y RiskPayGo devuelve un checkout_url. El comprador se redirige a esa URL para completar el pago.
Webhooks firmados
RiskPayGo firma las notificaciones con HMAC SHA-256 para que puedas verificar que el evento es legítimo.
1. Credenciales necesarias
Entra en tu panel de RiskPayGo y abre la pestaña API. Allí encontrarás los datos que debes copiar en tu integración.
API Base URLURL base para las peticiones. En producción suele ser https://riskpaygo.com/portal/api/plugin.Merchant IDIdentificador de tu comercio. Se envía en la cabecera X-RPG-Merchant.API TokenToken privado de autorización. Se envía como Authorization: Bearer TU_API_TOKEN.Webhook SecretClave usada para comprobar la cabecera X-RPG-Signature de las notificaciones entrantes.API Token ni el Webhook Secret en JavaScript público del navegador. Deben quedar en tu servidor, plugin o backend.2. Flujo recomendado de cobro
La integración PRO crea el pago desde tu servidor, valida los datos del comprador, redirige al checkout seguro y confirma el resultado mediante webhook.
4. Datos obligatorios del comprador
Para que el checkout pueda iniciarse correctamente, envía siempre el objeto customer y el objeto customer_details. El teléfono debe ir con código de país separado por espacio, sin símbolo +.
Objeto customer
customer.first_nameNombre del comprador.customer.last_nameApellido del comprador.customer.emailEmail válido del comprador. Este dato ayuda a aplicar FTD/Trusted por cliente.customer.phoneTeléfono en formato 34 600111222, sin +.customer.countryPaís ISO 2 letras, por ejemplo ES, FR o MX.customer.date_of_birthFecha de nacimiento en formato YYYY-MM-DD.Objeto customer_details
customer_details.first_nameNombre del comprador.customer_details.last_nameApellido del comprador.customer_details.address_line1Dirección principal. Ejemplo: 10 Nueva Strada.customer_details.cityCiudad. Ejemplo: Barcelona.customer_details.postal_codeCódigo postal. Ejemplo: 12345.customer_details.country_of_residencePaís de residencia ISO 2 letras. Ejemplo: ES.customer_details.state_of_residenceProvincia, estado o región. Ejemplo: Sevilla.customer_details.phoneTeléfono en formato <prefijo país> <número>. Ejemplo: 34 600111222.customer_details.date_of_birthFecha de nacimiento en formato YYYY-MM-DD.34 600111222, 357 99123456 o equivalente. No uses +34600111222 ni 0034600111222 en customer_details.phone.5. Límites y países bloqueados en Premium
RiskPayGo aplica las reglas de importe y país antes de iniciar el checkout. Si el país no está permitido, la compra no se podrá gestionar.
FTD
Importe mínimo: 10 EUR/USD
Importe máximo: 500 EUR/USD
Uso: primeras 2 transacciones pagadas del mismo comprador.
Trusted
Importe mínimo: 10 EUR/USD
Importe máximo: 2.820 EUR/USD
Uso: tercera transacción pagada y siguientes del mismo comprador.
El país desde donde intenta pagar está bloqueado y no podemos gestionar esta compra.
| Ruta | Países bloqueados |
|---|---|
| FTD | Afganistán, Azerbaiyán, Bielorrusia, Bosnia, Burundi, República Centroafricana, Congo, Egipto, Guinea, Guinea-Bissau, India, Irán, Irak, Israel, Japón, Kazajistán, Líbano, Libia, Malí, Mauricio, Myanmar, Nicaragua, Corea del Norte, Pakistán, Rusia, Somalia, Sudán del Sur, Sudán, Siria, Turquía, Emiratos Árabes Unidos, Reino Unido, EE. UU., Venezuela, Yemen y Zimbabue. |
| Trusted | Afganistán, Bielorrusia, República Centroafricana, China, Congo, República Democrática del Congo, Cuba, Haití, Hong Kong, Irán, Irak, Japón, Malí, Myanmar, Rusia, Somalia, Sudán del Sur, Sudán, Siria, Turquía, Emiratos Árabes Unidos, Ucrania, EE. UU., Venezuela, Yemen y Zimbabue. |
6. Comprobar conexión con ping
Este endpoint sirve para comprobar que las credenciales son correctas y que la cuenta está usando el perfil API PRO.
curl -X GET 'https://riskpaygo.com/portal/api/plugin/ping' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer TU_API_TOKEN' \
-H 'X-RPG-Merchant: TU_MERCHANT_ID'
{
"success": true,
"merchant_id": "mer_xxxxxxxx",
"api_profile": "pro",
"account_status": "approved",
"currency": "USD",
"required_customer_fields": [
"customer.first_name",
"customer.last_name",
"customer.email",
"customer.phone",
"customer.country",
"customer.date_of_birth",
"customer_details.first_name",
"customer_details.last_name",
"customer_details.address_line1",
"customer_details.city",
"customer_details.postal_code",
"customer_details.country_of_residence",
"customer_details.state_of_residence",
"customer_details.phone",
"customer_details.date_of_birth"
]
}
7. Crear un pago
Envía una petición POST con el pedido y los datos completos del comprador. No envíes un checkout manual: RiskPayGo decide internamente si corresponde FTD o Trusted.
Campos base obligatorios
merchant_order_idID único del pedido en tu sistema.amountImporte del pedido. Debe respetar los límites de la ruta FTD/Trusted que corresponda al comprador.currencyUsa USD o EUR según la moneda aprobada para tu cuenta.site.urlDominio de la tienda o web aprobada en RiskPayGo.Campos recomendados
notify_urlURL donde recibirás el webhook de confirmación.return_urlURL para volver después de un pago completado.cancel_urlURL para volver si el comprador cancela.site.platformEjemplo: woocommerce, shopify, custom.curl -X POST 'https://riskpaygo.com/portal/api/plugin/payments/create' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TU_API_TOKEN' \
-H 'X-RPG-Merchant: TU_MERCHANT_ID' \
-d '{
"merchant_order_id": "PED-1001",
"order_id": 1001,
"order_key": "wc_order_abc123",
"amount": "149.99",
"currency": "USD",
"customer": {
"first_name": "Jane",
"last_name": "Doe",
"email": "cliente@ejemplo.com",
"phone": "34 600111222",
"country": "ES",
"date_of_birth": "1990-05-12"
},
"customer_details": {
"first_name": "Jane",
"last_name": "Doe",
"address_line1": "10 Nueva Strada",
"city": "Barcelona",
"postal_code": "12345",
"country_of_residence": "ES",
"state_of_residence": "Sevilla",
"phone": "34 600111222",
"date_of_birth": "1990-05-12"
},
"site": {
"url": "https://tu-dominio.com/",
"name": "Mi tienda",
"platform": "woocommerce",
"plugin": "riskpaygo-wc"
},
"notify_url": "https://tu-dominio.com/wp-json/riskpaygo/v1/webhook",
"return_url": "https://tu-dominio.com/pago/completado",
"cancel_url": "https://tu-dominio.com/pago/cancelado"
}'
$payload = [
'merchant_order_id' => 'PED-1001',
'amount' => '149.99',
'currency' => 'USD',
'customer' => [
'first_name' => 'Jane',
'last_name' => 'Doe',
'email' => 'cliente@ejemplo.com',
'phone' => '34 600111222',
'country' => 'ES',
'date_of_birth' => '1990-05-12',
],
'customer_details' => [
'first_name' => 'Jane',
'last_name' => 'Doe',
'address_line1' => '10 Nueva Strada',
'city' => 'Barcelona',
'postal_code' => '12345',
'country_of_residence' => 'ES',
'state_of_residence' => 'Sevilla',
'phone' => '34 600111222',
'date_of_birth' => '1990-05-12',
],
'site' => [
'url' => 'https://tu-dominio.com/',
'name' => 'Mi tienda',
'platform' => 'woocommerce',
],
'notify_url' => 'https://tu-dominio.com/wp-json/riskpaygo/v1/webhook',
'return_url' => 'https://tu-dominio.com/pago/completado',
'cancel_url' => 'https://tu-dominio.com/pago/cancelado',
];
$ch = curl_init('https://riskpaygo.com/portal/api/plugin/payments/create');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Accept: application/json',
'Content-Type: application/json',
'Authorization: Bearer TU_API_TOKEN',
'X-RPG-Merchant: TU_MERCHANT_ID',
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (!empty($data['success']) && !empty($data['data']['checkout_url'])) {
header('Location: ' . $data['data']['checkout_url']);
exit;
}
const response = await fetch('https://riskpaygo.com/portal/api/plugin/payments/create', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': 'Bearer TU_API_TOKEN',
'X-RPG-Merchant': 'TU_MERCHANT_ID'
},
body: JSON.stringify({
merchant_order_id: 'PED-1001',
amount: '149.99',
currency: 'USD',
customer: {
first_name: 'Jane',
last_name: 'Doe',
email: 'cliente@ejemplo.com',
phone: '34 600111222',
country: 'ES',
date_of_birth: '1990-05-12'
},
customer_details: {
first_name: 'Jane',
last_name: 'Doe',
address_line1: '10 Nueva Strada',
city: 'Barcelona',
postal_code: '12345',
country_of_residence: 'ES',
state_of_residence: 'Sevilla',
phone: '34 600111222',
date_of_birth: '1990-05-12'
},
site: {
url: 'https://tu-dominio.com/',
name: 'Mi tienda',
platform: 'custom'
},
notify_url: 'https://tu-dominio.com/webhook/riskpaygo',
return_url: 'https://tu-dominio.com/pago/completado',
cancel_url: 'https://tu-dominio.com/pago/cancelado'
})
});
const data = await response.json();
if (data.success && data.data.checkout_url) {
window.location.href = data.data.checkout_url;
}
8. Respuesta esperada
Si el pago se crea correctamente, RiskPayGo devolverá una referencia interna y la URL de checkout.
{
"success": true,
"data": {
"payment_ref": "RPG-20260703-ABC12345",
"checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260703-ABC12345",
"fee_percent": 15,
"checkout_flow": "secure_checkout",
"status": "pending"
}
}
9. Validar webhooks
Cuando el estado del pago cambie, RiskPayGo enviará una notificación a tu notify_url. Valida siempre la firma antes de marcar un pedido como pagado.
X-RPG-SignatureFirma HMAC SHA-256 calculada con tu Webhook Secret.payment_refReferencia interna devuelta al crear el pago.merchant_order_idID del pedido en tu sistema.statusEstado habitual: pending, paid, failed o cancelled.$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RPG_SIGNATURE'] ?? '';
$secret = 'TU_WEBHOOK_SECRET';
$expected = hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('invalid signature');
}
$event = json_decode($rawBody, true);
if (($event['status'] ?? '') === 'paid') {
// Marca el pedido como pagado usando merchant_order_id o payment_ref.
}
http_response_code(200);
echo 'ok';
import crypto from 'crypto';
function validateRiskPayGoWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature || '')
);
}
payment_ref o transaction_id, no dupliques el pedido ni el saldo.10. Errores frecuentes y cómo resolverlos
| Código | Mensaje habitual | Solución |
|---|---|---|
403 | Merchant no autorizado | Revisa Merchant ID, API Token y cabecera Authorization: Bearer. |
403 | Dominio no aprobado | Añade el dominio en Proyectos y espera aprobación antes de vender en real. |
422 | Datos del comprador incompletos | Envía todos los campos de customer y customer_details, incluyendo dirección, ciudad y código postal. |
422 | customer_details.phone is required in '<country code> <number>' format | Envía el teléfono como 34 600111222, sin + y con espacio entre prefijo y número. |
422 | País bloqueado | El comprador está en un país restringido. Muestra: El país desde donde intenta pagar está bloqueado y no podemos gestionar esta compra. |
422 | Importe no permitido | FTD permite 10-500 EUR/USD. Trusted permite 10-2.820 EUR/USD. |
429 | Demasiados intentos o intervalo FTD | Espera unos minutos antes de volver a iniciar otro pago para el mismo comprador. |
500 | Error interno al crear la transacción | Reintenta y contacta con soporte si persiste, incluyendo hora, dominio y merchant_order_id. |
11. Buenas prácticas de seguridad
Protege tus claves
Guarda el API Token y el Webhook Secret en variables de entorno, ajustes privados del plugin o configuración segura del servidor.
Valida siempre el webhook
No marques pedidos como pagados solo porque llegue una petición a tu endpoint. Comprueba X-RPG-Signature.
Usa HTTPS
Tus URLs notify_url, return_url y cancel_url deben usar HTTPS en producción.
No muestres detalles internos
Al comprador solo debes mostrar el checkout seguro de RiskPayGo y mensajes claros. No expongas tokens, rutas internas ni credenciales.
12. Checklist antes de activar pagos reales
site.url aparece como proyecto aprobado en RiskPayGo.34 600111222, no como +34600111222./payments/create devuelve checkout_url y el comprador puede abrirla.status: paid.