Integra RiskPayGo con datos completos del comprador.
Esta guía explica la integración PRO: cómo usar tus credenciales, qué datos debes enviar, cómo crear una transacción, cómo redirigir al comprador al checkout y cómo validar la notificación de pago en tu sistema.
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.
Firma de webhooks
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, redirige al comprador al checkout seguro y confirma el resultado mediante webhook.
/payments/create con tus credenciales.site.url pertenece a un proyecto aprobado.3. Datos obligatorios para API PRO
En API PRO debes enviar datos completos del comprador. El país debe ir en formato ISO de 2 letras, el teléfono en formato internacional y la fecha de nacimiento en formato YYYY-MM-DD.
Objeto customer
customer.first_nameNombre del comprador.customer.last_nameApellido del comprador.customer.emailEmail válido del comprador.customer.phoneTeléfono en formato internacional, por ejemplo +34600111222.customer.countryPaís ISO 2 letras, por ejemplo ES, US 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.country_of_residencePaís de residencia ISO 2 letras.customer_details.phoneTeléfono en formato internacional.customer_details.date_of_birthFecha de nacimiento en formato YYYY-MM-DD.customer_details.state_of_residenceObligatorio si el comprador es de Estados Unidos. Código de 2 letras, por ejemplo FL, CA o NY.customer_details.post_codeObligatorio si el comprador es de Estados Unidos. ZIP/postal code.customer_details.country_of_residence es US, envía siempre customer_details.state_of_residence y customer_details.post_code.4. Comprobar conexión con ping
Este endpoint sirve para comprobar que las credenciales son correctas y que la cuenta está usando el perfil 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.country_of_residence",
"customer_details.phone",
"customer_details.date_of_birth"
]
}
5. Crear un pago
Envía una petición POST con el pedido y los datos completos del comprador.
Campos base obligatorios
merchant_order_idID único del pedido en tu sistema.amountImporte en USD según los límites activos de tu cuenta PRO.currencyUsa USD.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": "Nombre",
"last_name": "Apellido",
"email": "cliente@ejemplo.com",
"phone": "+34600111222",
"country": "US",
"date_of_birth": "1990-05-20"
},
"customer_details": {
"first_name": "Nombre",
"last_name": "Apellido",
"country_of_residence": "US",
"state_of_residence": "FL",
"post_code": "33101",
"phone": "+34600111222",
"date_of_birth": "1990-05-20"
},
"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' => 'Nombre',
'last_name' => 'Apellido',
'email' => 'cliente@ejemplo.com',
'phone' => '+34600111222',
'country' => 'US',
'date_of_birth' => '1990-05-20',
],
'customer_details' => [
'first_name' => 'Nombre',
'last_name' => 'Apellido',
'country_of_residence' => 'US',
'state_of_residence' => 'FL',
'post_code' => '33101',
'phone' => '+34600111222',
'date_of_birth' => '1990-05-20',
],
'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: 'Nombre',
last_name: 'Apellido',
email: 'cliente@ejemplo.com',
phone: '+34600111222',
country: 'US',
date_of_birth: '1990-05-20'
},
customer_details: {
first_name: 'Nombre',
last_name: 'Apellido',
country_of_residence: 'US',
state_of_residence: 'FL',
post_code: '33101',
phone: '+34600111222',
date_of_birth: '1990-05-20'
},
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;
}
6. Respuesta esperada
Si el pago se crea correctamente, RiskPayGo devolverá una referencia interna y la URL de checkout.
{
"success": true,
"data": {
"payment_ref": "RPG-20260313-ABC12345",
"checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260313-ABC12345",
"fee_percent": 15,
"checkout_flow": "secure_checkout",
"status": "pending"
}
}
7. 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.8. 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 | En API PRO envía nombre, apellido, email, teléfono, país y fecha de nacimiento. |
422 | Faltan datos para comprador de Estados Unidos | Si el país es US, envía customer_details.state_of_residence y customer_details.post_code. |
422 | Importe no permitido | El importe debe respetar los límites activos de tu cuenta. |
500 | Error interno al crear la transacción | Reintenta y contacta con soporte si persiste, incluyendo hora, dominio y merchant_order_id. |
9. 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 ni rutas internas.
10. Checklist antes de activar pagos reales
site.url aparece como proyecto aprobado en RiskPayGo.customer_details./ping responde con success: true y muestra API PRO./payments/create devuelve checkout_url y el comprador puede abrirla.status: paid.