Questa documentazione spiega come integrare RiskPayGo nel tuo sito web o nella tua applicazione per creare pagamenti, reindirizzare l'acquirente alla pagina di pagamento e ricevere la conferma finale dello stato tramite webhook.
L'integrazione deve essere effettuata dal backend. Si sconsiglia di esporre credenziali o logiche sensibili sul frontend.
Prima di iniziare
Prima di iniziare, è necessario disporre di un conto commerciante approvato e attivo con RiskPayGo. È inoltre necessario disporre delle credenziali di integrazione e assicurarsi che il dominio da cui si intende ricevere i pagamenti sia approvato all'interno del proprio account.
I dati di cui avrai bisogno sono i tuoi ID Commerciante, Voi Token API, Voi Segreto del webhook e l'URL di base dell'API.
L'URL di base è il seguente:
https://riskpaygo.com/portal/api/pluginAutenticazione
Tutte le richieste API devono essere autenticate. Per farlo, è necessario includere il token privato nell'intestazione. Autorizzazione e l'identificativo del commerciante nell'intestazione X-RPG-Mercante.
Le intestazioni necessarie sono le seguenti:
Accept: application/json
Content-Type: application/json
Authorization: Bearer TU_API_TOKEN
X-RPG-Merchant: TU_MERCHANT_IDQueste credenziali devono essere utilizzate esclusivamente sul server. Non devono essere visibili nel codice JavaScript del browser o nel codice pubblico.
Dominio approvato
RiskPayGo convalida il dominio che invii nel campo URL del sitoCiò significa che possedere credenziali valide non è sufficiente: il dominio da cui si effettua il pagamento deve essere registrato e approvato nel proprio account.
Se il dominio non corrisponde a uno dei progetti approvati, l'API rifiuterà la richiesta anche se il token è corretto.
Pertanto, prima di passare alla fase di produzione, è consigliabile verificare che l'URL corretto del proprio negozio o applicazione sia registrato nel pannello di controllo.
Crea un pagamento
Per avviare un pagamento, è necessario inviare una richiesta. INVIARE all'endpoint di creazione del pagamento.
POST https://riskpaygo.com/portal/api/plugin/payments/createNella richiesta è necessario inviare le informazioni principali dell'ordine: l'importo, la valuta, i riferimenti interni, i dati dell'acquirente e gli URL per il reso e la notifica.
Una richiesta tipica includerà campi come ID_ordine_mercante, ID ordine, chiave_ordine, quantità, valuta, cliente, sito, URL di notifica, URL di ritorno E cancel_url.
Di seguito è riportato un esempio completo del corpo del messaggio che è possibile inviare:
{
"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"
}Il campo quantità Deve essere maggiore di zero. La valuta viene inviata in valuta. In cliente È consigliabile inviare almeno l'indirizzo email dell'acquirente. URL del sito È necessario inviare il dominio approvato. URL di notifica È necessario indicare dove si desidera ricevere la notifica sullo stato del pagamento.
Risposta API
Se la richiesta ha esito positivo, RiskPayGo restituisce una risposta con il riferimento interno del pagamento e l'URL di pagamento. Questo riferimento consente di collegare il pagamento al proprio ordine e di tracciarlo in seguito.
La risposta attesa assume questa 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"
}
}Non appena ricevi URL di checkoutÈ necessario reindirizzare l'acquirente a quell'indirizzo affinché possa completare il pagamento.
Cosa fare riguardo al checkout
Il pagamento viene elaborato tramite una pagina di pagamento gestita da RiskPayGo. Il tuo sistema non deve considerare l'ordine pagato semplicemente perché hai ottenuto l'URL della pagina di pagamento o perché l'utente è tornato sul sito web.
Si consiglia di salvare il riferimento. riferimento_pagamentoReindirizzare l'acquirente e attendere la conferma finale tramite webhook.
IL URL di ritorno Serve a riportare l'utente al tuo sito dopo il pagamento, ma lo stato finale dovrebbe essere basato sulla notifica che ricevi in URL di notifica.
Webhook di conferma
Quando lo stato del pagamento cambia, RiskPayGo invierà una richiesta INVIARE all'URL indicato in URL di notificaTale notifica include una firma in alto. Firma X-RPG.
È necessario convalidare quella firma utilizzando il tuo Segreto del webhookLa convalida deve essere effettuata sul corpo originale esatto della richiesta, non su un JSON riserializzato.
L'intestazione che devi controllare è questa:
X-RPG-Signature:La notifica di RiskPayGo può includere informazioni quali il commerciante, il riferimento dell'ordine, il riferimento del pagamento, lo stato e l'ID della transazione. Ecco un esempio:
{
"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"
}La cosa importante qui è che si convalida la firma e poi si utilizza il valore di stato per aggiornare l'ordine nel tuo sistema.
Stato dei pagamenti
Durante l'integrazione è necessario considerare quattro stati principali.
in attesa di Ciò indica che il pagamento è stato avviato ma non è ancora stato confermato.
pagato Questo indica che il pagamento è stato confermato con successo. Questo è lo stato che normalmente dovresti utilizzare per contrassegnare l'ordine come pagato.
fallito indica che il pagamento non è andato a buon fine o è stato rifiutato.
annullato indica che il pagamento è stato annullato o è scaduto.
La raccomandazione generale è di utilizzare il webhook come fonte primaria di verità e considerare l'ordine pagato solo quando lo si riceve stato = pagato.
Errori comuni
Commerciante non autorizzato
Se l'API risponde con un errore di autorizzazione, la prima cosa da controllare è che il valore inviato in Autorizzazione essere corretto e che il commerciante ha inviato X-RPG-Mercante deve corrispondere a quel token. È inoltre necessario confermare che l'account sia approvato e attivo.
Dominio non approvato
Se il problema è nel dominio, controlla il valore inviato in URL del sito e verificare che il dominio esista come progetto approvato all'interno del pannello RiskPayGo.
Importo non valido
Se l'API rifiuta l'importo, assicurati che quantità È stato inviato correttamente e ha un valore maggiore di zero.
Firma del webhook non valida
Se il tuo sistema non riesce a convalidare la notifica, verifica di utilizzare il Segreto del webhook corretto e che il calcolo della firma venga effettuato sul corpo originale esatto della richiesta.
Utilizzabile con WooCommerce
Se utilizzi il plugin ufficiale di WooCommerce, sono comunque necessari gli stessi dettagli di integrazione. Dovrai configurare l'URL di base, il commerciante, il token e il segreto del webhook.
I valori principali da inserire sono i seguenti:
API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRETL'URL del webhook in WordPress ha solitamente questo formato:
https://tu-dominio.com/wp-json/riskpaygo/v1/webhookRaccomandazioni finali
Prima di andare in produzione, è consigliabile verificare che il dominio sia approvato, che il tuo URL di notifica Risponde correttamente tramite HTTPS, che viene salvato. riferimento_pagamento nel tuo sistema e che contrassegni gli ordini come pagati solo quando arriva la conferma finale tramite webhook.
Con questa struttura disponi già di una solida base per integrare RiskPayGo nel tuo sito web, in un'applicazione personalizzata o in un negozio WooCommerce.