API PRO FTD / TrustedFTD / Trusted Datos completosFull customer data
Documentación actualizada para clientes API PRO

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.

2 pagos FTDpor cada comprador nuevo o sin historial pagado
3º pago TrustedRiskPayGo cambia automáticamente al cliente recurrente
Campos nuevosdirección, ciudad, código postal y teléfono con prefijo separado
🔌

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.
Importante: nunca expongas el 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.

Pedido creadoTu web crea el pedido con importe, divisa y datos del comprador.
Datos completosEnvías datos personales, dirección, país, teléfono y fecha de nacimiento.
Ruta automáticaRiskPayGo decide si el comprador va por FTD o por Trusted.
Checkout URLRiskPayGo devuelve una URL segura de pago.
WebhookTu web recibe la confirmación y actualiza el pedido.
No envíes checkout_id: en Premium los checkouts FTD/Trusted son internos de RiskPayGo. Tu integración solo debe enviar los datos del pedido y del comprador.

3. Nuevo sistema Premium: FTD y Trusted

El cambio de FTD a Trusted se calcula por comprador, no de forma global. El comprador se identifica principalmente por el email enviado en customer.email.

1

Primer depósito pagado

El primer pago aprobado de ese comprador usa la ruta FTD.

2

Segundo depósito pagado

El segundo pago aprobado del mismo comprador también usa FTD.

3

Tercer depósito y siguientes

Cuando ese comprador ya tenga 2 depósitos pagados, RiskPayGo lo envía automáticamente por Trusted.

Ejemplo: si Pedro paga dos pedidos correctamente, su tercer pedido y todos los siguientes irán por Trusted. Si llega Juan como comprador nuevo, Juan empieza de nuevo por FTD.
Intervalo FTD: para compradores que siguen en FTD, evita lanzar pagos aprobados demasiado seguidos. Debe respetarse un intervalo aproximado de 4 minutos entre transacciones aprobadas por tarjeta del mismo comprador.

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.
Formato de teléfono obligatorio: usa 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.

Mensaje al comprador cuando el país esté bloqueado:
El país desde donde intenta pagar está bloqueado y no podemos gestionar esta compra.
RutaPaíses bloqueados
FTDAfganistá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.
TrustedAfganistá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.

GEThttps://riskpaygo.com/portal/api/plugin/ping
Ejemplo cURL
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'
Respuesta orientativa
{
  "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.

POSThttps://riskpaygo.com/portal/api/plugin/payments/create

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.
Crear pago con cURL
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"
  }'
Crear pago con PHP
$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;
}
Crear pago con Node.js
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.

JSON de ejemplo
{
  "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"
  }
}
Nota: la URL de pago puede redirigir a la ruta FTD o Trusted según el historial del comprador. Tu sistema no tiene que decidirlo.

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.
Validación PHP
$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';
Validación Node.js
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 || '')
  );
}
Consejo: procesa los webhooks de forma idempotente. Si recibes dos veces el mismo payment_ref o transaction_id, no dupliques el pedido ni el saldo.

10. Errores frecuentes y cómo resolverlos

CódigoMensaje habitualSolución
403Merchant no autorizadoRevisa Merchant ID, API Token y cabecera Authorization: Bearer.
403Dominio no aprobadoAñade el dominio en Proyectos y espera aprobación antes de vender en real.
422Datos del comprador incompletosEnvía todos los campos de customer y customer_details, incluyendo dirección, ciudad y código postal.
422customer_details.phone is required in '<country code> <number>' formatEnvía el teléfono como 34 600111222, sin + y con espacio entre prefijo y número.
422País bloqueadoEl comprador está en un país restringido. Muestra: El país desde donde intenta pagar está bloqueado y no podemos gestionar esta compra.
422Importe no permitidoFTD permite 10-500 EUR/USD. Trusted permite 10-2.820 EUR/USD.
429Demasiados intentos o intervalo FTDEspera unos minutos antes de volver a iniciar otro pago para el mismo comprador.
500Error interno al crear la transacciónReintenta 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

