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 是否已在控制面板中註冊。

結帳選擇流程

RiskPayGo 根據買家所在國家/地區採用兩種不同的結帳流程：

  • 如果該國派出 客戶國家 是 我們 這 那買家將被引導至美國/加拿大結帳頁面。
  • 如果國家/地區為其他國家/地區，買家將被引導至國際結帳頁面。

您無需提交額外的欄位來手動選擇結帳方式。系統會根據下列數值自動進行選擇： 客戶國家.

因此，在每筆訂單中正確填寫買家所在國家/地區非常重要。

建立付款

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

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

請注意以下事項：

  • 領域 數量 必須大於零。
  • 貨幣以匯款方式發送。 貨幣.
  • 在 顧客 必須發送 名, 姓, 電子郵件 和 國家.
  • 價值 客戶國家 它決定向買家展示哪個結帳頁面。
  • 在 網站網址 您必須提交一個先前已在您的帳戶中獲得批准的網域名稱。
  • 在 通知網址 您需要指定接收付款狀態確認資訊的網址。

各國行為範例

如果您從美國/加拿大以外的國家發送郵件：

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

買家將被引導至美國/加拿大結帳頁面。

如果您從其他國家發送郵件：

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

買家將被引導至國際結帳頁面。

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

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

即使結帳流程是根據買家所在國家/地區選擇的，您的整合流程也相同：您應該始終使用 結帳網址 API 傳回的結果。

結帳時該怎麼辦

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

建議按照以下步驟進行：

  1. 從後端建立支付流程。
  2. 儲存引用 付款參考 在您的系統中。
  3. 將買家重新導向到 結帳網址.
  4. 請等待webhook的最終確認。

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

確認 webhook

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

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

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

X-RPG-Signature: <firma_base64_hmac_sha256>

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 才是主要的資訊來源。

付款狀態

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

  • 待辦的付款已發起，但尚未確認。
  • 有薪資的付款已成功確認。通常情況下，您應該使用此狀態將訂單標記為已付款。
  • 失敗的付款失敗或已被拒絕。
  • 取消付款已被取消或已過期。

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

常見錯誤

未經授權的商家

如果 API 傳回授權錯誤，請檢查以下幾點：

  • 發送的值 授權 正確。
  • 發送的值 X-RPG-商人 匹配該令牌。
  • 商家的帳戶已獲批准並處於啟動狀態。

域名未獲批准

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

國家/地區錯誤或意外結帳

如果買家發現結算單與預期不符，請核對已支付的金額。 客戶國家.

  • 如果你發送 我們 這 那我們將使用美國/加拿大的結帳系統。
  • 如果您要將商品寄送到其他國家/地區，我們將使用國際結帳系統。

國家/地區資訊錯誤可能會導致買家被引導至錯誤的結帳頁面。

無效金額

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

買家資訊不完整

如果請求因客戶資料而失敗，請驗證這一點。 顧客 您必須至少提交以下欄位：

first_name
last_name
email
country

記住這一點 電話 和 出生日期 在這種整合過程中，它們不再是必要的了。

無效的 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

如果插件流程使用買家所在國家/地區產生付款，則在美國/加拿大結帳和國際結帳之間的選擇將遵循上述相同的邏輯。

最終建議

投入生產前，建議確認以下所有事項：

  • 該網域已發送 網站網址 它已獲得RiskPayGo的批准。
  • 那個你 通知網址 它透過HTTPS協定可以正常回應。
  • 哪些守衛 付款參考 在您的系統中，以便能夠將付款與訂單關聯起來。
  • 你發送的是正確的 客戶國家因為這個數值決定了買家會看到哪個結帳頁面。
  • 只有當透過 webhook 收到最終確認訊息時，才能將訂單標記為已付款。 狀態 = 已付費.

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

回到頂部