RiskPayGo API-Integration

Diese Dokumentation erklärt, wie Sie RiskPayGo in Ihre Website oder Anwendung integrieren, um Zahlungen zu erstellen, den Käufer zum richtigen Checkout weiterzuleiten und eine endgültige Statusbestätigung per Webhook zu erhalten.

Die Integration muss über Ihr Backend erfolgen. Es wird nicht empfohlen, Zugangsdaten oder sensible Logik im Frontend offenzulegen.

Bevor wir beginnen

Bevor Sie beginnen, benötigen Sie ein genehmigtes und aktives Händlerkonto bei RiskPayGo. Außerdem benötigen Sie Ihre Integrationsdaten und müssen sicherstellen, dass die Domain, von der Sie Zahlungen empfangen möchten, in Ihrem Konto freigeschaltet ist.

Die Daten, die Sie benötigen, sind Ihre Händler-ID, Du API-Token, Du Webhook-Geheimnis und die Basis-URL der API.

Die Basis-URL lautet wie folgt:

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

Authentifizierung

Alle API-Anfragen müssen authentifiziert werden. Dazu müssen Sie das private Token im Header angeben. Genehmigung und die Händlerkennung im Header X-RPG-Händler.

Die erforderlichen Überschriften lauten wie folgt:

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

Diese Zugangsdaten dürfen nur auf dem Server verwendet werden. Sie dürfen weder im Browser-JavaScript noch im öffentlichen Code sichtbar sein.

Genehmigte Domain

RiskPayGo validiert die Domain, die Sie im Feld angeben. Website-URLDas bedeutet, dass gültige Zugangsdaten nicht ausreichen: Die Domain, von der aus Sie die Zahlung erstellen, muss auch in Ihrem Konto registriert und genehmigt sein.

Wenn die Domain nicht mit einem Ihrer genehmigten Projekte übereinstimmt, lehnt die API die Anfrage ab, selbst wenn das Token korrekt ist.

Daher ist es ratsam, vor Produktionsbeginn zu überprüfen, ob die genaue URL Ihres Shops oder Ihrer Anwendung im Panel registriert ist.

So funktioniert die Auswahl im Bestellvorgang

RiskPayGo verwendet je nach Land des Käufers zwei unterschiedliche Bezahlvorgänge:

  • Wenn das Land entsandt Kunde.Land Ist UNS Die DASDer Käufer wird zur Kasse für die USA/Kanada weitergeleitet.
  • Handelt es sich um ein anderes Land, wird der Käufer zur internationalen Kasse weitergeleitet.

Sie müssen kein zusätzliches Feld ausfüllen, um die Kasse manuell auszuwählen. Die Auswahl erfolgt automatisch anhand des Werts von Kunde.Land.

Deshalb ist es wichtig, dass das Land des Käufers bei jeder Bestellung korrekt angegeben wird.

Eine Zahlung erstellen

Um eine Zahlung auszulösen, müssen Sie einen Antrag stellen. POST zum Endpunkt für die Zahlungserstellung.

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

In dieser Anfrage müssen Sie die wichtigsten Informationen zur Bestellung angeben: den Betrag, die Währung, Ihre internen Referenzen, die grundlegenden Käuferdaten sowie die URLs für Rücksendung und Benachrichtigung.

Eine typische Anfrage enthält Felder wie beispielsweise Händler-Bestell-ID, Bestellnummer, Bestellschlüssel, Menge, Währung, Kunde, Website, notify_url, Rücksprung-URL Und cancel_url.

Aktuell im Block Kunde Sie müssen lediglich diese Käuferinformationen senden:

  • Vorname: Name
  • NachnameNachnamen
  • E-MailE-Mail-Adresse
  • Land: Land

Es ist nicht mehr notwendig zu senden Telefon In Geburtsdatum.

Nachfolgend finden Sie ein vollständiges Beispiel für den Nachrichtentext, den Sie senden können:

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