Credenciales copiadasAPI Base URL, Merchant ID, API Token y Webhook Secret están configurados en tu servidor o plugin.
Dominio aprobadoLa URL enviada en site.url aparece como proyecto aprobado en RiskPayGo.
Datos completos enviadosEl comprador incluye nombre, apellido, email, teléfono, país, dirección, ciudad, código postal, provincia/estado y fecha de nacimiento.
Teléfono correctoEl teléfono se envía como 34 600111222, no como +34600111222.
País permitidoAntes de iniciar el pago, valida que el país no esté bloqueado para la ruta aplicable.
Sin checkout manualTu integración no envía IDs de checkout. RiskPayGo decide FTD o Trusted por historial pagado del comprador.
Pago de pruebaLa petición a /payments/create devuelve checkout_url y el comprador puede abrirla.
Webhook validadoTu web valida la firma y marca el pedido como pagado solo cuando recibe status: paid.
Listo: si todos los puntos están correctos, la integración PRO ya está preparada para operar con RiskPayGo.
Updated documentation for API PRO clients

Integrate RiskPayGo with the new Premium flow.

This guide explains how to create API payments, which full customer details are required and how Premium routing works: FTD for the first two paid deposits from the same customer, then Trusted from the third paid deposit onward.

2 FTD paymentsfor each new customer or customer with no paid history
3rd payment TrustedRiskPayGo switches returning customers automatically
New fieldsaddress, city, postal code and phone with separated country code
🔌

Direct integration

Use the API from WooCommerce, Laravel, PHP, Node.js or any custom system that can send HTTPS requests.

🧾

Hosted checkout

Your website creates the payment and RiskPayGo returns a checkout_url. The buyer is redirected to that URL to pay.

🔐

Signed webhooks

RiskPayGo signs notifications with HMAC SHA-256 so you can verify that the event is legitimate.

1. Required credentials

Log in to your RiskPayGo dashboard and open the API tab. You will find the details you need to copy into your integration.

API Base URLBase URL for API requests. In production it is usually https://riskpaygo.com/portal/api/plugin.
Merchant IDYour merchant identifier. Send it in the X-RPG-Merchant header.
API TokenPrivate authorization token. Send it as Authorization: Bearer YOUR_API_TOKEN.
Webhook SecretSecret used to verify the X-RPG-Signature header on incoming notifications.
Important: never expose the API Token or Webhook Secret in public browser JavaScript. They must remain on your server, plugin or backend.

2. Recommended payment flow

The PRO integration creates the payment from your server, validates customer details, redirects to secure checkout and confirms the result through a webhook.

Order createdYour website creates the order with amount, currency and buyer details.
Full detailsYou send personal details, address, country, phone and date of birth.
Automatic routeRiskPayGo decides whether the buyer goes through FTD or Trusted.
Checkout URLRiskPayGo returns a secure payment URL.
WebhookYour website receives confirmation and updates the order.
Do not send checkout_id: for Premium, FTD/Trusted checkout routing is handled internally by RiskPayGo. Your integration only sends order and customer data.

3. New Premium system: FTD and Trusted

The switch from FTD to Trusted is calculated per customer, not globally. The customer is mainly identified by the email sent in customer.email.

1

First paid deposit

The first approved payment from that buyer uses the FTD route.

2

Second paid deposit

The second approved payment from the same buyer also uses FTD.

3

Third deposit and onward

Once that buyer has 2 paid deposits, RiskPayGo automatically sends them through Trusted.

Example: if Pedro successfully pays two orders, his third order and all following orders will go through Trusted. If Juan arrives as a new buyer, Juan starts again with FTD.
FTD interval: for buyers still under FTD, avoid launching approved card payments too close together. Keep an approximate 4-minute interval between approved card transactions for the same buyer.

4. Required customer data

To start checkout correctly, always send both the customer object and the customer_details object. The phone number must include the country code separated by a space, without the + symbol.

customer object

customer.first_nameBuyer first name.
customer.last_nameBuyer last name.
customer.emailValid buyer email. This helps apply FTD/Trusted routing per customer.
customer.phonePhone in 34 600111222 format, without +.
customer.country2-letter ISO country, for example ES, FR or MX.
customer.date_of_birthDate of birth in YYYY-MM-DD format.

customer_details object

