{"id":502,"date":"2026-04-06T02:14:42","date_gmt":"2026-04-06T00:14:42","guid":{"rendered":"https:\/\/riskpaygo.com\/?page_id=502"},"modified":"2026-05-03T14:12:11","modified_gmt":"2026-05-03T12:12:11","slug":"api","status":"publish","type":"page","link":"https:\/\/riskpaygo.com\/en\/api\/","title":{"rendered":"RiskPayGo API Integration"},"content":{"rendered":"<p>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.<\/p>\n<p>The integration must be done from your backend. Exposing credentials or sensitive logic on the frontend is not recommended.<\/p>\n<h2>Before we begin<\/h2>\n<p>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.<\/p>\n<p>The data you will need is your <code>Merchant ID<\/code>, you <code>API Token<\/code>, you <code>Webhook Secret<\/code> and the base URL of the API.<\/p>\n<p>The base URL is as follows:<\/p>\n<pre><code>https:\/\/riskpaygo.com\/portal\/api\/plugin<\/code><\/pre>\n<h2>Authentication<\/h2>\n<p>All API requests must be authenticated. To do this, you must include the private token in the header. <code>Authorization<\/code> and the merchant identifier in the header <code>X-RPG-Merchant<\/code>.<\/p>\n<p>The necessary headers are these:<\/p>\n<pre><code>Accept: application\/json\nContent-Type: application\/json\nAuthorization: Bearer TU_API_TOKEN\nX-RPG-Merchant: TU_MERCHANT_ID<\/code><\/pre>\n<p>These credentials should only be used on the server. They should not be visible in browser JavaScript or public code.<\/p>\n<h2>Approved Domain<\/h2>\n<p>RiskPayGo validates the domain you send in the field <code>site.url<\/code>This 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.<\/p>\n<p>If the domain does not match one of your approved projects, the API will reject the request even if the token is correct.<\/p>\n<p>Therefore, before going into production, it's advisable to check that the exact URL of your store or application is registered in the panel.<\/p>\n<h2>How the checkout selection works<\/h2>\n<p>RiskPayGo uses two different checkout processes depending on the buyer's country:<\/p>\n<ul>\n<li>If the country sent in <code>customer.country<\/code> is <code>US<\/code> the <code>THAT<\/code>The buyer will be directed to the USA\/Canada checkout.<\/li>\n<li>If the country is any other, the buyer will be sent to the international checkout.<\/li>\n<\/ul>\n<p>You don't need to submit an additional field to manually select the checkout. The selection is made automatically using the value of <code>customer.country<\/code>.<\/p>\n<p>That's why it's important that the buyer's country is correctly entered in each order.<\/p>\n<h2>Create a payment<\/h2>\n<p>To initiate a payment, you must submit a request. <code>POST<\/code> to the payment creation endpoint.<\/p>\n<pre><code>POST https:\/\/riskpaygo.com\/portal\/api\/plugin\/payments\/create<\/code><\/pre>\n<p>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.<\/p>\n<p>A typical request will include fields such as <code>merchant_order_id<\/code>, <code>order_id<\/code>, <code>order_key<\/code>, <code>amount<\/code>, <code>currency<\/code>, <code>customer<\/code>, <code>site<\/code>, <code>notify_url<\/code>, <code>return_url<\/code> and <code>cancel_url<\/code>.<\/p>\n<p>Currently, in the block <code>customer<\/code> You only need to send this buyer information:<\/p>\n<ul>\n<li><code>first_name<\/code>: name<\/li>\n<li><code>last_name<\/code>: surnames<\/li>\n<li><code>email<\/code>: email<\/li>\n<li><code>country<\/code>: country<\/li>\n<\/ul>\n<p>It is no longer necessary to send <code>phone<\/code> in <code>date_of_birth<\/code>.<\/p>\n<p>Below is a complete example of the body you can send:<\/p>\n<pre><code>{\r\n  \"merchant_order_id\": \"PED-1001\",\r\n  \"order_id\": 1001,\r\n  \"order_key\": \"pedido_1001_key\",\r\n  \"amount\": \"149.99\",\r\n  \"currency\": \"USD\",\r\n  \"customer\": {\r\n    \"email\": \"cliente@ejemplo.com\",\r\n    \"first_name\": \"Nombre\",\r\n    \"last_name\": \"Apellido\",\r\n    \"country\": \"US\"\r\n  },\r\n  \"site\": {\r\n    \"url\": \"https:\/\/tu-dominio.com\/\",\r\n    \"name\": \"Mi tienda\",\r\n    \"platform\": \"custom\",\r\n    \"plugin\": \"integracion-propia\"\r\n  },\r\n  \"notify_url\": \"https:\/\/tu-dominio.com\/api\/riskpaygo\/webhook\",\r\n  \"return_url\": \"https:\/\/tu-dominio.com\/pago\/completado\",\r\n  \"cancel_url\": \"https:\/\/tu-dominio.com\/pago\/cancelado\"\r\n}<\/code><\/pre>\n<p>Please note the following:<\/p>\n<ul>\n<li>The field <code>amount<\/code> must be greater than zero.<\/li>\n<li>The currency is sent in <code>currency<\/code>.<\/li>\n<li>In <code>customer<\/code> It is mandatory to send <code>first_name<\/code>, <code>last_name<\/code>, <code>email<\/code> and <code>country<\/code>.<\/li>\n<li>The value of <code>customer.country<\/code> It is the one that determines which checkout will be shown to the buyer.<\/li>\n<li>In <code>site.url<\/code> You must submit a domain that has been previously approved in your account.<\/li>\n<li>In <code>notify_url<\/code> You specify the URL where you want to receive the payment status confirmation.<\/li>\n<\/ul>\n<h3>Examples of behavior by country<\/h3>\n<p>If you are sending from a country outside of the USA\/Canada:<\/p>\n<pre><code>{\r\n  \"customer\": {\r\n    \"email\": \"cliente@ejemplo.com\",\r\n    \"first_name\": \"John\",\r\n    \"last_name\": \"Smith\",\r\n    \"country\": \"US\"\r\n  }\r\n}<\/code><\/pre>\n<p>The buyer will be directed to the USA\/Canada checkout.<\/p>\n<p>If you send from a different country:<\/p>\n<pre><code>{\r\n  \"customer\": {\r\n    \"email\": \"cliente@ejemplo.com\",\r\n    \"first_name\": \"Carlos\",\r\n    \"last_name\": \"Garc\u00eda\",\r\n    \"country\": \"ES\"\r\n  }\r\n}<\/code><\/pre>\n<p>The buyer will be directed to the international checkout.<\/p>\n<h2>API Response<\/h2>\n<p>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.<\/p>\n<p>The expected response takes this form:<\/p>\n<pre><code>{\r\n  \"success\": true,\r\n  \"data\": {\r\n    \"payment_ref\": \"RPG-20260313-ABC12345\",\r\n    \"checkout_url\": \"https:\/\/riskpaygo.com\/portal\/checkout.php?ref=RPG-20260313-ABC12345\",\r\n    \"fee_percent\": 20,\r\n    \"plan_slug\": \"free\"\r\n  }\r\n}<\/code><\/pre>\n<p>As soon as you receive <code>checkout_url<\/code>You must redirect the buyer to that address so they can complete the payment.<\/p>\n<p>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 <code>checkout_url<\/code> returned by the API.<\/p>\n<h2>What to do about the checkout<\/h2>\n<p>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.<\/p>\n<p>The recommended approach is to follow this flow:<\/p>\n<ol>\n<li>Create the payment from your backend.<\/li>\n<li>Save the reference <code>payment_ref<\/code> in your system.<\/li>\n<li>Redirect the buyer to <code>checkout_url<\/code>.<\/li>\n<li>Wait for final confirmation via webhook.<\/li>\n<\/ol>\n<p>The <code>return_url<\/code> 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 <code>notify_url<\/code>.<\/p>\n<h2>Confirmation webhook<\/h2>\n<p>When the payment status changes, RiskPayGo will send a request <code>POST<\/code> to the URL indicated in <code>notify_url<\/code>That notification includes a signature at the top. <code>X-RPG-Signature<\/code>.<\/p>\n<p>You must validate that signature using your <code>Webhook Secret<\/code>The validation must be done on the exact original body of the request, not on a reserialized JSON.<\/p>\n<p>The header you need to check is this one:<\/p>\n<pre><code>X-RPG-Signature: &lt;firma_base64_hmac_sha256&gt;<\/code><\/pre>\n<p>The RiskPayGo notification may include information such as the merchant, order reference, payment reference, status, and transaction ID. An example would be this:<\/p>\n<pre><code>{\r\n  \"merchant_id\": \"TU_MERCHANT_ID\",\r\n  \"order_id\": 1001,\r\n  \"order_key\": \"pedido_1001_key\",\r\n  \"payment_ref\": \"RPG-20260313-ABC12345\",\r\n  \"transaction_id\": \"RPG-20260313-ABC12345\",\r\n  \"status\": \"paid\",\r\n  \"provider_status\": \"success\",\r\n  \"provider_event\": \"payment_succeeded\",\r\n  \"source\": \"payera_webhook\"\r\n}<\/code><\/pre>\n<p>The important thing here is that:<\/p>\n<ul>\n<li>First, validate the signature.<\/li>\n<li>Then check the value of <code>status<\/code>.<\/li>\n<li>And finally, update the order in your system with that status.<\/li>\n<\/ul>\n<p>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.<\/p>\n<h2>Payment statuses<\/h2>\n<p>During integration you must consider four main states:<\/p>\n<ul>\n<li><code>pending<\/code>The payment has been initiated but is not yet confirmed.<\/li>\n<li><code>paid<\/code>The payment has been successfully confirmed. This is the status you should normally use to mark the order as paid.<\/li>\n<li><code>failed<\/code>The payment has failed or has been rejected.<\/li>\n<li><code>cancelled<\/code>The payment has been cancelled or has expired.<\/li>\n<\/ul>\n<p>The general recommendation is to use the webhook as the primary source of truth and only consider the order paid for when you receive <code>status = paid<\/code>.<\/p>\n<h2>Common mistakes<\/h2>\n<h3>Unauthorized Merchant<\/h3>\n<p>If the API responds with an authorization error, check these points:<\/p>\n<ul>\n<li>That the value sent in <code>Authorization<\/code> be correct.<\/li>\n<li>That the value sent in <code>X-RPG-Merchant<\/code> match that token.<\/li>\n<li>That the merchant's account is approved and active.<\/li>\n<\/ul>\n<h3>Domain not approved<\/h3>\n<p>If the problem is in the domain, check the value sent in <code>site.url<\/code> and verify that the domain exists as an approved project within the RiskPayGo panel.<\/p>\n<h3>Incorrect country or unexpected checkout<\/h3>\n<p>If the buyer sees a checkout that differs from what they expected, check the amount sent in <code>customer.country<\/code>.<\/p>\n<ul>\n<li>If you send <code>US<\/code> the <code>THAT<\/code>The USA\/Canada checkout will be used.<\/li>\n<li>If you ship to any other country, the international checkout will be used.<\/li>\n<\/ul>\n<p>An incorrect country value may cause the buyer to be sent to the wrong checkout.<\/p>\n<h3>Invalid amount<\/h3>\n<p>If the API rejects the amount, make sure that <code>amount<\/code> It is sent correctly and has a value greater than zero.<\/p>\n<h3>Incomplete buyer information<\/h3>\n<p>If the request fails due to customer data, verify that in <code>customer<\/code> You must be sending at least these fields:<\/p>\n<pre><code>first_name\nlast_name\nemail\ncountry<\/code><\/pre>\n<p>Remember that <code>phone<\/code> and <code>date_of_birth<\/code> They are no longer necessary in this integration.<\/p>\n<h3>Invalid webhook signature<\/h3>\n<p>If your system fails to validate the notification, check that you are using the <code>Webhook Secret<\/code> correct and that the signature calculation is done on the exact original body of the request.<\/p>\n<h2>Using WooCommerce<\/h2>\n<p>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.<\/p>\n<p>The main values \u200b\u200bto enter are these:<\/p>\n<pre><code>API Base URL: https:\/\/riskpaygo.com\/portal\/api\/plugin\r\nMerchant ID: TU_MERCHANT_ID\r\nAPI Token: TU_API_TOKEN\r\nWebhook Secret: TU_WEBHOOK_SECRET<\/code><\/pre>\n<p>The webhook URL in WordPress usually has this format:<\/p>\n<pre><code>https:\/\/tu-dominio.com\/wp-json\/riskpaygo\/v1\/webhook<\/code><\/pre>\n<p>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.<\/p>\n<h2>Final recommendations<\/h2>\n<p>Before going into production, it is advisable to verify all of the following:<\/p>\n<ul>\n<li>That the domain sent in <code>site.url<\/code> It is approved in RiskPayGo.<\/li>\n<li>That you <code>notify_url<\/code> It responds correctly via HTTPS.<\/li>\n<li>What guards <code>payment_ref<\/code> in your system to be able to link the payment to the order.<\/li>\n<li>That you send correctly <code>customer.country<\/code>because that value determines which checkout the buyer will see.<\/li>\n<li>You only mark orders as paid when the final confirmation arrives via webhook with <code>status = paid<\/code>.<\/li>\n<\/ul>\n<p>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.<\/p>","protected":false},"excerpt":{"rendered":"<p>Esta documentaci\u00f3n explica c\u00f3mo integrar RiskPayGo en tu web o aplicaci\u00f3n para crear pagos, redirigir al comprador al checkout correcto [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"default","adv-header-id-meta":"","stick-header-meta":"default","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"set","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"class_list":["post-502","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/pages\/502","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/comments?post=502"}],"version-history":[{"count":0,"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/pages\/502\/revisions"}],"wp:attachment":[{"href":"https:\/\/riskpaygo.com\/en\/wp-json\/wp\/v2\/media?parent=502"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}