Diese Dokumentation erklärt, wie Sie RiskPayGo in Ihre Website oder Anwendung integrieren, um Zahlungen zu erstellen, den Käufer zur Kasse 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/pluginAuthentifizierung
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_IDDiese 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.
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/createIn dieser Anfrage müssen Sie die wichtigsten Informationen zur Bestellung angeben: den Betrag, die Währung, Ihre internen Referenzen, die Daten des Käufers 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.
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",
"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"
}Das Feld Menge Es muss größer als null sein. Die Währung wird gesendet. Währung. In Kunde Es empfiehlt sich, zumindest die E-Mail-Adresse des Käufers mitzusenden. Website-URL Sie müssen die genehmigte Domain einreichen. notify_url Sie geben an, wohin Sie die Benachrichtigung über den Zahlungsstatus erhalten möchten.
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.
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.
Es wird empfohlen, die Referenz zu speichern. ZahlungsreferenzLeiten Sie den Käufer weiter und 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 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: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"
}Wichtig ist hierbei, dass Sie die Signatur validieren und dann den Wert verwenden. Status Um die Bestellung in Ihrem System zu aktualisieren.
Zahlungsstatus
Bei der Integration müssen vier Hauptzustände berücksichtigt werden.
ausstehend Es bedeutet, dass die Zahlung eingeleitet, aber noch nicht bestätigt wurde.
bezahlt Dies bedeutet, dass die Zahlung erfolgreich bestätigt wurde. Diesen Status sollten Sie normalerweise verwenden, um die Bestellung als bezahlt zu markieren.
fehlgeschlagen weist darauf hin, dass die Zahlung fehlgeschlagen oder abgelehnt wurde.
abgesagt weist darauf hin, dass die Zahlung storniert wurde oder abgelaufen ist.
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
Wenn die API mit einem Autorisierungsfehler antwortet, sollten Sie als Erstes überprüfen, ob der gesendete Wert korrekt ist. Genehmigung korrekt sein und dass der Händler eingesandt hat X-RPG-Händler Sie müssen dieses Token abgleichen. Außerdem müssen Sie bestätigen, dass das Konto 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.
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.
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.
Verwendung mit WooCommerce
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_SECRETDie Webhook-URL in WordPress hat üblicherweise dieses Format:
https://tu-dominio.com/wp-json/riskpaygo/v1/webhookAbschließende Empfehlungen
Vor Produktionsbeginn ist es ratsam, zu überprüfen, ob die Domain genehmigt ist und ob Ihre notify_url Es antwortet korrekt über HTTPS, was Sie speichern. Zahlungsreferenz in Ihrem System und dass Sie Bestellungen erst dann als bezahlt markieren, wenn die endgültige Bestätigung per Webhook eingeht.
Mit dieser Struktur verfügen Sie bereits über eine solide Grundlage, um RiskPayGo in Ihre eigene Website, eine individuelle Anwendung oder einen WooCommerce-Shop zu integrieren.