加密大额支付API：以非托管方式自动化支付

加密大额支付API的实际功能

单个POST /v1/payout调用为整个批次保留资金，验证每个收款人，并将其排队等待签名。然后，操作员从离线密钥签名并广播。那就是基于非托管网关构建的加密大额支付API的真实形态：API自动化提交、验证、状态和网络钩子——它不自动化签名，因为私钥从不存储在服务器上。没有热钱包可以被耗尽，也没有静默自动发送。如果这种权衡听起来可以接受，API将手动工资或联盟运行转化为两到三行代码。

这是一个开发者指南。它复制了来自API文档的确切合同，以便您今天可以根据它进行交付：端点、HMAC签名、Idempotency-Key、严格的422验证、payout.sent网络钩子，以及如何取消释放被保留的余额。如果您想先了解产品概述，请阅读大额支付页面。

为什么它是半自动化的，以及这为什么是安全的胜利

没有任何内容由Web应用程序本身广播。接收地址源自公钥材料；授权支出的私钥保留在您的硬件上，离线。因此，流程故意是两步的。当您提交一个批次——从机柜或通过API——Payora保留总额加上每项移动费用在您的内部余额中，瞬间完成，因此该批次永远不会超支。然后一个人（您或您的操作轮换）在离线状态下签署排队的项目并广播它们。

服务器漏洞无法移动一枚硬币，因为接收API调用的盒子没有任何可以签名的东西。每个批次的成本是一个签名步骤。对于工资、联盟运行和供应商结算来说，这是一个公平的价格，并且它与在没有热钱包的情况下支付数百个钱包中描述的架构相同。绝不要将其建模为“API调用，硬币瞬间消失”——那将是一个不同的、更具风险的产品。

身份验证和请求签名

加密大额支付API使用与Payora其余部分相同的身份验证。每个请求都携带三个头部：X-Payora-Key、X-Payora-Timestamp（Unix秒，±120秒偏差）和X-Payora-Signature。签名是对时间戳、一个字面点和确切的原始请求体进行的HMAC-SHA256：

X-Payora-Signature = hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body))

签署您实际发送的字节，在任何重新序列化之前。如果您的HTTP客户端重新编码JSON，请先捕获原始主体并对其进行哈希。这是用于验证入站网络钩子的相同方案，涵盖在HMAC-SHA256网络钩子签名验证中。

POST /v1/payout：提交一个批次

发送一种货币，最多500个项目，以及一个可选的备注。每个项目是一个地址，一个作为字符串的金额，以及一个可选的标签——当资产需要时的XRP目标标签或XLM备注。

curl -X POST https://api.payora.money/v1/payout \
  -H "X-Payora-Key: pk_live_9f3c8a12" \
  -H "X-Payora-Timestamp: 1753280400" \
  -H "X-Payora-Signature: 7b1e0c4d9a55f2..." \
  -H "Idempotency-Key: payroll-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "items": [
      {"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "250.00"},
      {"address": "TXk9mP2v7wQ3nR5tYb1cD8eF4gH6jK0lMn", "amount": "1800.00", "tag": ""}
    ],
    "note": "七月承包商"
  }'

成功时，您将获得201，并且可以跟踪的批次。总额是金额的总和，费用是您计划的移动费用（免费计划为1.5%）加上硬币’的网络费用，且两者已在您的余额中保留：

{
  "batch_id": "po_7Qd2K8xM4b",
  "status": "pending",
  "currency": "USDT",
  "item_count": 2,
  "total": "2050.00",
  "fee": "20.50",
  "items": [
    {"index": 0, "address": "TR7NHqjeKQ...", "amount": "250.00", "status": "pending"},
    {"index": 1, "address": "TXk9mP2v7w...", "amount": "1800.00", "status": "pending"}
  ]
}

接受支付仍然是0%；移动费用仅在资金离开时适用。网络费用是单独的，并在广播时按链上支付。

严格验证：没有静默丢失的收款人

验证是故意的全有或全无。如果任何地址对于所选网络格式错误，或者任何金额的十进制位数超过硬币支持的位数，则整个批次将被拒绝，并返回422和有问题的索引。没有任何内容被排队，没有任何内容被保留。

HTTP/1.1 422 无法处理的实体
{
  "error": "validation_failed",
  "invalid_items": [3, 17],
  "message": "索引3的地址无效；索引17的金额超过硬币精度"
}

这是您希望在工资中看到的行为。一个安静截断1800.123456789或跳过一行错误的网关将导致支付不足或丢失一个人，您直到有人投诉才会注意到。修复标记的索引并重新提交整个批次。

幂等性：重试永远不会重复支付

网络会超时。中途失败的支付请求盲目重试是危险的，因此发送一个Idempotency-Key头——任何稳定的、唯一的字符串用于该逻辑批次（一个工资周期，一个发票组）。如果带有相同密钥的请求再次到达，Payora将返回原始批次，而不是创建第二个批次。对同一批次的每次重试都重用该密钥；对于真正的新批次使用一个新的密钥。

• 相同的密钥，相同的批次——超时后安全重试；您将获得第一个结果。
• 新密钥——一个新批次，您余额上的新保留。
• 一旦您获得返回的batch_id，请立即存储，以便即使响应丢失也能进行对账。

通过GET /v1/payout/{id}

在操作员签名后，轮询GET /v1/payout/{id}以获取当前状态和每个项目的tx_hash，因为每笔交易被广播。GET /v1/payout列出最近的批次以供仪表板和审计使用。将batch_id和每个项目索引存储在您自己的记录中，以便每个收款人都映射到您可以向他们展示的链上哈希。

需要在签名之前撤回一个？POST /v1/payout/{id}/cancel取消仍在待处理的批次，并完全释放被保留的余额。一旦项目被广播，它们就在链上并且是最终的，就像任何加密交易一样——取消仅在批次待处理时有效。

payout.sent网络钩子

与其永远轮询，不如订阅payout.sent。当操作员广播批次中的每个项目时，Payora会使用与invoice.paid相同的HMAC签名触发一个签名的网络钩子。以相同的方式验证——对时间戳、点、原始主体重新计算签名并在常量时间内进行比较：

$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $webhook_secret);
if (!hash_equals($expected, $signature_header)) { http_response_code(400); exit; }
// payload.event == "payout.sent", payload.batch_id, payload.items[].tx_hash

只有在该检查通过后，您才应标记工资运行完成，发送收据或更新账本。未经验证的网络钩子只是一个不受信任的HTTP请求。

一个最小的集成检查清单

1. 创建一个帐户并在注册处生成API密钥；在您将支付的货币中为内部余额提供资金。
2. 构建原始JSON主体，使用HMAC-SHA256对其进行签名（时间戳 + "." + 主体），附加三个头部以及一个Idempotency-Key。
3. POST /v1/payout；在201时持久化batch_id，在422时修复标记的索引并重新发送。
4. 让您的操作员离线签署并广播排队的批次。
5. 验证payout.sent网络钩子，或轮询GET /v1/payout/{id}，并记录每个tx_hash。

这就是整个循环。API消除了繁琐且容易出错的部分——构建、验证和跟踪一个500行的批次——而离线签名则将真正重要的东西，即您的密钥，置于服务器的不可接触范围内。

开始构建

阅读大额支付API部分的文档，在注册处获取密钥，并在大额支付