{"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-04-06T11:38:03","modified_gmt":"2026-04-06T09:38:03","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 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>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 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>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    \"phone\": \"+34123456789\",\n    \"country\": \"ES\",\n    \"date_of_birth\": \"1990-05-20\"\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>El camp <code>quantitat<\/code> ha de ser m\u00e9s gran que zero. La divisa s'envia a <code>moneda<\/code>. A <code>client<\/code> conv\u00e9 enviar, almenys, l'email del comprador. A <code>lloc.url<\/code> heu d'enviar el domini aprovat. A <code>url_de_notificaci\u00f3<\/code> indiques on vols rebre la notificaci\u00f3 de l'estat del pagament.<\/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<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 recomanable \u00e9s desar la refer\u00e8ncia <code>refer\u00e8ncia_de_pagament<\/code>, redirigir el comprador i esperar la confirmaci\u00f3 definitiva per webhook.<\/p>\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 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:<\/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 validis la signatura i, despr\u00e9s, facis servir el valor de <code>estat<\/code> per actualitzar la comanda al vostre sistema.<\/p>\n<h2>Estats del pagament<\/h2>\n<p>Durant la integraci\u00f3 has de contemplar quatre estats principals.<\/p>\n<p><code>pendent<\/code> indica que el pagament ha estat iniciat, per\u00f2 encara no est\u00e0 confirmat.<\/p>\n<p><code>pagat<\/code> indica que el pagament ha estat confirmat correctament. Aquest \u00e9s l'estat amb qu\u00e8 normalment has de marcar la comanda com a abonada.<\/p>\n<p><code>fallat<\/code> indica que el pagament ha fallat o ha estat rebutjat.<\/p>\n<p><code>cancel\u00b7lat<\/code> indica que el pagament ha estat cancel\u00b7lat o ha expirat.<\/p>\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, el primer que heu de revisar \u00e9s que el valor enviat a <code>Autoritzaci\u00f3<\/code> sigui correcte i que el marxant enviat a <code>X-RPG-Merchant<\/code> coincideixi amb aquest token. Tamb\u00e9 heu de confirmar que el compte estigui aprovat i actiu.<\/p>\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>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>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<h2>Recomanacions finals<\/h2>\n<p>Abans de passar a producci\u00f3, conv\u00e9 verificar que el domini est\u00e0 aprovat, que el teu <code>url_de_notificaci\u00f3<\/code> respon correctament per HTTPS, que guardes <code>refer\u00e8ncia_de_pagament<\/code> al teu sistema i que nom\u00e9s marques les comandes com a pagades quan arriba la confirmaci\u00f3 final per webhook.<\/p>\n<p>Amb aquesta estructura ja tens una base s\u00f2lida 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 y [&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}]}}