RiskPayGo API 整合

本文檔說明如何將 RiskPayGo 整合到您的網站或應用程式中，以建立付款、將買家重新導向到結帳頁面，並透過 webhook 接收最終狀態確認。

集成必須在後端完成。不建議在前端暴露憑證或敏感邏輯。

在我們開始之前

在開始之前，您需要一個已批准且有效的 RiskPayGo 商家帳戶。您還需要整合憑證，並確保您用於收款的網域已在您的帳戶中獲得批准。

您需要的數據是您的 商家ID，你 API令牌，你 Webhook 秘密 以及 API 的基本 URL。

基本網址如下：

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

驗證

所有 API 請求都必須經過身份驗證。為此，您必須在請求頭中包含私有令牌。 授權 以及標頭中的商家識別碼。 X-RPG-商人.

必要的頭部資訊如下：

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

這些憑證只能在伺服器端使用，不應在瀏覽器 JavaScript 或公用程式碼中可見。

已批准域名

RiskPayGo 會驗證您在欄位中發送的網域名稱。 網站網址這意味著擁有有效的憑證是不夠的：您用於建立付款的網域名稱也必須在您的帳戶中註冊並獲得批准。

如果網域名稱與您已核准的項目之一不匹配，即使令牌正確，API 也會拒絕該要求。

因此，在投入生產之前，建議檢查您的商店或應用程式的確切 URL 是否已在控制面板中註冊。

建立付款

要發起付款，您必須提交申請。 郵政 到支付創建端點。

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

在該請求中，您必須發送訂單的主要資訊：金額、貨幣、您的內部參考編號、買家詳細資訊以及退貨和通知網址。

典型的請求將包含以下欄位： 商家訂單 ID, 訂單編號, 訂單鍵, 數量, 貨幣, 顧客, 地點, 通知網址, 返回網址 和 取消網址.

以下是您可以發送的正文的完整範例：

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

領域 數量 它必須大於零。貨幣以這種形式發送。 貨幣。在 顧客 建議至少發送買家的電子郵件地址。 網站網址 您必須提交已批准的網域名稱。 通知網址 您可指定接收付款狀態通知的途徑。

API回應

如果請求成功，RiskPayGo 會傳回包含內部支付參考號碼和結帳 URL 的回應。您可以使用此參考號碼將付款關聯到您的訂單，並在之後追蹤付款狀態。

預期的回應形式如下：

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

您一收到 結帳網址您必須將買家重新導向到該地址，以便他們完成付款。

結帳時該怎麼辦

付款透過 RiskPayGo 提供的結帳系統處理。您的系統不應僅僅因為您獲得了結帳 URL 或用戶返回了網站就認為訂單已支付。

建議保存參考資料。 付款參考重定向買家並等待透過 webhook 進行的最終確認。

這 返回網址 它的作用是在用戶付款後將其返回到您的網站，但最終狀態應以您收到的通知為準。 通知網址.

確認 webhook

當支付狀態變更時，RiskPayGo 將發送請求 郵政 跳到指定的URL 通知網址該通知頂部包含簽名。 X-RPG-簽名.

您必須使用您的 Webhook 秘密驗證必須基於請求的原始正文進行，而不是基於重新序列化的 JSON。

您需要檢查的標頭是這個：

X-RPG-Signature:

RiskPayGo 通知可能包含商家資訊、訂單參考號碼、付款參考號碼、狀態和交易 ID 等資訊。例如：

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

關鍵在於驗證簽名，然後使用該值。 地位 更新系統中的訂單。

付款狀態

在整合過程中，您必須考慮四個主要狀態。

待辦的 這表示付款已發起，但尚未確認。

有薪資的 這表示付款已成功確認。通常情況下，您應該使用此狀態將訂單標記為已付款。

失敗的 表示付款失敗或已被拒絕。

取消 表示付款已被取消或已過期。

一般建議是將 webhook 作為主要資訊來源，並且僅在收到款項時才將已付款訂單視為最終資訊。 狀態 = 已付費.

常見錯誤

未經授權的商家

如果 API 傳回授權錯誤，首先應該檢查的是發送的值是否正確。 授權 正確，且商家發送的訊息屬實。 X-RPG-商人 請核對該令牌。您還必須確認該帳戶已獲批准且處於啟動狀態。

域名未獲批准

如果問題出在網域中，請檢查傳送的值。 網站網址 並確認該網域已作為 RiskPayGo 面板中的已核准項目存在。

無效金額

如果 API 拒絕該金額，請確保： 數量 它已正確發送，且值大於零。

無效的 Webhook 簽名

如果您的系統無法驗證通知，請檢查您是否正在使用… Webhook 秘密 正確，簽名計算是在請求的原始正文上進行的。

與 WooCommerce 搭配使用

如果您使用的是官方 WooCommerce 插件，則仍需要相同的整合資訊。您需要設定基本 URL、商家資訊、令牌和 Webhook 金鑰。

需要輸入的主要數值如下：

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

WordPress 中的 webhook URL 通常會採用以下格式：

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

最終建議

在正式上線之前，建議先確認網域是否已獲批准，以及您的 通知網址 它透過 HTTPS 正確回應，您可以保存。 付款參考 在您的系統中，只有當透過 webhook 收到最終確認時，您才能將訂單標記為已付款。

有了這個結構，您就已經擁有了將 RiskPayGo 整合到您自己的網站、自訂應用程式或 WooCommerce 商店中的堅實基礎。

RiskPayGo API 集成