{"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\/it\/api\/","title":{"rendered":"Integrazione API di RiskPayGo"},"content":{"rendered":"<p>Questa documentazione spiega come integrare RiskPayGo nel tuo sito web o nella tua applicazione per creare pagamenti, reindirizzare l'acquirente alla pagina di pagamento corretta e ricevere la conferma finale dello stato tramite webhook.<\/p>\n<p>L'integrazione deve essere effettuata dal backend. Si sconsiglia di esporre credenziali o logiche sensibili sul frontend.<\/p>\n<h2>Prima di iniziare<\/h2>\n<p>Prima di iniziare, \u00e8 necessario disporre di un conto commerciante approvato e attivo con RiskPayGo. \u00c8 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.<\/p>\n<p>I dati di cui avrai bisogno sono i tuoi <code>ID Commerciante<\/code>, Voi <code>Token API<\/code>, Voi <code>Segreto del webhook<\/code> e l'URL di base dell'API.<\/p>\n<p>L'URL di base \u00e8 il seguente:<\/p>\n<pre><code>https:\/\/riskpaygo.com\/portal\/api\/plugin<\/code><\/pre>\n<h2>Autenticazione<\/h2>\n<p>Tutte le richieste API devono essere autenticate. Per farlo, \u00e8 necessario includere il token privato nell'intestazione. <code>Autorizzazione<\/code> e l'identificativo del commerciante nell'intestazione <code>X-RPG-Mercante<\/code>.<\/p>\n<p>Le intestazioni necessarie sono le seguenti:<\/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>Queste credenziali devono essere utilizzate esclusivamente sul server. Non devono essere visibili nel codice JavaScript del browser o nel codice pubblico.<\/p>\n<h2>Dominio approvato<\/h2>\n<p>RiskPayGo convalida il dominio che invii nel campo <code>URL del sito<\/code>Ci\u00f2 significa che possedere credenziali valide non \u00e8 sufficiente: il dominio da cui si effettua il pagamento deve essere registrato e approvato nel proprio account.<\/p>\n<p>Se il dominio non corrisponde a uno dei progetti approvati, l'API rifiuter\u00e0 la richiesta anche se il token \u00e8 corretto.<\/p>\n<p>Pertanto, prima di passare alla fase di produzione, \u00e8 consigliabile verificare che l'URL corretto del proprio negozio o applicazione sia registrato nel pannello di controllo.<\/p>\n<h2>Come funziona la selezione al momento del pagamento<\/h2>\n<p>RiskPayGo utilizza due diverse procedure di pagamento a seconda del paese dell'acquirente:<\/p>\n<ul>\n<li>Se il paese ha inviato <code>paese cliente<\/code> \u00c8 <code>NOI<\/code> IL <code>QUELLO<\/code>L'acquirente verr\u00e0 reindirizzato alla pagina di pagamento per Stati Uniti\/Canada.<\/li>\n<li>Se il paese \u00e8 diverso, l'acquirente verr\u00e0 reindirizzato alla pagina di pagamento internazionale.<\/li>\n<\/ul>\n<p>Non \u00e8 necessario inviare un campo aggiuntivo per selezionare manualmente il checkout. La selezione viene effettuata automaticamente utilizzando il valore di <code>paese cliente<\/code>.<\/p>\n<p>Per questo motivo \u00e8 importante che il paese dell'acquirente venga inserito correttamente in ogni ordine.<\/p>\n<h2>Crea un pagamento<\/h2>\n<p>Per avviare un pagamento, \u00e8 necessario inviare una richiesta. <code>INVIARE<\/code> all'endpoint di creazione del pagamento.<\/p>\n<pre><code>POST https:\/\/riskpaygo.com\/portal\/api\/plugin\/payments\/create<\/code><\/pre>\n<p>Nella richiesta \u00e8 necessario inviare le informazioni principali dell'ordine: l'importo, la valuta, i riferimenti interni, i dati anagrafici dell'acquirente e gli URL per il reso e la notifica.<\/p>\n<p>Una richiesta tipica includer\u00e0 campi come <code>ID_ordine_mercante<\/code>, <code>ID ordine<\/code>, <code>chiave_ordine<\/code>, <code>quantit\u00e0<\/code>, <code>valuta<\/code>, <code>cliente<\/code>, <code>sito<\/code>, <code>URL di notifica<\/code>, <code>URL di ritorno<\/code> E <code>cancel_url<\/code>.<\/p>\n<p>Attualmente, nel blocco <code>cliente<\/code> Devi inviare solo queste informazioni all'acquirente:<\/p>\n<ul>\n<li><code>nome di battesimo<\/code>: nome<\/li>\n<li><code>cognome<\/code>: cognomi<\/li>\n<li><code>e-mail<\/code>: email<\/li>\n<li><code>Paese<\/code>: Paese<\/li>\n<\/ul>\n<p>Non \u00e8 pi\u00f9 necessario inviare <code>telefono<\/code> In <code>data_di_nascita<\/code>.<\/p>\n<p>Di seguito \u00e8 riportato un esempio completo del corpo del messaggio che \u00e8 possibile inviare:<\/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>Si prega di prendere nota di quanto segue:<\/p>\n<ul>\n<li>Il campo <code>quantit\u00e0<\/code> deve essere maggiore di zero.<\/li>\n<li>La valuta viene inviata in <code>valuta<\/code>.<\/li>\n<li>In <code>cliente<\/code> \u00c8 obbligatorio inviare <code>nome di battesimo<\/code>, <code>cognome<\/code>, <code>e-mail<\/code> E <code>Paese<\/code>.<\/li>\n<li>Il valore di <code>paese cliente<\/code> \u00c8 quello che determina quale procedura di pagamento verr\u00e0 mostrata all'acquirente.<\/li>\n<li>In <code>URL del sito<\/code> \u00c8 necessario inviare un dominio che sia stato precedentemente approvato nel proprio account.<\/li>\n<li>In <code>URL di notifica<\/code> \u00c8 necessario specificare l'URL al quale si desidera ricevere la conferma dello stato del pagamento.<\/li>\n<\/ul>\n<h3>Esempi di comportamento per paese<\/h3>\n<p>Se effettui la spedizione da un Paese al di fuori di Stati Uniti e 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>L'acquirente verr\u00e0 reindirizzato alla pagina di pagamento per Stati Uniti\/Canada.<\/p>\n<p>Se invii da un altro Paese:<\/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>L'acquirente verr\u00e0 indirizzato alla pagina di pagamento internazionale.<\/p>\n<h2>Risposta API<\/h2>\n<p>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.<\/p>\n<p>La risposta attesa assume questa 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>Non appena ricevi <code>URL di checkout<\/code>\u00c8 necessario reindirizzare l'acquirente a quell'indirizzo affinch\u00e9 possa completare il pagamento.<\/p>\n<p>Anche se il checkout viene selezionato in base al paese dell'acquirente, il flusso per la tua integrazione \u00e8 lo stesso: dovresti sempre utilizzare il <code>URL di checkout<\/code> restituito dall'API.<\/p>\n<h2>Cosa fare riguardo al checkout<\/h2>\n<p>Il pagamento viene elaborato tramite una pagina di pagamento gestita da RiskPayGo. Il tuo sistema non deve considerare l'ordine pagato semplicemente perch\u00e9 hai ottenuto l'URL della pagina di pagamento o perch\u00e9 l'utente \u00e8 tornato sul sito web.<\/p>\n<p>Si consiglia di seguire questo flusso:<\/p>\n<ol>\n<li>Crea il pagamento dal tuo pannello di controllo.<\/li>\n<li>Salva il riferimento <code>riferimento_pagamento<\/code> nel tuo sistema.<\/li>\n<li>Reindirizzare l'acquirente a <code>URL di checkout<\/code>.<\/li>\n<li>Attendi la conferma definitiva tramite webhook.<\/li>\n<\/ol>\n<p>IL <code>URL di ritorno<\/code> Serve a riportare l'utente al tuo sito dopo il pagamento, ma lo stato finale dovrebbe sempre basarsi sulla notifica che ricevi in <code>URL di notifica<\/code>.<\/p>\n<h2>Webhook di conferma<\/h2>\n<p>Quando lo stato del pagamento cambia, RiskPayGo invier\u00e0 una richiesta <code>INVIARE<\/code> all'URL indicato in <code>URL di notifica<\/code>Tale notifica include una firma in alto. <code>Firma X-RPG<\/code>.<\/p>\n<p>\u00c8 necessario convalidare quella firma utilizzando il tuo <code>Segreto del webhook<\/code>La convalida deve essere effettuata sul corpo originale esatto della richiesta, non su un JSON riserializzato.<\/p>\n<p>L'intestazione che devi controllare \u00e8 questa:<\/p>\n<pre><code>X-RPG-Signature: &lt;firma_base64_hmac_sha256&gt;<\/code><\/pre>\n<p>La notifica di RiskPayGo pu\u00f2 includere informazioni quali il commerciante, il riferimento dell'ordine, il riferimento del pagamento, lo stato e l'ID della transazione. Ecco un esempio:<\/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>La cosa importante qui \u00e8 che:<\/p>\n<ul>\n<li>Innanzitutto, convalida la firma.<\/li>\n<li>Quindi controlla il valore di <code>stato<\/code>.<\/li>\n<li>Infine, aggiorna l'ordine nel tuo sistema con tale stato.<\/li>\n<\/ul>\n<p>Non dovresti contrassegnare un ordine come pagato solo perch\u00e9 l'utente \u00e8 tornato sul sito web o ha raggiunto la pagina di conferma. La fonte primaria di informazioni attendibili dovrebbe essere il webhook.<\/p>\n<h2>Stato dei pagamenti<\/h2>\n<p>Durante l'integrazione \u00e8 necessario considerare quattro stati principali:<\/p>\n<ul>\n<li><code>in attesa di<\/code>Il pagamento \u00e8 stato avviato ma non \u00e8 ancora stato confermato.<\/li>\n<li><code>pagato<\/code>Il pagamento \u00e8 stato confermato con successo. Questo \u00e8 lo stato che normalmente dovresti utilizzare per contrassegnare l'ordine come pagato.<\/li>\n<li><code>fallito<\/code>Il pagamento non \u00e8 andato a buon fine o \u00e8 stato rifiutato.<\/li>\n<li><code>annullato<\/code>Il pagamento \u00e8 stato annullato o \u00e8 scaduto.<\/li>\n<\/ul>\n<p>La raccomandazione generale \u00e8 di utilizzare il webhook come fonte primaria di verit\u00e0 e considerare l'ordine pagato solo quando lo si riceve <code>stato = pagato<\/code>.<\/p>\n<h2>Errori comuni<\/h2>\n<h3>Commerciante non autorizzato<\/h3>\n<p>Se l'API restituisce un errore di autorizzazione, verifica questi punti:<\/p>\n<ul>\n<li>Che il valore inviato <code>Autorizzazione<\/code> essere corretto.<\/li>\n<li>Che il valore inviato <code>X-RPG-Mercante<\/code> abbina quel token.<\/li>\n<li>Che l'account del commerciante sia approvato e attivo.<\/li>\n<\/ul>\n<h3>Dominio non approvato<\/h3>\n<p>Se il problema \u00e8 nel dominio, controlla il valore inviato in <code>URL del sito<\/code> e verificare che il dominio esista come progetto approvato all'interno del pannello RiskPayGo.<\/p>\n<h3>Paese errato o procedura di pagamento inattesa<\/h3>\n<p>Se l'acquirente vede un checkout diverso da quello che si aspettava, controlla l'importo inviato <code>paese cliente<\/code>.<\/p>\n<ul>\n<li>Se invii <code>NOI<\/code> IL <code>QUELLO<\/code>Verr\u00e0 utilizzata la procedura di pagamento per Stati Uniti e Canada.<\/li>\n<li>Se effettui la spedizione verso un altro Paese, verr\u00e0 utilizzata la procedura di pagamento internazionale.<\/li>\n<\/ul>\n<p>L'inserimento di un paese errato potrebbe reindirizzare l'acquirente alla pagina di pagamento sbagliata.<\/p>\n<h3>Importo non valido<\/h3>\n<p>Se l'API rifiuta l'importo, assicurati che <code>quantit\u00e0<\/code> \u00c8 stato inviato correttamente e ha un valore maggiore di zero.<\/p>\n<h3>Informazioni incomplete sull'acquirente<\/h3>\n<p>Se la richiesta fallisce a causa dei dati del cliente, verificare che in <code>cliente<\/code> \u00c8 necessario inviare almeno i seguenti campi:<\/p>\n<pre><code>first_name\nlast_name\nemail\ncountry<\/code><\/pre>\n<p>Ricorda che <code>telefono<\/code> E <code>data_di_nascita<\/code> In questa integrazione non sono pi\u00f9 necessari.<\/p>\n<h3>Firma del webhook non valida<\/h3>\n<p>Se il tuo sistema non riesce a convalidare la notifica, verifica di utilizzare il <code>Segreto del webhook<\/code> corretto e che il calcolo della firma venga effettuato sul corpo originale esatto della richiesta.<\/p>\n<h2>Utilizzo di WooCommerce<\/h2>\n<p>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.<\/p>\n<p>I valori principali da inserire sono i seguenti:<\/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>L'URL del webhook in WordPress ha solitamente questo formato:<\/p>\n<pre><code>https:\/\/tu-dominio.com\/wp-json\/riskpaygo\/v1\/webhook<\/code><\/pre>\n<p>Se il flusso del plugin utilizza il paese dell'acquirente per generare il pagamento, la selezione tra checkout per USA\/Canada e checkout internazionale seguir\u00e0 la stessa logica descritta sopra.<\/p>\n<h2>Raccomandazioni finali<\/h2>\n<p>Prima di avviare la produzione, \u00e8 consigliabile verificare tutti i seguenti aspetti:<\/p>\n<ul>\n<li>Che il dominio inviato <code>URL del sito<\/code> \u00c8 approvato da RiskPayGo.<\/li>\n<li>Che tu <code>URL di notifica<\/code> Risponde correttamente tramite HTTPS.<\/li>\n<li>Quali guardie <code>riferimento_pagamento<\/code> nel vostro sistema per poter collegare il pagamento all'ordine.<\/li>\n<li>Che tu invii correttamente <code>paese cliente<\/code>perch\u00e9 quel valore determina quale schermata di pagamento visualizzer\u00e0 l'acquirente.<\/li>\n<li>Contrassegni gli ordini come pagati solo quando arriva la conferma finale tramite webhook con <code>stato = pagato<\/code>.<\/li>\n<\/ul>\n<p>Con questa struttura disponi gi\u00e0 di una base chiara e sicura per integrare RiskPayGo nel tuo sito web, in un'applicazione personalizzata o in un negozio 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\/it\/wp-json\/wp\/v2\/pages\/502","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/comments?post=502"}],"version-history":[{"count":0,"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/pages\/502\/revisions"}],"wp:attachment":[{"href":"https:\/\/riskpaygo.com\/it\/wp-json\/wp\/v2\/media?parent=502"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}