Integrazione API di RiskPayGo

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.

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/plugin

Autenticazione

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_ID

Queste 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.

Come funziona la selezione al momento del pagamento

RiskPayGo utilizza due diverse procedure di pagamento a seconda del paese dell'acquirente:

  • Se il paese ha inviato paese cliente È NOI IL QUELLOL'acquirente verrà reindirizzato alla pagina di pagamento per Stati Uniti/Canada.
  • Se il paese è diverso, l'acquirente verrà reindirizzato alla pagina di pagamento internazionale.

Non è necessario inviare un campo aggiuntivo per selezionare manualmente il checkout. La selezione viene effettuata automaticamente utilizzando il valore di paese cliente.

Per questo motivo è importante che il paese dell'acquirente venga inserito correttamente in ogni ordine.

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/create

Nella richiesta è 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.

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.

Attualmente, nel blocco cliente Devi inviare solo queste informazioni all'acquirente:

  • nome di battesimo: nome
  • cognome: cognomi
  • e-mail: email
  • Paese: Paese

Non è più necessario inviare telefono In data_di_nascita.

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

Si prega di prendere nota di quanto segue:

  • Il campo quantità deve essere maggiore di zero.
  • La valuta viene inviata in valuta.
  • In cliente È obbligatorio inviare nome di battesimo, cognome, e-mail E Paese.
  • Il valore di paese cliente È quello che determina quale procedura di pagamento verrà mostrata all'acquirente.
  • In URL del sito È necessario inviare un dominio che sia stato precedentemente approvato nel proprio account.
  • In URL di notifica È necessario specificare l'URL al quale si desidera ricevere la conferma dello stato del pagamento.

Esempi di comportamento per paese

Se effettui la spedizione da un Paese al di fuori di Stati Uniti e Canada:

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

L'acquirente verrà reindirizzato alla pagina di pagamento per Stati Uniti/Canada.

Se invii da un altro Paese:

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

L'acquirente verrà indirizzato alla pagina di pagamento internazionale.

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.

Anche se il checkout viene selezionato in base al paese dell'acquirente, il flusso per la tua integrazione è lo stesso: dovresti sempre utilizzare il URL di checkout restituito dall'API.

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 seguire questo flusso:

  1. Crea il pagamento dal tuo pannello di controllo.
  2. Salva il riferimento riferimento_pagamento nel tuo sistema.
  3. Reindirizzare l'acquirente a URL di checkout.
  4. Attendi la conferma definitiva tramite webhook.

IL URL di ritorno Serve a riportare l'utente al tuo sito dopo il pagamento, ma lo stato finale dovrebbe sempre basarsi 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: <firma_base64_hmac_sha256>

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:

  • Innanzitutto, convalida la firma.
  • Quindi controlla il valore di stato.
  • Infine, aggiorna l'ordine nel tuo sistema con tale stato.

Non dovresti contrassegnare un ordine come pagato solo perché l'utente è tornato sul sito web o ha raggiunto la pagina di conferma. La fonte primaria di informazioni attendibili dovrebbe essere il webhook.

Stato dei pagamenti

Durante l'integrazione è necessario considerare quattro stati principali:

  • in attesa diIl pagamento è stato avviato ma non è ancora stato confermato.
  • pagatoIl pagamento è stato confermato con successo. Questo è lo stato che normalmente dovresti utilizzare per contrassegnare l'ordine come pagato.
  • fallitoIl pagamento non è andato a buon fine o è stato rifiutato.
  • annullatoIl 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 restituisce un errore di autorizzazione, verifica questi punti:

  • Che il valore inviato Autorizzazione essere corretto.
  • Che il valore inviato X-RPG-Mercante abbina quel token.
  • Che l'account del commerciante 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.

Paese errato o procedura di pagamento inattesa

Se l'acquirente vede un checkout diverso da quello che si aspettava, controlla l'importo inviato paese cliente.

  • Se invii NOI IL QUELLOVerrà utilizzata la procedura di pagamento per Stati Uniti e Canada.
  • Se effettui la spedizione verso un altro Paese, verrà utilizzata la procedura di pagamento internazionale.

L'inserimento di un paese errato potrebbe reindirizzare l'acquirente alla pagina di pagamento sbagliata.

Importo non valido

Se l'API rifiuta l'importo, assicurati che quantità È stato inviato correttamente e ha un valore maggiore di zero.

Informazioni incomplete sull'acquirente

Se la richiesta fallisce a causa dei dati del cliente, verificare che in cliente È necessario inviare almeno i seguenti campi:

first_name
last_name
email
country

Ricorda che telefono E data_di_nascita In questa integrazione non sono più necessari.

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.

Utilizzo di 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_SECRET

L'URL del webhook in WordPress ha solitamente questo formato:

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

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à la stessa logica descritta sopra.

Raccomandazioni finali

Prima di avviare la produzione, è consigliabile verificare tutti i seguenti aspetti:

  • Che il dominio inviato URL del sito È approvato da RiskPayGo.
  • Che tu URL di notifica Risponde correttamente tramite HTTPS.
  • Quali guardie riferimento_pagamento nel vostro sistema per poter collegare il pagamento all'ordine.
  • Che tu invii correttamente paese clienteperché quel valore determina quale schermata di pagamento visualizzerà l'acquirente.
  • Contrassegni gli ordini come pagati solo quando arriva la conferma finale tramite webhook con stato = pagato.

Con questa struttura disponi già di una base chiara e sicura per integrare RiskPayGo nel tuo sito web, in un'applicazione personalizzata o in un negozio WooCommerce.

Scorri verso l'alto