Integració API RiskPayGo

Aquesta documentació explica com integrar RiskPayGo a la teva web o aplicació per crear pagaments, redirigir el comprador al checkout correcte i rebre la confirmació final de l'estat mitjançant webhook.

La integració s'ha de fer des del teu backend. No es recomana exposar credencials ni lògica sensible a frontend.

Abans de començar

Abans de començar, necessites tenir un compte de marxant aprovat i activa a RiskPayGo. També has de comptar amb les teves credencials d'integració i assegurar-te que el domini des del qual cobraràs estigui aprovat dins del teu compte.

Les dades que necessitaràs són la teva ID del comerciant, tu Token de l'API, tu Secret del Webhook i l'URL base de l'API.

La URL base és la següent:

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

Autenticació

Totes les peticions a l'API s'han d'enviar autenticades. Per això, has d'incloure el token privat a la capçalera Autorització i l'identificador del marxant a la capçalera X-RPG-Merchant.

Les capçaleres necessàries són aquestes:

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

Aquestes credencials s'han d'utilitzar només al servidor. No heu de quedar visibles en JavaScript del navegador ni en codi públic.

Domini aprovat

RiskPayGo valida el domini que envieu al camp lloc.url. Això vol dir que no n'hi ha prou de tenir unes credencials vàlides: el domini des del qual estàs creant el cobrament també ha d'estar registrat i aprovat al teu compte.

Si el domini no coincideix amb un dels vostres projectes aprovats, l'API rebutjarà la petició encara que el token sigui correcte.

Per això, abans de passar a producció, convé comprovar que la URL exacta de la teva botiga o aplicació està donada d'alta al tauler.

Com funciona la selecció del checkout

RiskPayGo treballa amb dos checkout diferents segons el país del comprador:

  • Si el país enviat a client.país ca EUA el AIXÒ, el comprador serà enviat al checkout d'USA/Canada.
  • Si el país és qualsevol altre, el comprador serà enviat al checkout internacional.

No cal enviar un camp addicional per triar manualment el checkout. La selecció es realitza automàticament usant el valor de client.país.

Per això és important que el país del comprador s'enviï correctament a cada sol·licitud.

Crear un pagament

Per iniciar un cobrament has de fer una petició PUBLICACIÓ a l'endpoint de creació de pagaments.

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

En aquesta petició heu d'enviar la informació principal de la comanda: l'import, la divisa, les vostres referències internes, les dades bàsiques del comprador i les URLs de retorn i notificació.

Una petició típica inclourà camps com identificador_de_comanda_del_mercant, id_comanda, clau_comanda, quantitat, moneda, client, lloc, url_de_notificació, retorn_url i cancel_url.

Actualment, al bloc client només heu d'enviar aquestes dades del comprador:

  • nom_de_primer: nom
  • cognom: cognoms
  • correu electrònic: correu electrònic
  • país: país

Ja no cal enviar telèfon en data_de_naixement.

A continuació tens un exemple complet del cos que pots enviar:

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

Tingues en compte el següent:

  • El camp quantitat ha de ser més gran que zero.
  • La divisa s'envia a moneda.
  • A client és obligatori enviar nom_de_primer, cognom, correu electrònic i país.
  • El valor de client.país és el que determina quin checkout es mostrarà al comprador.
  • A lloc.url has d'enviar un domini prèviament aprovat al teu compte.
  • A url_de_notificació indiques la URL on vols rebre la confirmació de l'estat del pagament.

Exemples de comportament per país

Si envieu un país d'USA/Canada:

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

El comprador serà dirigit al checkout d'USA/Canada.

Si envies un país diferent:

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

El comprador serà dirigit al checkout internacional.

Resposta de l'API

Si la sol·licitud és correcta, RiskPayGo torna una resposta amb la referència interna del pagament i l'URL del checkout. Aquesta referència et serveix per enllaçar el cobrament amb la teva comanda i per fer-ne un seguiment posterior.

La resposta esperada té aquesta forma:

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

Quan rebis URL_de_compra, has de redirigir al comprador a aquesta adreça perquè pugui completar el pagament.

Encara que el checkout se seleccioni segons el país del comprador, per a la teva integració el flux és el mateix: sempre has d'usar la URL_de_compra tornada per l'API.

Què fer amb el checkout

El pagament es fa en un checkout allotjat per RiskPayGo. El vostre sistema no ha de considerar la comanda com a pagada únicament per haver obtingut la URL del checkout o perquè l'usuari hagi tornat a la web.

El que és recomanable és seguir aquest flux:

  1. Crear el pagament des del teu backend.
  2. Desar la referència referència_de_pagament al vostre sistema.
  3. Redirigir el comprador a URL_de_compra.
  4. Esperar la confirmació definitiva mitjançant webhook.

