快速开始

介绍 JovePay 的集成方式:身份验证、支付流程、Webhook 处理以及代码示例。

JovePay API

JovePay 是一个非托管的加密货币支付处理平台。支持跨多条区块链网络接收加密货币付款,并即时结算,直接到达您的钱包。保持简洁——没有多余环节。

身份验证

使用 JovePay API 的步骤:

  1. 在 jovepay.com 注册账号。
  2. 设置您的结算钱包地址。
  3. 生成 API 密钥和 IPN 密钥。

注意:IPN 密钥只在创建时完整显示一次,生成后请立即保存。

JovePay 标准电商流程

  1. API:检查 API 可用性:
    GET /v1/status
  2. API(可选):获取可用的支付币种:
    GET /v1/currencies
  3. UI:客户选择要购买的商品(得到总价)。
  4. UI:客户选择支付币种。
  5. API:获取该币种对的最低支付金额:
    GET /v1/min-amount
  6. API:估算应付的加密货币总额:
    GET /v1/estimate
    (确保高于最低金额)
  7. API:创建支付:
    POST /v1/payment
    (获得充值地址)
  8. UI:客户向生成的充值地址付款。
  9. 后端/UI:通过以下方式跟踪支付状态:
    • IPN 回调
    • GET /v1/payment/{payment_id}
  10. API:获取支付列表:
    GET /v1/payment

所有信息也可以在您的 JovePay 账户中查看。


替代流程(使用发票)

您可以为客户生成发票,而不是充值地址。

  1. API:创建发票:
    POST /v1/invoice
    (设置 success_url 以便支付成功后跳转)
  2. UI:展示发票 URL 或将用户重定向到发票页面。
  3. JovePay:处理支付,并在完成后跳回您的网站(如已配置)。
  4. 按上述方式跟踪支付状态。

即时支付通知(IPN)

IPN Webhook 会在交易状态更新时通知您。

使用 IPN:

  1. 生成并保存 IPN 密钥(控制台 → 支付设置)。
  2. 在 create_payment 请求的 ipn_callback_url 参数中填写您的 Webhook URL。支付状态更新将发送到该地址。
    • 我们无法向 localhost 发送回调,除非它拥有独立的公网 IP 地址。

  3. 确保您的服务器和防火墙允许来自我们 IP 的请求(如有需要,请联系 [email protected])。
  4. 我们将向您的 ipn_callback_url 发送 POST 更新。
    • 请求头:x-jovepay-sig(签名)
    • 请求体:JSON(与支付状态结构类似)

验证 IPN 请求

对键进行排序并编码为 JSON,然后使用您的 IPN 密钥进行签名(sha512/HMAC)。将签名与 x-jovepay-sig 请求头进行对比。

Node.js 示例

function sortObject(obj) {
  return Object.keys(obj).sort().reduce(
    (result, key) => {
      result[key] = (obj[key] && typeof obj[key] === 'object') ? sortObject(obj[key]) : obj[key];
      return result;
    }, {}
  );
}

const hmac = crypto.createHmac('sha512', notificationsKey);
hmac.update(JSON.stringify(sortObject(params)));
const signature = hmac.digest('hex');

PHP 示例

function tksort(&$array) {
  ksort($array);
  foreach(array_keys($array) as $k) {
    if(gettype($array[$k])=="array") {
      tksort($array[$k]);
    }
  }
}

function check_ipn_request_is_valid() {
  $error_msg = "Unknown error";
  $auth_ok = false;
  $request_data = null;
  if (isset($_SERVER['HTTP_X_JOVEPAY_SIG']) && !empty($_SERVER['HTTP_X_JOVEPAY_SIG'])) {
    $recived_hmac = $_SERVER['HTTP_X_JOVEPAY_SIG'];
    $request_json = file_get_contents('php://input');
    $request_data = json_decode($request_json, true);
    tksort($request_data);
    $sorted_request_json = json_encode($request_data, JSON_UNESCAPED_SLASHES);
    if ($request_json !== false && !empty($request_json)) {
      $hmac = hash_hmac("sha512", $sorted_request_json, trim($this->ipn_secret));
      if ($hmac == $recived_hmac) {
        $auth_ok = true;
      } else {
        $error_msg = 'HMAC signature does not match';
      }
    } else {
      $error_msg = 'Error reading POST data';
    }
  } else {
    $error_msg = 'No HMAC signature sent.';
  }
}

Python 示例

import json
import hmac
import hashlib

def np_signature_check(np_secret_key, np_x_signature, message):
    sorted_msg = json.dumps(message, separators=(',', ':'), sort_keys=True)
    digest = hmac.new(
        str(np_secret_key).encode(), 
        f'{sorted_msg}'.encode(),
        hashlib.sha512
    )
    signature = digest.hexdigest()
    if signature == np_x_signature:
        return
    else:
        print("HMAC signature does not match")

提示:每个事件都会发送通知。上线前请务必测试您的接收端点。

重复支付通知

如果投递失败,我们将根据您在控制台中的设置进行重试。


Webhook 示例

支付 Webhook

{
  "payment_id": 123456789,
  "parent_payment_id": 987654321,
  "invoice_id": null,
  "payment_status": "finished",
  "pay_address": "address",
  "payin_extra_id": null,
  "price_amount": 1,
  "price_currency": "usd",
  "pay_amount": 15,
  "actually_paid": 15,
  "pay_currency": "trx",
  "order_id": null,
  "order_description": null,
  "purchase_id": "123456789",
  "outcome_amount": 14.8106,
  "outcome_currency": "trx",
  "payment_extra_ids": null,
  "fee": {
    "currency": "btc",
    "depositFee": 0.09853637216235617,
    "serviceFee": 0
  }
}

结算 Webhook

{
  "id": "123456789",
  "payment_id": "987654321",
  "status": "SETTLED",
  "error": null,
  "currency": "usdttrc20",
  "amount": "50",
  "address": "merchant_wallet_address",
  "hash": "tx_hash",
  "extra_id": null,
  "ipn_callback_url": "callback_url",
  "settled_at": "2026-07-27T15:29:40.803Z"
}

处理重复充值与错误资产充值

重复充值

  • 对同一充值地址的额外付款(parent_payment_id 关联到原始支付)。
  • 在控制台中标记为“Re-deposit”。
  • 在 IPN 中跟踪 parent_payment_id,以避免对部分付款/少付金额提供服务。
  • 不建议基于重复充值状态自动履约。

**注意:**所有重复充值都会被兑换为原始支付币种。

错误资产充值

  • 用户发送了错误的网络/资产(但平台支持该资产)。
  • 在控制台中标记为“Wrong Asset”。
  • 通常需要人工处理。
  • 您可以在控制台设置中启用自动处理,但请谨慎使用。
  • 始终以 IPN 中的金额和资产类型为准进行验证。

API 调用示例

检查 API 状态

curl --location 'https://api.jovepay.com/v1/status'

成功响应:

{
  "message": "OK"
}

身份验证并获取 JWT

curl --location 'https://api.jovepay.com/v1/auth' \
  --header 'Content-Type: application/json' \
  --data '{
      "email": "your_email",
      "password": "your_password"
  }'

成功响应:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

所有需要认证的接口都使用此 Token 作为 Bearer:

Authorization: Bearer <token>

更多接口方法和详细流程,请参阅 JovePay 官方 API 文档以及您的开发者控制台。

目錄