RiskPayGo API Integration

This documentation explains how to integrate RiskPayGo into your website or application to create payments, redirect the buyer to the correct checkout, and receive final status confirmation via webhook.

The integration must be done from your backend. Exposing credentials or sensitive logic on the frontend is not recommended.

Before we begin

Before you begin, you need an approved and active merchant account with RiskPayGo. You also need your integration credentials and to ensure that the domain you'll be collecting payments from is approved within your account.

The data you will need is your Merchant ID, you API Token, you Webhook Secret and the base URL of the API.

The base URL is as follows:

https://riskpaygo.com/portal/api/plugin

Authentication

All API requests must be authenticated. To do this, you must include the private token in the header. Authorization and the merchant identifier in the header X-RPG-Merchant.

The necessary headers are these:

Accept: application/json
Content-Type: application/json
Authorization: Bearer TU_API_TOKEN
X-RPG-Merchant: TU_MERCHANT_ID

These credentials should only be used on the server. They should not be visible in browser JavaScript or public code.

Approved Domain

RiskPayGo validates the domain you send in the field site.urlThis means that having valid credentials is not enough: the domain from which you are creating the payment must also be registered and approved in your account.

If the domain does not match one of your approved projects, the API will reject the request even if the token is correct.

Therefore, before going into production, it's advisable to check that the exact URL of your store or application is registered in the panel.

How the checkout selection works

RiskPayGo uses two different checkout processes depending on the buyer's country:

  • If the country sent in customer.country is US the THATThe buyer will be directed to the USA/Canada checkout.
  • If the country is any other, the buyer will be sent to the international checkout.

You don't need to submit an additional field to manually select the checkout. The selection is made automatically using the value of customer.country.

That's why it's important that the buyer's country is correctly entered in each order.

Create a payment

To initiate a payment, you must submit a request. POST to the payment creation endpoint.

POST https://riskpaygo.com/portal/api/plugin/payments/create

In that request you must send the main information of the order: the amount, the currency, your internal references, the basic buyer data and the return and notification URLs.

A typical request will include fields such as merchant_order_id, order_id, order_key, amount, currency, customer, site, notify_url, return_url and cancel_url.

Currently, in the block customer You only need to send this buyer information:

  • first_name: name
  • last_name: surnames
  • email: email
  • country: country

It is no longer necessary to send phone in date_of_birth.

Below is a complete example of the body you can send:

{
  "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",
    "country": "US"
  },
  "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"
}

Please note the following:

  • The field amount must be greater than zero.
  • The currency is sent in currency.
  • In customer It is mandatory to send first_name, last_name, email and country.
  • The value of customer.country It is the one that determines which checkout will be shown to the buyer.
  • In site.url You must submit a domain that has been previously approved in your account.
  • In notify_url You specify the URL where you want to receive the payment status confirmation.

Examples of behavior by country

If you are sending from a country outside of the USA/Canada:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "John",
    "last_name": "Smith",
    "country": "US"
  }
}

The buyer will be directed to the USA/Canada checkout.

If you send from a different country:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Carlos",
    "last_name": "García",
    "country": "ES"
  }
}

The buyer will be directed to the international checkout.

API Response

If the request is successful, RiskPayGo returns a response with the internal payment reference and the checkout URL. This reference allows you to link the payment to your order and track it afterward.

The expected response takes this form:

{
  "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"
  }
}

As soon as you receive checkout_urlYou must redirect the buyer to that address so they can complete the payment.

Even if the checkout is selected based on the buyer's country, the flow for your integration is the same: you should always use the checkout_url returned by the API.

What to do about the checkout

Payment is processed through a checkout hosted by RiskPayGo. Your system should not consider the order paid simply because you obtained the checkout URL or because the user returned to the website.

The recommended approach is to follow this flow:

  1. Create the payment from your backend.
  2. Save the reference payment_ref in your system.
  3. Redirect the buyer to checkout_url.
  4. Wait for final confirmation via webhook.

The return_url It serves to return the user to your site after payment, but the final status should always be based on the notification you receive in notify_url.

Confirmation webhook

When the payment status changes, RiskPayGo will send a request POST to the URL indicated in notify_urlThat notification includes a signature at the top. X-RPG-Signature.

You must validate that signature using your Webhook SecretThe validation must be done on the exact original body of the request, not on a reserialized JSON.

The header you need to check is this one:

X-RPG-Signature: <firma_base64_hmac_sha256>

The RiskPayGo notification may include information such as the merchant, order reference, payment reference, status, and transaction ID. An example would be this:

{
  "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"
}

The important thing here is that:

  • First, validate the signature.
  • Then check the value of status.
  • And finally, update the order in your system with that status.

You shouldn't mark an order as paid just because the user returned to the website or reached the success page. The primary source of truth should be the webhook.

Payment statuses

During integration you must consider four main states:

  • pendingThe payment has been initiated but is not yet confirmed.
  • paidThe payment has been successfully confirmed. This is the status you should normally use to mark the order as paid.
  • failedThe payment has failed or has been rejected.
  • cancelledThe payment has been cancelled or has expired.

The general recommendation is to use the webhook as the primary source of truth and only consider the order paid for when you receive status = paid.

Common mistakes

Unauthorized Merchant

If the API responds with an authorization error, check these points:

  • That the value sent in Authorization be correct.
  • That the value sent in X-RPG-Merchant match that token.
  • That the merchant's account is approved and active.

Domain not approved

If the problem is in the domain, check the value sent in site.url and verify that the domain exists as an approved project within the RiskPayGo panel.

Incorrect country or unexpected checkout

If the buyer sees a checkout that differs from what they expected, check the amount sent in customer.country.

  • If you send US the THATThe USA/Canada checkout will be used.
  • If you ship to any other country, the international checkout will be used.

An incorrect country value may cause the buyer to be sent to the wrong checkout.

Invalid amount

If the API rejects the amount, make sure that amount It is sent correctly and has a value greater than zero.

Incomplete buyer information

If the request fails due to customer data, verify that in customer You must be sending at least these fields:

first_name
last_name
email
country

Remember that phone and date_of_birth They are no longer necessary in this integration.

Invalid webhook signature

If your system fails to validate the notification, check that you are using the Webhook Secret correct and that the signature calculation is done on the exact original body of the request.

Using WooCommerce

If you're using the official WooCommerce plugin, the same integration details are still required. You'll need to configure the base URL, merchant, token, and webhook secret.

The main values ​​to enter are these:

API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRET

The webhook URL in WordPress usually has this format:

https://tu-dominio.com/wp-json/riskpaygo/v1/webhook

If the plugin flow uses the buyer's country to generate the payment, the selection between USA/Canada checkout and international checkout will follow the same logic described above.

Final recommendations

Before going into production, it is advisable to verify all of the following:

  • That the domain sent in site.url It is approved in RiskPayGo.
  • That you notify_url It responds correctly via HTTPS.
  • What guards payment_ref in your system to be able to link the payment to the order.
  • That you send correctly customer.countrybecause that value determines which checkout the buyer will see.
  • You only mark orders as paid when the final confirmation arrives via webhook with status = paid.

With this structure you already have a clear and secure foundation to integrate RiskPayGo into your own website, a custom application or a WooCommerce store.

Scroll to Top