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 appropriée et recevoir la confirmation de statut finale 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.

Comment fonctionne la sélection au moment du paiement

RiskPayGo utilise deux processus de paiement différents selon le pays de l'acheteur :

  • Si le pays a envoyé client.pays est NOUS le QUEL'acheteur sera redirigé vers la page de paiement pour les États-Unis/Canada.
  • Si le pays est différent, l'acheteur sera redirigé vers la page de paiement internationale.

Vous n'avez pas besoin de renseigner un champ supplémentaire pour sélectionner manuellement la page de paiement. La sélection est effectuée automatiquement à partir de la valeur de client.pays.

C’est pourquoi il est important que le pays de l’acheteur soit correctement indiqué dans chaque commande.

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 principales informations relatives à la commande : le montant, la devise, vos références internes, les données de base 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, URL de notification, URL de retour et URL d'annulation.

Actuellement, dans le bloc client Il vous suffit d'envoyer ces informations sur l'acheteur :

  • prénom: nom
  • nom de famille: noms de famille
  • e-mail: e-mail
  • pays: pays

Il n'est plus nécessaire d'envoyer téléphone dans date_de_naissance.

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

Veuillez noter ce qui suit :

  • Le champ montant doit être supérieur à zéro.
  • La devise est envoyée en devise.
  • Dans client Il est obligatoire d'envoyer prénom, nom de famille, e-mail et pays.
  • La valeur de client.pays C'est lui qui détermine quelle page de paiement sera affichée à l'acheteur.
  • Dans site.url Vous devez soumettre un domaine qui a été préalablement approuvé dans votre compte.
  • Dans URL de notification Vous indiquez l'URL où vous souhaitez recevoir la confirmation de l'état du paiement.

Exemples de comportement par pays

Si vous envoyez un colis depuis un pays autre que les États-Unis ou le Canada :

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

L'acheteur sera redirigé vers la page de paiement pour les États-Unis/Canada.

Si vous envoyez depuis un autre pays :

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

L'acheteur sera redirigé vers la page de paiement internationale.

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.

Même si le processus de paiement est sélectionné en fonction du pays de l'acheteur, le flux de votre intégration reste le même : vous devez toujours utiliser URL de paiement renvoyé par l'API.

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.

L'approche recommandée consiste à suivre ce processus :

  1. Créez le paiement depuis votre interface d'administration.
  2. Enregistrer la référence référence de paiement dans votre système.
  3. Rediriger l'acheteur vers URL de paiement.
  4. Attendez la confirmation finale via webhook.

Le URL de retour Elle permet de rediriger l'utilisateur vers votre site après le paiement, mais le statut final doit toujours être basé sur la notification que vous recevez. URL de notification.

Webhook de confirmation

Lorsque le statut du paiement change, RiskPayGo enverra une demande POSTE à l'URL indiquée dans URL de notificationCette 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: <firma_base64_hmac_sha256>

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, c'est que :

  • Premièrement, validez la signature.
  • Vérifiez ensuite la valeur de statut.
  • Enfin, mettez à jour la commande dans votre système avec ce statut.

Il ne faut pas considérer une commande comme payée simplement parce que l'utilisateur est retourné sur le site web ou a accédé à la page de confirmation. La source d'information principale doit être le webhook.

Statuts de paiement

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

  • en attenteLe paiement a été initié mais n'est pas encore confirmé.
  • payéLe paiement a bien été confirmé. C'est le statut à utiliser pour indiquer que la commande est payée.
  • échouéLe paiement a échoué ou a été rejeté.
  • annulé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, vérifiez les points suivants :

  • Que la valeur envoyée Autorisation avoir raison.
  • Que la valeur envoyée Marchand de X-RPG faire correspondre ce jeton.
  • Que le compte du commerçant 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.

Pays incorrect ou final de commande inattendu

Si l'acheteur voit un relevé de paiement différent de celui auquel il s'attendait, vérifiez le montant envoyé. client.pays.

  • Si vous envoyez NOUS le QUELe système de paiement pour les États-Unis et le Canada sera utilisé.
  • Si vous souhaitez une livraison vers un autre pays, la procédure de paiement internationale sera utilisée.

Une valeur de pays incorrecte peut entraîner l'envoi de l'acheteur vers la mauvaise page de paiement.

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.

Informations incomplètes sur l'acheteur

Si la requête échoue en raison de données client, vérifiez que dans client Vous devez envoyer au moins les champs suivants :

first_name
last_name
email
country

N'oubliez pas que téléphone et date_de_naissance Elles ne sont plus nécessaires dans cette intégration.

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 de 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

Si le flux du plugin utilise le pays de l'acheteur pour générer le paiement, la sélection entre le paiement aux États-Unis/Canada et le paiement international suivra la même logique que celle décrite ci-dessus.

Recommandations finales

Avant de passer à la production, il est conseillé de vérifier les points suivants :

  • Que le domaine a envoyé site.url Il est approuvé par RiskPayGo.
  • Que tu URL de notification Il répond correctement via HTTPS.
  • Quels gardes référence de paiement dans votre système pour pouvoir lier le paiement à la commande.
  • Que vous envoyiez correctement client.payscar cette valeur détermine quelle page de paiement l'acheteur verra.
  • Vous ne marquez les commandes comme payées que lorsque la confirmation finale arrive par webhook avec statut = payé.

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

Retour en haut de la page