Integra RiskPayGo en tu web y empieza a crear pagos seguros.
Esta guía explica la integración estándar: cómo usar tus credenciales, 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 que pueda enviar peticiones HTTPS.
Checkout alojado
Tu web crea el pago y RiskPayGo devuelve una checkout_url. El comprador se redirige a esa URL para pagar.
Firma de webhooks
RiskPayGo firma las notificaciones con HMAC SHA-256 para que puedas validar que el evento es legítimo.
1. Credenciales necesarias
Entra en tu panel de RiskPayGo y abre la pestaña API. Ahí verás los datos que debes copiar en tu integración.
API Base URLURL base para llamar a la API. En producción normalmente 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 SecretSecreto usado para verificar la firma X-RPG-Signature de las notificaciones entrantes.API Token ni el Webhook Secret en JavaScript público del navegador. Deben vivir en tu servidor, plugin o backend.2. Flujo recomendado de cobro
La integración estándar evita que tengas que construir una pantalla de pago completa. Tu sistema solo crea la operación y redirige al comprador.
/payments/create con tus credenciales.site.url pertenece a un proyecto aprobado.3. Comprobar conexión con ping
Este endpoint sirve para comprobar que las credenciales son correctas y que la cuenta está usando el perfil estándar.
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": "standard",
"account_status": "approved",
"currency": "USD",
"limits": {
"min_amount": 10,
"max_amount": null,
"max_label": "Sin límite"
},
"required_customer_fields": ["customer_name", "customer_email"]
}4. Crear un pago
Envía una petición POST con el pedido. Para API STANDAR, los datos mínimos del comprador son nombre y email.
Campos obligatorios
merchant_order_idID único del pedido en tu sistema.amountImporte en USD. Mínimo 10.00.currencyUsa USD.customer_nameNombre del comprador.customer_emailEmail válido del comprador.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.order_idID numérico o interno del pedido.order_keyClave interna del pedido si tu plataforma la usa.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_name": "Nombre Cliente",
"customer_email": "cliente@ejemplo.com",
"site": {"url": "https://tu-dominio.com/", "name": "Mi tienda", "platform": "custom"},
"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"
}'<?php
$apiBase = 'https://riskpaygo.com/portal/api/plugin';
$merchantId = 'TU_MERCHANT_ID';
$apiToken = 'TU_API_TOKEN';
$payload = [
'merchant_order_id' => 'PED-1001',
'order_id' => 1001,
'order_key' => 'wc_order_abc123',
'amount' => '149.99',
'currency' => 'USD',
'customer_name' => 'Nombre Cliente',
'customer_email' => 'cliente@ejemplo.com',
'site' => ['url' => 'https://tu-dominio.com/', 'name' => 'Mi tienda', 'platform' => 'custom'],
'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($apiBase . '/payments/create');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Accept: application/json','Content-Type: application/json','Authorization: Bearer ' . $apiToken,'X-RPG-Merchant: ' . $merchantId], CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES), CURLOPT_TIMEOUT => 30]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($error || $status >= 400) { throw new RuntimeException('Error creando pago: ' . ($error ?: $response)); }
$data = json_decode($response, true);
header('Location: ' . $data['data']['checkout_url']);
exit;const apiBase = 'https://riskpaygo.com/portal/api/plugin';
const merchantId = 'TU_MERCHANT_ID';
const apiToken = 'TU_API_TOKEN';
const payload = {
merchant_order_id: 'PED-1001', order_id: 1001, order_key: 'wc_order_abc123', amount: '149.99', currency: 'USD',
customer_name: 'Nombre Cliente', customer_email: 'cliente@ejemplo.com',
site: {url: 'https://tu-dominio.com/', name: 'Mi tienda', platform: 'custom'},
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'
};
const response = await fetch(`${apiBase}/payments/create`, {method: 'POST', headers: {'Accept':'application/json','Content-Type':'application/json','Authorization':`Bearer ${apiToken}`,'X-RPG-Merchant':merchantId}, body: JSON.stringify(payload)});
const data = await response.json();
if (!response.ok || !data.success) throw new Error(data.message || 'No se pudo crear el pago');
console.log(data.data.checkout_url);5. Respuesta de creación de pago
Cuando el pago se crea correctamente, RiskPayGo devuelve una referencia interna y una URL de checkout. Tu integración debe redirigir al comprador a checkout_url.
{
"success": true,
"data": {
"payment_ref": "RPG-20260621-ABC12345",
"checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260621-ABC12345",
"fee_percent": 20,
"plan_slug": "free",
"api_profile": "standard",
"language": "es"
}
}payment_ref asociado a tu pedido. Te servirá para conciliar el pago cuando llegue el webhook.6. Webhooks de confirmación
Cuando RiskPayGo confirma un cambio de estado, enviará una petición POST a tu notify_url. Tu endpoint debe responder con HTTP 200 cuando procese correctamente el evento.
Cabeceras recibidas
| Cabecera | Uso |
|---|---|
Content-Type | application/json |
X-RPG-Signature | Firma HMAC SHA-256 en base64 calculada sobre el cuerpo JSON sin modificar. |
Payload habitual
| Campo | Descripción |
|---|---|
merchant_id | Merchant ID de RiskPayGo. |
order_id | ID del pedido enviado por tu web. |
order_key | Clave del pedido si la enviaste. |
payment_ref | Referencia RiskPayGo. |
transaction_id | Referencia interna de la transacción. |
status | Estado final o actualizado. Por ejemplo: paid. |
{
"merchant_id": "mer_XXXXXXXX",
"order_id": 1001,
"order_key": "wc_order_abc123",
"payment_ref": "RPG-20260621-ABC12345",
"transaction_id": "TX-789456123",
"status": "paid",
"event": "payment_confirmed",
"source": "riskpaygo_checkout"
}<?php
$webhookSecret = 'TU_WEBHOOK_SECRET';
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RPG_SIGNATURE'] ?? '';
$expected = base64_encode(hash_hmac('sha256', $rawBody, $webhookSecret, true));
if (!hash_equals($expected, $signature)) { http_response_code(401); exit('invalid_signature'); }
$event = json_decode($rawBody, true);
if (!is_array($event)) { http_response_code(400); exit('invalid_json'); }
if (($event['status'] ?? '') === 'paid') {
// Busca tu pedido por order_id, order_key o payment_ref y márcalo como pagado una sola vez.
}
http_response_code(200);
echo 'ok';import crypto from 'crypto';
const webhookSecret = 'TU_WEBHOOK_SECRET';
export async function riskpaygoWebhook(req, res) {
const rawBody = req.rawBody;
const signature = req.headers['x-rpg-signature'] || '';
const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('base64');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) return res.status(401).send('invalid_signature');
const event = JSON.parse(rawBody.toString('utf8'));
if (event.status === 'paid') {
// Marca tu pedido como pagado de forma idempotente.
}
return res.status(200).send('ok');
}payment_ref o transaction_id, no dupliques el pedido ni el saldo.7. 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 | Importe no permitido | En API STANDAR el importe mínimo es 10 USD. |
422 | Email o nombre requerido | Envía customer_name y customer_email, o los equivalentes dentro de customer. |
500 | Error interno al crear la transacción | Reintenta y contacta con soporte si persiste, incluyendo hora, dominio y merchant_order_id. |
8. 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 de RiskPayGo y mensajes claros. No expongas tokens ni rutas internas.
9. Checklist antes de activar pagos reales
site.url aparece como proyecto aprobado en RiskPayGo./ping responde con success: true y muestra API STANDAR./payments/create devuelve checkout_url y el comprador puede abrirla.status: paid.