Bitte beachten Sie Folgendes:

  • Das Feld Menge muss größer als null sein.
  • Das Geld wird gesendet Währung.
  • In Kunde Es ist obligatorisch, Folgendes zu senden Vorname, Nachname, E-Mail Und Land.
  • Der Wert von Kunde.Land Sie ist diejenige, die bestimmt, welche Checkout-Seite dem Käufer angezeigt wird.
  • In Website-URL Sie müssen eine Domain einreichen, die zuvor in Ihrem Konto genehmigt wurde.
  • In notify_url Sie geben die URL an, unter der Sie die Zahlungsstatusbestätigung erhalten möchten.

Beispiele für das Verhalten einzelner Länder

Wenn Sie aus einem Land außerhalb der USA/Kanada senden:

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

Der Käufer wird zur Kasse für die USA/Kanada weitergeleitet.

Wenn Sie aus einem anderen Land senden:

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

Der Käufer wird zur internationalen Kasse weitergeleitet.

API-Antwort

Bei erfolgreicher Anfrage sendet RiskPayGo eine Antwort mit der internen Zahlungsreferenz und der Checkout-URL. Mithilfe dieser Referenz können Sie die Zahlung Ihrer Bestellung zuordnen und diese anschließend verfolgen.

Die erwartete Antwort hat folgende Form:

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

Sobald Sie erhalten Checkout-URLSie müssen den Käufer an diese Adresse weiterleiten, damit er die Zahlung abschließen kann.

Auch wenn die Checkout-Option basierend auf dem Land des Käufers ausgewählt wird, bleibt der Integrationsablauf gleich: Sie sollten immer die Checkout-URL von der API zurückgegeben.

Was ist beim Bezahlvorgang zu tun?

Die Zahlung wird über einen von RiskPayGo bereitgestellten Checkout abgewickelt. Ihr System sollte die Bestellung nicht allein deshalb als bezahlt betrachten, weil Sie die Checkout-URL erhalten haben oder der Nutzer zur Website zurückgekehrt ist.

Die empfohlene Vorgehensweise ist folgende:

  1. Erstellen Sie die Zahlung in Ihrem Backend.
  2. Speichere die Referenz. Zahlungsreferenz in Ihrem System.
  3. Leiten Sie den Käufer weiter zu Checkout-URL.
  4. Warten Sie auf die endgültige Bestätigung per Webhook.

Der Rücksprung-URL Es dient dazu, den Nutzer nach der Zahlung auf Ihre Website zurückzuführen, der endgültige Status sollte jedoch immer auf der Benachrichtigung basieren, die Sie erhalten. notify_url.

Bestätigungs-Webhook

Wenn sich der Zahlungsstatus ändert, sendet RiskPayGo eine Anfrage. POST zur angegebenen URL notify_urlDiese Benachrichtigung enthält oben eine Signatur. X-RPG-Signatur.

Sie müssen diese Signatur mit Ihrem Webhook-GeheimnisDie Validierung muss am exakten Originaltext der Anfrage erfolgen, nicht an einem neu serialisierten JSON-Dokument.

Die zu überprüfende Kopfzeile ist diese:

X-RPG-Signature: <firma_base64_hmac_sha256>

Die RiskPayGo-Benachrichtigung kann Informationen wie Händler, Bestellnummer, Zahlungsreferenz, Status und Transaktions-ID enthalten. Ein Beispiel wäre folgendes:

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

Das Wichtigste hierbei ist Folgendes:

  • Zuerst muss die Signatur überprüft werden.
  • Überprüfen Sie anschließend den Wert von Status.
  • Und schließlich aktualisieren Sie die Bestellung in Ihrem System mit diesem Status.

Eine Bestellung sollte nicht als bezahlt markiert werden, nur weil der Nutzer zur Website zurückgekehrt ist oder die Bestätigungsseite erreicht hat. Die primäre Datenquelle sollte der Webhook sein.

Zahlungsstatus

Bei der Integration müssen vier Hauptzustände berücksichtigt werden:

  • ausstehendDie Zahlung wurde eingeleitet, ist aber noch nicht bestätigt.
  • bezahltDie Zahlung wurde erfolgreich bestätigt. Dies ist der Status, den Sie normalerweise verwenden sollten, um die Bestellung als bezahlt zu markieren.
  • fehlgeschlagenDie Zahlung ist fehlgeschlagen oder wurde abgelehnt.
  • abgesagtDie Zahlung wurde storniert oder ist abgelaufen.