customer_details.first_nameBuyer first name.
customer_details.last_nameBuyer last name.
customer_details.address_line1Main address. Example: 10 Nueva Strada.
customer_details.cityCity. Example: Barcelona.
customer_details.postal_codePostal code. Example: 12345.
customer_details.country_of_residence2-letter ISO country of residence. Example: ES.
customer_details.state_of_residenceState, province or region. Example: Sevilla.
customer_details.phonePhone in <country code> <number> format. Example: 34 600111222.
customer_details.date_of_birthDate of birth in YYYY-MM-DD format.
Mandatory phone format: use 34 600111222, 357 99123456 or equivalent. Do not use +34600111222 or 0034600111222 in customer_details.phone.

5. Premium limits and blocked countries

RiskPayGo applies amount and country rules before starting checkout. If the country is not allowed, the purchase cannot be processed.

FTD

Minimum amount: 10 EUR/USD
Maximum amount: 500 EUR/USD
Use: first 2 paid transactions from the same buyer.

Trusted

Minimum amount: 10 EUR/USD
Maximum amount: 2,820 EUR/USD
Use: third paid transaction and onward from the same buyer.

Buyer message when the country is blocked:
The country you are trying to pay from is blocked and we cannot process this purchase.
RouteBlocked countries
FTDAfghanistan, Azerbaijan, Belarus, Bosnia, Burundi, Central African Republic, Congo, Egypt, Guinea, Guinea-Bissau, India, Iran, Iraq, Israel, Japan, Kazakhstan, Lebanon, Libya, Mali, Mauritius, Myanmar, Nicaragua, North Korea, Pakistan, Russia, Somalia, South Sudan, Sudan, Syria, Turkey, United Arab Emirates, United Kingdom, United States, Venezuela, Yemen and Zimbabwe.
TrustedAfghanistan, Belarus, Central African Republic, China, Congo, Democratic Republic of the Congo, Cuba, Haiti, Hong Kong, Iran, Iraq, Japan, Mali, Myanmar, Russia, Somalia, South Sudan, Sudan, Syria, Turkey, United Arab Emirates, Ukraine, United States, Venezuela, Yemen and Zimbabwe.

6. Check connection with ping

This endpoint checks that your credentials are correct and that the account is using the API PRO profile.

GEThttps://riskpaygo.com/portal/api/plugin/ping
cURL example
curl -X GET 'https://riskpaygo.com/portal/api/plugin/ping' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'X-RPG-Merchant: YOUR_MERCHANT_ID'
Example response
{
  "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. Create a payment

Send a POST request with the order and full customer details. Do not send a manual checkout: RiskPayGo decides internally whether FTD or Trusted applies.

POSThttps://riskpaygo.com/portal/api/plugin/payments/create

Required base fields

merchant_order_idUnique order ID in your system.
amountOrder amount. It must respect the limits of the FTD/Trusted route that applies to the buyer.
currencyUse USD or EUR depending on the currency approved for your account.
site.urlStore or website domain approved in RiskPayGo.

Recommended fields

notify_urlURL where you will receive the confirmation webhook.
return_urlURL to return to after a completed payment.
cancel_urlURL to return to if the buyer cancels.
site.platformExample: woocommerce, shopify, custom.
Create payment with cURL
curl -X POST 'https://riskpaygo.com/portal/api/plugin/payments/create' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'X-RPG-Merchant: YOUR_MERCHANT_ID' \
  -d '{
    "merchant_order_id": "ORD-1001",
    "order_id": 1001,
    "order_key": "wc_order_abc123",
    "amount": "149.99",
    "currency": "USD",
    "customer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "customer@example.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://your-domain.com/",
      "name": "My store",
      "platform": "woocommerce",
      "plugin": "riskpaygo-wc"
    },
    "notify_url": "https://your-domain.com/wp-json/riskpaygo/v1/webhook",
    "return_url": "https://your-domain.com/payment/completed",
    "cancel_url": "https://your-domain.com/payment/cancelled"
  }'
Create payment with PHP
$payload = [
    'merchant_order_id' => 'ORD-1001',
    'amount' => '149.99',
    'currency' => 'USD',
    'customer' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'email' => 'customer@example.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://your-domain.com/',
        'name' => 'My store',
        'platform' => 'woocommerce',
    ],
    'notify_url' => 'https://your-domain.com/wp-json/riskpaygo/v1/webhook',
    'return_url' => 'https://your-domain.com/payment/completed',
    'cancel_url' => 'https://your-domain.com/payment/cancelled',
];

