Intégration de l'API RiskPayGo

Cette documentation explique comment intégrer RiskPayGo à votre site web ou application pour créer des paiements, rediriger l'acheteur vers la page de paiement et recevoir la confirmation de statut final via webhook.

L'intégration doit être effectuée depuis votre backend. Il est déconseillé d'exposer des identifiants ou des données sensibles côté client.

Avant de commencer

Avant de commencer, vous devez disposer d'un compte marchand RiskPayGo approuvé et actif. Vous aurez également besoin de vos identifiants d'intégration et devrez vous assurer que le domaine à partir duquel vous collecterez les paiements est autorisé dans votre compte.

Les données dont vous aurez besoin sont les vôtres ID du commerçant, toi Jeton API, toi Secret du webhook et l'URL de base de l'API.

L'URL de base est la suivante :

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

Authentification

Toutes les requêtes API doivent être authentifiées. Pour ce faire, vous devez inclure le jeton privé dans l'en-tête. Autorisation et l'identifiant du commerçant dans l'en-tête Marchand de X-RPG.

Les en-têtes nécessaires sont les suivants :

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

Ces identifiants ne doivent être utilisés que sur le serveur. Ils ne doivent pas être visibles dans le code JavaScript du navigateur ni dans le code public.

Domaine approuvé

RiskPayGo valide le domaine que vous envoyez dans le champ. site.urlCela signifie que disposer d'identifiants valides ne suffit pas : le domaine à partir duquel vous effectuez le paiement doit également être enregistré et approuvé dans votre compte.

Si le domaine ne correspond à aucun de vos projets approuvés, l'API rejettera la requête même si le jeton est correct.

Par conséquent, avant la mise en production, il est conseillé de vérifier que l'URL exacte de votre boutique ou application est bien enregistrée dans le panneau.

Créer un paiement

Pour initier un paiement, vous devez soumettre une demande. POSTE vers le point de terminaison de création de paiement.

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

Dans cette demande, vous devez envoyer les informations principales de la commande : le montant, la devise, vos références internes, les coordonnées de l’acheteur ainsi que les URL de retour et de notification.

Une requête type comprendra des champs tels que : id_commande_marchand, id_de_commande, clé_de_commande, montant, devise, client, site, notification_url, URL de retour et URL d'annulation.

Voici un exemple complet du corps du message que vous pouvez envoyer :

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

Le champ montant Il doit être supérieur à zéro. La devise est envoyée en devise. Dans client Il est conseillé d'envoyer au moins l'adresse électronique de l'acheteur. site.url Vous devez soumettre le domaine approuvé. notification_url Vous indiquez où vous souhaitez recevoir la notification relative à l'état du paiement.

Réponse de l'API

Si la requête aboutit, RiskPayGo renvoie une réponse contenant la référence de paiement interne et l'URL de la page de paiement. Cette référence vous permet d'associer le paiement à votre commande et d'en suivre l'évolution.

La réponse attendue prend la forme suivante :

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

Dès que vous recevez URL de paiementVous devez rediriger l'acheteur vers cette adresse afin qu'il puisse effectuer le paiement.

Que faire au moment du passage en caisse

Le paiement est traité via une plateforme de paiement hébergée par RiskPayGo. Votre système ne doit pas considérer la commande comme payée simplement parce que vous avez obtenu l'URL de paiement ou parce que l'utilisateur est retourné sur le site web.

Il est recommandé de conserver la référence. référence de paiementrediriger l'acheteur et attendre la confirmation finale via webhook.

Le URL de retour Cela permet de rediriger l'utilisateur vers votre site après le paiement, mais le statut final dépendra de la notification que vous recevez. notification_url.

Webhook de confirmation

Lorsque le statut du paiement change, RiskPayGo enverra une demande POSTE à l'URL indiquée dans notification_urlCette notification comporte une signature en haut. Signature X-RPG.

Vous devez valider cette signature à l'aide de votre Secret du webhookLa validation doit être effectuée sur le corps original exact de la requête, et non sur un JSON resérialisé.

L'en-tête que vous devez vérifier est celui-ci :

X-RPG-Signature:

La notification RiskPayGo peut inclure des informations telles que le nom du commerçant, la référence de la commande, la référence du paiement, le statut et l'identifiant de la transaction. Voici un exemple :

{
  "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 ici est de valider la signature, puis d'utiliser la valeur de statut pour mettre à jour la commande dans votre système.

Statuts de paiement

Lors de l'intégration, vous devez prendre en compte quatre états principaux.

en attente Cela indique que le paiement a été initié mais n'est pas encore confirmé.

payé Cela indique que le paiement a bien été confirmé. C'est le statut à utiliser pour marquer la commande comme payée.

échoué indique que le paiement a échoué ou a été rejeté.

annulé indique que le paiement a été annulé ou a expiré.

Il est généralement recommandé d'utiliser le webhook comme source principale de vérité et de ne considérer la commande payée que lorsqu'elle est reçue. statut = payé.

Erreurs courantes

Commerçant non autorisé

Si l'API renvoie une erreur d'autorisation, la première chose à vérifier est la valeur envoyée. Autorisation être correct et que le commerçant a envoyé Marchand de X-RPG Vous devez faire correspondre ce jeton. Vous devez également confirmer que le compte est approuvé et actif.

Domaine non approuvé

Si le problème se situe au niveau du domaine, vérifiez la valeur envoyée dans site.url et vérifiez que le domaine existe bien en tant que projet approuvé dans le panel RiskPayGo.

Montant invalide

Si l'API rejette le montant, assurez-vous que montant Elle est correctement envoyée et sa valeur est supérieure à zéro.

Signature de webhook invalide

Si votre système ne parvient pas à valider la notification, vérifiez que vous utilisez bien le Secret du webhook correct et que le calcul de la signature est effectué sur le corps original exact de la requête.

Utilisation avec WooCommerce

Si vous utilisez l'extension WooCommerce officielle, les mêmes informations d'intégration sont nécessaires. Vous devrez configurer l'URL de base, le nom du marchand, le jeton et le secret du webhook.

Les principales valeurs à saisir sont les suivantes :

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 du webhook dans WordPress a généralement ce format :

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

Recommandations finales

Avant la mise en production, il est conseillé de vérifier que le domaine est approuvé et que votre notification_url Il répond correctement via HTTPS, ce qui vous permet de sauvegarder vos données. référence de paiement dans votre système et que vous ne marquez les commandes comme payées que lorsque la confirmation finale arrive par webhook.

Grâce à cette structure, vous disposez déjà d'une base solide pour intégrer RiskPayGo à votre propre site web, à une application personnalisée ou à une boutique WooCommerce.