Generell wird empfohlen, den Webhook als primäre Datenquelle zu verwenden und eine Bestellung erst dann als bezahlt zu betrachten, wenn Sie den entsprechenden Eingang erhalten. Status = bezahlt.

Häufige Fehler

Nicht autorisierter Händler

Falls die API mit einem Autorisierungsfehler antwortet, überprüfen Sie folgende Punkte:

  • Dass der Wert gesendet wurde Genehmigung richtig sein.
  • Dass der Wert gesendet wurde X-RPG-Händler Dieses Token muss übereinstimmen.
  • Dass das Händlerkonto genehmigt und aktiv ist.

Domain nicht genehmigt

Wenn das Problem in der Domäne liegt, überprüfen Sie den gesendeten Wert. Website-URL und überprüfen Sie, ob die Domain als genehmigtes Projekt im RiskPayGo-Panel existiert.

Falsches Land oder unerwarteter Checkout

Wenn der Käufer einen Checkout sieht, der von seinen Erwartungen abweicht, überprüfen Sie den gesendeten Betrag. Kunde.Land.

  • Wenn Sie senden UNS Die DASEs wird der Checkout-Prozess für die USA/Kanada verwendet.
  • Bei Lieferungen in andere Länder wird der internationale Bezahlvorgang genutzt.

Eine falsche Länderangabe kann dazu führen, dass der Käufer zur falschen Kasse weitergeleitet wird.

Ungültiger Betrag

Falls die API den Betrag ablehnt, stellen Sie sicher, dass Menge Es wurde korrekt gesendet und hat einen Wert größer als Null.

Unvollständige Käuferinformationen

Falls die Anfrage aufgrund von Kundendaten fehlschlägt, überprüfen Sie, ob in Kunde Sie müssen mindestens die folgenden Felder senden:

first_name
last_name
email
country

Denk daran Telefon Und Geburtsdatum Sie werden in dieser Integration nicht mehr benötigt.

Ungültige Webhook-Signatur

Falls Ihr System die Benachrichtigung nicht validieren kann, überprüfen Sie, ob Sie die Webhook-Geheimnis korrekt ist und dass die Signaturberechnung auf dem exakten Originaltext der Anfrage durchgeführt wird.

WooCommerce verwenden

Wenn Sie das offizielle WooCommerce-Plugin verwenden, sind dieselben Integrationsdetails weiterhin erforderlich. Sie müssen die Basis-URL, den Händler, das Token und das Webhook-Geheimnis konfigurieren.

Folgende Hauptwerte sind einzugeben:

API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRET

Die Webhook-URL in WordPress hat üblicherweise dieses Format:

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

Wenn der Plugin-Ablauf das Land des Käufers zur Generierung der Zahlung verwendet, erfolgt die Auswahl zwischen USA/Kanada-Checkout und internationalem Checkout nach der oben beschriebenen Logik.

Abschließende Empfehlungen

Vor Produktionsbeginn empfiehlt es sich, Folgendes zu überprüfen:

  • Dass die Domain gesendet wurde Website-URL Es ist in RiskPayGo zugelassen.
  • Dass du notify_url Es antwortet korrekt über HTTPS.
  • Welche Wachen Zahlungsreferenz in Ihrem System, um die Zahlung mit der Bestellung verknüpfen zu können.
  • Dass Sie es korrekt senden Kunde.LandDenn dieser Wert bestimmt, welche Kassenabwicklung dem Käufer angezeigt wird.
  • Bestellungen werden erst dann als bezahlt markiert, wenn die endgültige Bestätigung per Webhook eingeht. Status = bezahlt.

Mit dieser Struktur verfügen Sie bereits über eine klare und sichere Grundlage, um RiskPayGo in Ihre eigene Website, eine individuelle Anwendung oder einen WooCommerce-Shop zu integrieren.

Zum Seitenanfang scrollen