$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 YOUR_API_TOKEN',
        'X-RPG-Merchant: YOUR_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;
}
Create payment with Node.js
const response = await fetch('https://riskpaygo.com/portal/api/plugin/payments/create', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'X-RPG-Merchant': 'YOUR_MERCHANT_ID'
  },
  body: JSON.stringify({
    merchant_order_id: 'ORD-1001',
    amount: '149.99',
    currency: 'USD',
    customer: {
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'customer@example.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://your-domain.com/',
      name: 'My store',
      platform: 'custom'
    },
    notify_url: 'https://your-domain.com/webhook/riskpaygo',
    return_url: 'https://your-domain.com/payment/completed',
    cancel_url: 'https://your-domain.com/payment/cancelled'
  })
});

const data = await response.json();
if (data.success && data.data.checkout_url) {
  window.location.href = data.data.checkout_url;
}

8. Expected response

If the payment is created successfully, RiskPayGo will return an internal reference and the checkout URL.

Example JSON
{
  "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"
  }
}
Note: the payment URL may redirect to the FTD or Trusted route depending on the buyer history. Your system does not have to decide it.

9. Validate webhooks

When the payment status changes, RiskPayGo sends a notification to your notify_url. Always validate the signature before marking an order as paid.

X-RPG-SignatureHMAC SHA-256 signature calculated with your Webhook Secret.
payment_refInternal reference returned when creating the payment.
merchant_order_idOrder ID in your system.
statusCommon status: pending, paid, failed or cancelled.
PHP validation
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RPG_SIGNATURE'] ?? '';
$secret = 'YOUR_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') {
    // Mark the order as paid using merchant_order_id or payment_ref.
}

http_response_code(200);
echo 'ok';
Node.js validation
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 || '')
  );
}
Tip: process webhooks idempotently. If you receive the same payment_ref or transaction_id twice, do not duplicate the order or balance.

10. Common errors and how to fix them

CodeCommon messageSolution
403Unauthorized merchantCheck Merchant ID, API Token and Authorization: Bearer header.
403Domain not approvedAdd the domain under Projects and wait for approval before selling live.
422Incomplete customer detailsSend all customer and customer_details fields, including address, city and postal code.
422customer_details.phone is required in '<country code> <number>' formatSend phone as 34 600111222, without + and with a space between country code and number.
422Blocked countryThe buyer is in a restricted country. Show: The country you are trying to pay from is blocked and we cannot process this purchase.
422Amount not allowedFTD allows 10-500 EUR/USD. Trusted allows 10-2,820 EUR/USD.
429Too many attempts or FTD intervalWait a few minutes before starting another payment for the same buyer.
500Internal error creating the transactionRetry and contact support if it persists, including time, domain and merchant_order_id.

11. Security best practices

Protect your keys

Store the API Token and Webhook Secret in environment variables, private plugin settings or secure server configuration.

Always validate the webhook

Do not mark orders as paid just because a request reaches your endpoint. Verify X-RPG-Signature.

Use HTTPS

Your notify_url, return_url and cancel_url must use HTTPS in production.

Do not expose internal details

The buyer should only see the secure RiskPayGo checkout and clear messages. Do not expose tokens, internal routes or credentials.

12. Checklist before enabling live payments

Credentials copiedAPI Base URL, Merchant ID, API Token and Webhook Secret are configured on your server or plugin.
Domain approvedThe URL sent in site.url appears as an approved project in RiskPayGo.
Full details sentThe buyer includes first name, last name, email, phone, country, address, city, postal code, state/province and date of birth.
Phone format correctPhone is sent as 34 600111222, not as +34600111222.
Allowed countryBefore starting payment, confirm the country is not blocked for the applicable route.
No manual checkoutYour integration does not send checkout IDs. RiskPayGo decides FTD or Trusted based on the buyer paid history.
Test paymentThe request to /payments/create returns checkout_url and the buyer can open it.
Webhook validatedYour website validates the signature and marks the order as paid only when it receives status: paid.
Ready: if all points are correct, the PRO integration is ready to operate with RiskPayGo.