Aquesta documentació explica com integrar RiskPayGo a la teva web o aplicació per crear pagaments, redirigir el comprador al checkout 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/pluginAutenticació
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_IDAquestes 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.
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/createEn aquesta petició heu d'enviar la informació principal de la comanda: l'import, la divisa, les vostres referències internes, les dades 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.
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",
"phone": "+34123456789",
"country": "ES",
"date_of_birth": "1990-05-20"
},
"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"
}El camp quantitat ha de ser més gran que zero. La divisa s'envia a moneda. A client convé enviar, almenys, l'email del comprador. A lloc.url heu d'enviar el domini aprovat. A url_de_notificació indiques on vols rebre la notificació de l'estat del pagament.
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.
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 recomanable és desar la referència referència_de_pagament, redirigir el comprador i esperar la confirmació definitiva per webhook.
La retorn_url serveix per tornar l'usuari al teu lloc després del pagament, però l'estat final ha de basar-se 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: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 validis la signatura i, després, facis servir el valor de estat per actualitzar la comanda al vostre sistema.
Estats del pagament
Durant la integració has de contemplar quatre estats principals.
pendent indica que el pagament ha estat iniciat, però encara no està confirmat.
pagat indica que el pagament ha estat confirmat correctament. Aquest és l'estat amb què normalment has de marcar la comanda com a abonada.
fallat indica que el pagament ha fallat o ha estat rebutjat.
cancel·lat indica que 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ó, el primer que heu de revisar és que el valor enviat a Autorització sigui correcte i que el marxant enviat a X-RPG-Merchant coincideixi amb aquest token. També heu de confirmar que el compte 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.
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.
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_SECRETLa URL del webhook a WordPress sol tenir aquesta forma:
https://tu-dominio.com/wp-json/riskpaygo/v1/webhookRecomanacions finals
Abans de passar a producció, convé verificar que el domini està aprovat, que el teu url_de_notificació respon correctament per HTTPS, que guardes referència_de_pagament al teu sistema i que només marques les comandes com a pagades quan arriba la confirmació final per webhook.
Amb aquesta estructura ja tens una base sòlida per integrar RiskPayGo a una web pròpia, una aplicació personalitzada o una botiga WooCommerce.