La retorn_url serveix per tornar l'usuari al teu lloc després del pagament, però l'estat final ha de basar-se sempre en la notificació que rebis a url_de_notificació.

Webhook de confirmació

Quan canvieu l'estat del pagament, RiskPayGo enviarà una petició PUBLICACIÓ a la URL indicada a url_de_notificació. Aquesta notificació inclou una signatura a la capçalera X-RPG-Signature.

Has de validar aquesta signatura utilitzant el teu Secret del Webhook. Cal fer la validació sobre el cos original exacte de la petició, no sobre un JSON reserialitzat.

La capçalera que has de comprovar és aquesta:

X-RPG-Signature: <firma_base64_hmac_sha256>

La notificació de RiskPayGo pot incloure informació com el marxant, la referència de la comanda, la referència del pagament, l'estat i l'identificador de transacció. Un exemple seria aquest:

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

L'important aquí és que:

  • Primer valideu la signatura.
  • Després comproveu el valor de estat.
  • I finalment actualitzeu la comanda en el vostre sistema amb aquest estat.

No has de marcar una comanda com a pagada només perquè l'usuari va tornar a la web o perquè va arribar a la pàgina d'èxit. La font principal de debò ha de ser el webhook.

Estats del pagament

Durant la integració has de contemplar quatre estats principals:

  • pendent: el pagament ha estat iniciat però encara no està confirmat.
  • pagat: el pagament ha estat confirmat correctament. Aquest és l'estat amb què normalment has de marcar la comanda com a abonada.
  • fallat: el pagament ha fallat o ha estat rebutjat.
  • cancel·lat: el pagament ha estat cancel·lat o ha expirat.

La recomanació general és fer servir el webhook com a font principal de veritat i considerar la comanda pagada només quan rebis estat = pagat.

Errors freqüents

Merchant no autoritzat

Si l'API respon amb un error d'autorització, revisa aquests punts:

  • Que el valor enviat a Autorització sigui correcte.
  • Que el valor enviat a X-RPG-Merchant coincideixi amb aquest token.
  • Que el compte del marxant estigui aprovat i actiu.

Domini no aprovat

Si el problema està al domini, revisa el valor enviat a lloc.url i comprova que aquest domini existeixi com a projecte aprovat dins del panell de RiskPayGo.

País incorrecte o checkout no esperat

Si el comprador veu un checkout diferent de l'esperat, revisa el valor enviat a client.país.

  • Si envies EUA el AIXÒ, s'usarà el checkout d'USA/Canada.
  • Si envieu qualsevol altre país, es farà servir el checkout internacional.

Un valor de país incorrecte pot fer que el comprador sigui enviat al checkout equivocat.

Import no vàlid

Si l'API rebutja l'import, assegureu-vos que quantitat s'envia correctament i té un valor més gran que zero.

Dades incomplets del comprador

Si la sol·licitud falla per dades del client, verifica que a client estiguis enviant almenys aquests camps:

first_name
last_name
email
country

Recorda que telèfon i data_de_naixement ja no són necessaris en aquesta integració.

Signatura de webhook invàlida

Si el teu sistema no aconsegueix validar la notificació, revisa que estiguis usant el Secret del Webhook correcte i que el càlcul de la signatura es faci sobre el cos original exacte de la petició.

Ús amb WooCommerce

Si utilitzeu el plugin oficial de WooCommerce, les mateixes dades d'integració continuen sent necessàries. Haureu de configurar l'URL base, el marxant, el token i el secret del webhook.

Els valors principals que cal introduir són aquests:

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

La URL del webhook a WordPress sol tenir aquesta forma:

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

Si el flux del plugin utilitza el país del comprador per generar el pagament, la selecció entre checkout USA/Canada i checkout internacional seguirà la mateixa lògica descrita anteriorment.

Recomanacions finals

Abans de passar a producció, convé verificar tot el següent:

  • Que el domini enviat a lloc.url està aprovat a RiskPayGo.
  • Que tu url_de_notificació respon correctament per HTTPS.
  • Quins guàrdies referència_de_pagament al teu sistema per poder relacionar el pagament amb la comanda.
  • Que envies correctament client.país, ja que aquest valor decideix quin checkout veurà el comprador.
  • Que només marques les comandes com a pagades quan arriba la confirmació final per webhook amb estat = pagat.

Amb aquesta estructura ja tens una base clara i segura per integrar RiskPayGo a una web pròpia, una aplicació personalitzada o una botiga WooCommerce.

Desplaça't a dalt