{"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\/ca\/api\/","title":{"rendered":"Integraci\u00f3 API RiskPayGo"},"content":{"rendered":"<p>Aquesta documentaci\u00f3 explica com integrar RiskPayGo a la teva web o aplicaci\u00f3 per crear pagaments, redirigir el comprador al checkout correcte i rebre la confirmaci\u00f3 final de l'estat mitjan\u00e7ant webhook.<\/p>\n<p>La integraci\u00f3 s'ha de fer des del teu backend. No es recomana exposar credencials ni l\u00f2gica sensible a frontend.<\/p>\n<h2>Abans de comen\u00e7ar<\/h2>\n<p>Abans de comen\u00e7ar, necessites tenir un compte de marxant aprovat i activa a RiskPayGo. Tamb\u00e9 has de comptar amb les teves credencials d'integraci\u00f3 i assegurar-te que el domini des del qual cobrar\u00e0s estigui aprovat dins del teu compte.<\/p>\n<p>Les dades que necessitar\u00e0s s\u00f3n la teva <code>ID del comerciant<\/code>, tu <code>Token de l'API<\/code>, tu <code>Secret del Webhook<\/code> i l'URL base de l'API.<\/p>\n<p>La URL base \u00e9s la seg\u00fcent:<\/p>\n<pre><code>https:\/\/riskpaygo.com\/portal\/api\/plugin<\/code><\/pre>\n<h2>Autenticaci\u00f3<\/h2>\n<p>Totes les peticions a l'API s'han d'enviar autenticades. Per aix\u00f2, has d'incloure el token privat a la cap\u00e7alera <code>Autoritzaci\u00f3<\/code> i l'identificador del marxant a la cap\u00e7alera <code>X-RPG-Merchant<\/code>.<\/p>\n<p>Les cap\u00e7aleres necess\u00e0ries s\u00f3n aquestes:<\/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>Aquestes credencials s'han d'utilitzar nom\u00e9s al servidor. No heu de quedar visibles en JavaScript del navegador ni en codi p\u00fablic.<\/p>\n<h2>Domini aprovat<\/h2>\n<p>RiskPayGo valida el domini que envieu al camp <code>lloc.url<\/code>. Aix\u00f2 vol dir que no n'hi ha prou de tenir unes credencials v\u00e0lides: el domini des del qual est\u00e0s creant el cobrament tamb\u00e9 ha d'estar registrat i aprovat al teu compte.<\/p>\n<p>Si el domini no coincideix amb un dels vostres projectes aprovats, l'API rebutjar\u00e0 la petici\u00f3 encara que el token sigui correcte.<\/p>\n<p>Per aix\u00f2, abans de passar a producci\u00f3, conv\u00e9 comprovar que la URL exacta de la teva botiga o aplicaci\u00f3 est\u00e0 donada d'alta al tauler.<\/p>\n<h2>Com funciona la selecci\u00f3 del checkout<\/h2>\n<p>RiskPayGo treballa amb dos checkout diferents segons el pa\u00eds del comprador:<\/p>\n<ul>\n<li>Si el pa\u00eds enviat a <code>client.pa\u00eds<\/code> ca <code>EUA<\/code> el <code>AIX\u00d2<\/code>, el comprador ser\u00e0 enviat al checkout d'USA\/Canada.<\/li>\n<li>Si el pa\u00eds \u00e9s qualsevol altre, el comprador ser\u00e0 enviat al checkout internacional.<\/li>\n<\/ul>\n<p>No cal enviar un camp addicional per triar manualment el checkout. La selecci\u00f3 es realitza autom\u00e0ticament usant el valor de <code>client.pa\u00eds<\/code>.<\/p>\n<p>Per aix\u00f2 \u00e9s important que el pa\u00eds del comprador s'envi\u00ef correctament a cada sol\u00b7licitud.<\/p>\n<h2>Crear un pagament<\/h2>\n<p>Per iniciar un cobrament has de fer una petici\u00f3 <code>PUBLICACI\u00d3<\/code> a l'endpoint de creaci\u00f3 de pagaments.<\/p>\n<pre><code>POST https:\/\/riskpaygo.com\/portal\/api\/plugin\/payments\/create<\/code><\/pre>\n<p>En aquesta petici\u00f3 heu d'enviar la informaci\u00f3 principal de la comanda: l'import, la divisa, les vostres refer\u00e8ncies internes, les dades b\u00e0siques del comprador i les URLs de retorn i notificaci\u00f3.<\/p>\n<p>Una petici\u00f3 t\u00edpica inclour\u00e0 camps com <code>identificador_de_comanda_del_mercant<\/code>, <code>id_comanda<\/code>, <code>clau_comanda<\/code>, <code>quantitat<\/code>, <code>moneda<\/code>, <code>client<\/code>, <code>lloc<\/code>, <code>url_de_notificaci\u00f3<\/code>, <code>retorn_url<\/code> i <code>cancel_url<\/code>.<\/p>\n<p>Actualment, al bloc <code>client<\/code> nom\u00e9s heu d'enviar aquestes dades del comprador:<\/p>\n<ul>\n<li><code>nom_de_primer<\/code>: nom<\/li>\n<li><code>cognom<\/code>: cognoms<\/li>\n<li><code>correu electr\u00f2nic<\/code>: correu electr\u00f2nic<\/li>\n<li><code>pa\u00eds<\/code>: pa\u00eds<\/li>\n<\/ul>\n<p>Ja no cal enviar <code>tel\u00e8fon<\/code> en <code>data_de_naixement<\/code>.<\/p>\n<p>A continuaci\u00f3 tens un exemple complet del cos que pots enviar:<\/p>\n<pre><code>{\n  \"merchant_order_id\": \"PED-1001\",\n  \"order_id\": 1001,\n  \"order_key\": \"pedido_1001_key\",\n  \"amount\": \"149.99\",\n  \"currency\": \"USD\",\n  \"customer\": {\n    \"email\": \"cliente@ejemplo.com\",\n    \"first_name\": \"Nombre\",\n    \"last_name\": \"Apellido\",\n    \"country\": \"US\"\n  },\n  \"site\": {\n    \"url\": \"https:\/\/tu-dominio.com\/\",\n    \"name\": \"Mi tienda\",\n    \"platform\": \"custom\",\n    \"plugin\": \"integracion-propia\"\n  },\n  \"notify_url\": \"https:\/\/tu-dominio.com\/api\/riskpaygo\/webhook\",\n  \"return_url\": \"https:\/\/tu-dominio.com\/pago\/completado\",\n  \"cancel_url\": \"https:\/\/tu-dominio.com\/pago\/cancelado\"\n}<\/code><\/pre>\n<p>Tingues en compte el seg\u00fcent:<\/p>\n<ul>\n<li>El camp <code>quantitat<\/code> ha de ser m\u00e9s gran que zero.<\/li>\n<li>La divisa s'envia a <code>moneda<\/code>.<\/li>\n<li>A <code>client<\/code> \u00e9s obligatori enviar <code>nom_de_primer<\/code>, <code>cognom<\/code>, <code>correu electr\u00f2nic<\/code> i <code>pa\u00eds<\/code>.<\/li>\n<li>El valor de <code>client.pa\u00eds<\/code> \u00e9s el que determina quin checkout es mostrar\u00e0 al comprador.<\/li>\n<li>A <code>lloc.url<\/code> has d'enviar un domini pr\u00e8viament aprovat al teu compte.<\/li>\n<li>A <code>url_de_notificaci\u00f3<\/code> indiques la URL on vols rebre la confirmaci\u00f3 de l'estat del pagament.<\/li>\n<\/ul>\n<h3>Exemples de comportament per pa\u00eds<\/h3>\n<p>Si envieu un pa\u00eds d'USA\/Canada:<\/p>\n<pre><code>{\n  \"customer\": {\n    \"email\": \"cliente@ejemplo.com\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Smith\",\n    \"country\": \"US\"\n  }\n}<\/code><\/pre>\n<p>El comprador ser\u00e0 dirigit al checkout d'USA\/Canada.<\/p>\n<p>Si envies un pa\u00eds diferent:<\/p>\n<pre><code>{\n  \"customer\": {\n    \"email\": \"cliente@ejemplo.com\",\n    \"first_name\": \"Carlos\",\n    \"last_name\": \"Garc\u00eda\",\n    \"country\": \"ES\"\n  }\n}<\/code><\/pre>\n<p>El comprador ser\u00e0 dirigit al checkout internacional.<\/p>\n<h2>Resposta de l'API<\/h2>\n<p>Si la sol\u00b7licitud \u00e9s correcta, RiskPayGo torna una resposta amb la refer\u00e8ncia interna del pagament i l'URL del checkout. Aquesta refer\u00e8ncia et serveix per enlla\u00e7ar el cobrament amb la teva comanda i per fer-ne un seguiment posterior.<\/p>\n<p>La resposta esperada t\u00e9 aquesta forma:<\/p>\n<pre><code>{\n  \"success\": true,\n  \"data\": {\n    \"payment_ref\": \"RPG-20260313-ABC12345\",\n    \"checkout_url\": \"https:\/\/riskpaygo.com\/portal\/checkout.php?ref=RPG-20260313-ABC12345\",\n    \"fee_percent\": 20,\n    \"plan_slug\": \"free\"\n  }\n}<\/code><\/pre>\n<p>Quan rebis <code>URL_de_compra<\/code>, has de redirigir al comprador a aquesta adre\u00e7a perqu\u00e8 pugui completar el pagament.<\/p>\n<p>Encara que el checkout se seleccioni segons el pa\u00eds del comprador, per a la teva integraci\u00f3 el flux \u00e9s el mateix: sempre has d'usar la <code>URL_de_compra<\/code> tornada per l'API.<\/p>\n<h2>Qu\u00e8 fer amb el checkout<\/h2>\n<p>El pagament es fa en un checkout allotjat per RiskPayGo. El vostre sistema no ha de considerar la comanda com a pagada \u00fanicament per haver obtingut la URL del checkout o perqu\u00e8 l'usuari hagi tornat a la web.<\/p>\n<p>El que \u00e9s recomanable \u00e9s seguir aquest flux:<\/p>\n<ol>\n<li>Crear el pagament des del teu backend.<\/li>\n<li>Desar la refer\u00e8ncia <code>refer\u00e8ncia_de_pagament<\/code> al vostre sistema.<\/li>\n<li>Redirigir el comprador a <code>URL_de_compra<\/code>.<\/li>\n<li>Esperar la confirmaci\u00f3 definitiva mitjan\u00e7ant webhook.<\/li>\n<\/ol>\n<p>La <code>retorn_url<\/code> serveix per tornar l'usuari al teu lloc despr\u00e9s del pagament, per\u00f2 l'estat final ha de basar-se sempre en la notificaci\u00f3 que rebis a <code>url_de_notificaci\u00f3<\/code>.<\/p>\n<h2>Webhook de confirmaci\u00f3<\/h2>\n<p>Quan canvieu l'estat del pagament, RiskPayGo enviar\u00e0 una petici\u00f3 <code>PUBLICACI\u00d3<\/code> a la URL indicada a <code>url_de_notificaci\u00f3<\/code>. Aquesta notificaci\u00f3 inclou una signatura a la cap\u00e7alera <code>X-RPG-Signature<\/code>.<\/p>\n<p>Has de validar aquesta signatura utilitzant el teu <code>Secret del Webhook<\/code>. Cal fer la validaci\u00f3 sobre el cos original exacte de la petici\u00f3, no sobre un JSON reserialitzat.<\/p>\n<p>La cap\u00e7alera que has de comprovar \u00e9s aquesta:<\/p>\n<pre><code>X-RPG-Signature: &lt;firma_base64_hmac_sha256&gt;<\/code><\/pre>\n<p>La notificaci\u00f3 de RiskPayGo pot incloure informaci\u00f3 com el marxant, la refer\u00e8ncia de la comanda, la refer\u00e8ncia del pagament, l'estat i l'identificador de transacci\u00f3. Un exemple seria aquest:<\/p>\n<pre><code>{\n  \"merchant_id\": \"TU_MERCHANT_ID\",\n  \"order_id\": 1001,\n  \"order_key\": \"pedido_1001_key\",\n  \"payment_ref\": \"RPG-20260313-ABC12345\",\n  \"transaction_id\": \"RPG-20260313-ABC12345\",\n  \"status\": \"paid\",\n  \"provider_status\": \"success\",\n  \"provider_event\": \"payment_succeeded\",\n  \"source\": \"payera_webhook\"\n}<\/code><\/pre>\n<p>L'important aqu\u00ed \u00e9s que:<\/p>\n<ul>\n<li>Primer valideu la signatura.<\/li>\n<li>Despr\u00e9s comproveu el valor de <code>estat<\/code>.<\/li>\n<li>I finalment actualitzeu la comanda en el vostre sistema amb aquest estat.<\/li>\n<\/ul>\n<p>No has de marcar una comanda com a pagada nom\u00e9s perqu\u00e8 l'usuari va tornar a la web o perqu\u00e8 va arribar a la p\u00e0gina d'\u00e8xit. La font principal de deb\u00f2 ha de ser el webhook.<\/p>\n<h2>Estats del pagament<\/h2>\n<p>Durant la integraci\u00f3 has de contemplar quatre estats principals:<\/p>\n<ul>\n<li><code>pendent<\/code>: el pagament ha estat iniciat per\u00f2 encara no est\u00e0 confirmat.<\/li>\n<li><code>pagat<\/code>: el pagament ha estat confirmat correctament. Aquest \u00e9s l'estat amb qu\u00e8 normalment has de marcar la comanda com a abonada.<\/li>\n<li><code>fallat<\/code>: el pagament ha fallat o ha estat rebutjat.<\/li>\n<li><code>cancel\u00b7lat<\/code>: el pagament ha estat cancel\u00b7lat o ha expirat.<\/li>\n<\/ul>\n<p>La recomanaci\u00f3 general \u00e9s fer servir el webhook com a font principal de veritat i considerar la comanda pagada nom\u00e9s quan rebis <code>estat = pagat<\/code>.<\/p>\n<h2>Errors freq\u00fcents<\/h2>\n<h3>Merchant no autoritzat<\/h3>\n<p>Si l'API respon amb un error d'autoritzaci\u00f3, revisa aquests punts:<\/p>\n<ul>\n<li>Que el valor enviat a <code>Autoritzaci\u00f3<\/code> sigui correcte.<\/li>\n<li>Que el valor enviat a <code>X-RPG-Merchant<\/code> coincideixi amb aquest token.<\/li>\n<li>Que el compte del marxant estigui aprovat i actiu.<\/li>\n<\/ul>\n<h3>Domini no aprovat<\/h3>\n<p>Si el problema est\u00e0 al domini, revisa el valor enviat a <code>lloc.url<\/code> i comprova que aquest domini existeixi com a projecte aprovat dins del panell de RiskPayGo.<\/p>\n<h3>Pa\u00eds incorrecte o checkout no esperat<\/h3>\n<p>Si el comprador veu un checkout diferent de l'esperat, revisa el valor enviat a <code>client.pa\u00eds<\/code>.<\/p>\n<ul>\n<li>Si envies <code>EUA<\/code> el <code>AIX\u00d2<\/code>, s'usar\u00e0 el checkout d'USA\/Canada.<\/li>\n<li>Si envieu qualsevol altre pa\u00eds, es far\u00e0 servir el checkout internacional.<\/li>\n<\/ul>\n<p>Un valor de pa\u00eds incorrecte pot fer que el comprador sigui enviat al checkout equivocat.<\/p>\n<h3>Import no v\u00e0lid<\/h3>\n<p>Si l'API rebutja l'import, assegureu-vos que <code>quantitat<\/code> s'envia correctament i t\u00e9 un valor m\u00e9s gran que zero.<\/p>\n<h3>Dades incomplets del comprador<\/h3>\n<p>Si la sol\u00b7licitud falla per dades del client, verifica que a <code>client<\/code> estiguis enviant almenys aquests camps:<\/p>\n<pre><code>first_name\nlast_name\nemail\ncountry<\/code><\/pre>\n<p>Recorda que <code>tel\u00e8fon<\/code> i <code>data_de_naixement<\/code> ja no s\u00f3n necessaris en aquesta integraci\u00f3.<\/p>\n<h3>Signatura de webhook inv\u00e0lida<\/h3>\n<p>Si el teu sistema no aconsegueix validar la notificaci\u00f3, revisa que estiguis usant el <code>Secret del Webhook<\/code> correcte i que el c\u00e0lcul de la signatura es faci sobre el cos original exacte de la petici\u00f3.<\/p>\n<h2>\u00das amb WooCommerce<\/h2>\n<p>Si utilitzeu el plugin oficial de WooCommerce, les mateixes dades d'integraci\u00f3 continuen sent necess\u00e0ries. Haureu de configurar l'URL base, el marxant, el token i el secret del webhook.<\/p>\n<p>Els valors principals que cal introduir s\u00f3n aquests:<\/p>\n<pre><code>API Base URL: https:\/\/riskpaygo.com\/portal\/api\/plugin\nMerchant ID: TU_MERCHANT_ID\nAPI Token: TU_API_TOKEN\nWebhook Secret: TU_WEBHOOK_SECRET<\/code><\/pre>\n<p>La URL del webhook a WordPress sol tenir aquesta forma:<\/p>\n<pre><code>https:\/\/tu-dominio.com\/wp-json\/riskpaygo\/v1\/webhook<\/code><\/pre>\n<p>Si el flux del plugin utilitza el pa\u00eds del comprador per generar el pagament, la selecci\u00f3 entre checkout USA\/Canada i checkout internacional seguir\u00e0 la mateixa l\u00f2gica descrita anteriorment.<\/p>\n<h2>Recomanacions finals<\/h2>\n<p>Abans de passar a producci\u00f3, conv\u00e9 verificar tot el seg\u00fcent:<\/p>\n<ul>\n<li>Que el domini enviat a <code>lloc.url<\/code> est\u00e0 aprovat a RiskPayGo.<\/li>\n<li>Que tu <code>url_de_notificaci\u00f3<\/code> respon correctament per HTTPS.<\/li>\n<li>Quins gu\u00e0rdies <code>refer\u00e8ncia_de_pagament<\/code> al teu sistema per poder relacionar el pagament amb la comanda.<\/li>\n<li>Que envies correctament <code>client.pa\u00eds<\/code>, ja que aquest valor decideix quin checkout veur\u00e0 el comprador.<\/li>\n<li>Que nom\u00e9s marques les comandes com a pagades quan arriba la confirmaci\u00f3 final per webhook amb <code>estat = pagat<\/code>.<\/li>\n<\/ul>\n<p>Amb aquesta estructura ja tens una base clara i segura per integrar RiskPayGo a una web pr\u00f2pia, una aplicaci\u00f3 personalitzada o una botiga WooCommerce.<\/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\/ca\/wp-json\/wp\/v2\/pages\/502","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/comments?post=502"}],"version-history":[{"count":0,"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/pages\/502\/revisions"}],"wp:attachment":[{"href":"https:\/\/riskpaygo.com\/ca\/wp-json\/wp\/v2\/media?parent=502"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}