快速开始
介绍 JovePay 的集成方式:身份验证、支付流程、Webhook 处理以及代码示例。
JovePay API
JovePay 是一个非托管的加密货币支付处理平台。支持跨多条区块链网络接收加密货币付款,并即时结算,直接到达您的钱包。保持简洁——没有多余环节。
身份验证
使用 JovePay API 的步骤:
- 在 jovepay.com 注册账号。
- 设置您的结算钱包地址。
- 生成 API 密钥和 IPN 密钥。
注意:IPN 密钥只在创建时完整显示一次,生成后请立即保存。
JovePay 标准电商流程
- API:检查 API 可用性:
GET /v1/status - API(可选):获取可用的支付币种:
GET /v1/currencies - UI:客户选择要购买的商品(得到总价)。
- UI:客户选择支付币种。
- API:获取该币种对的最低支付金额:
GET /v1/min-amount - API:估算应付的加密货币总额:
GET /v1/estimate
(确保高于最低金额) - API:创建支付:
POST /v1/payment
(获得充值地址) - UI:客户向生成的充值地址付款。
- 后端/UI:通过以下方式跟踪支付状态:
- IPN 回调
GET /v1/payment/{payment_id}
- API:获取支付列表:
GET /v1/payment
所有信息也可以在您的 JovePay 账户中查看。
替代流程(使用发票)
您可以为客户生成发票,而不是充值地址。
- API:创建发票:
POST /v1/invoice
(设置success_url以便支付成功后跳转) - UI:展示发票 URL 或将用户重定向到发票页面。
- JovePay:处理支付,并在完成后跳回您的网站(如已配置)。
- 按上述方式跟踪支付状态。
即时支付通知(IPN)
IPN Webhook 会在交易状态更新时通知您。
使用 IPN:
- 生成并保存 IPN 密钥(控制台 → 支付设置)。
- 在
create_payment请求的ipn_callback_url参数中填写您的 Webhook URL。支付状态更新将发送到该地址。-
我们无法向 localhost 发送回调,除非它拥有独立的公网 IP 地址。
-
- 确保您的服务器和防火墙允许来自我们 IP 的请求(如有需要,请联系 [email protected])。
- 我们将向您的
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 文档以及您的开发者控制台。