API 参考

Saga 支付 API 端点的完整参考

Saga 的支付 API 提供了一个简单、安全的接口来处理稳定币支付。为去中心化网络构建，我们的 API 以最小的集成复杂性处理支付创建、状态跟踪和 webhook 通知。

基础 URL

Sandbox:

https://beta.saga.onl/api/v1

Production:

https://saga.onl/api/v1

POST/pay

创建支付

创建新的支付请求并返回用于区块链交易的支付详情。

请求体

{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "chainId": 11155111,
  "nonce": 42,
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "callbackUrl": "https://your-site.com/webhook/saga",
  "callbackSecret": "your-webhook-secret-key"
}

参数

Name	Type	Required	Description
`transactionHash`	string	Required	Blockchain transaction hash
`chainId`	number	Required	Blockchain chain ID (11155111 for Sepolia, 1 for Mainnet)
`nonce`	number	Required	Transaction nonce for correlation
`payeeAddress`	string	Required	Merchant's wallet address
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals, e.g., "1000000" = $1.00)
`payerAddress`	string	Required	Customer's wallet address
`metadata`	object	Optional	Optional payment metadata
`callbackUrl`	string	Optional	Optional webhook callback URL
`callbackSecret`	string	Optional	Secret key for webhook signature verification (recommended for production)

响应

200Payment created successfully

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "PENDING"
}

400Bad Request - Invalid input

{
  "error": "transactionHash is not in the expected format"
}

响应参数

Name	Type	Required	Description
`paymentId`	string	Required	Unique payment identifier (UUID)
`payeeAddress`	string	Required	Merchant's wallet address
`payerAddress`	string	Required	Customer's wallet address
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals)
`status`	string	Required	Payment status (PENDING, COMPLETED, FAILED)

GET/pay/{paymentId}

获取支付状态

通过 ID 检索支付的当前状态和详情。

参数

Name	Type	Required	Description
`paymentId`	string (UUID)	Required	Unique payment identifier

响应

200Payment status retrieved successfully

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:15Z",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "blockchainTx": {
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "blockNumber": 12345678
  }
}

404Payment not found

{
  "error": "Payment not found"
}

响应参数

Name	Type	Required	Description
`paymentId`	string	Required	Unique payment identifier (UUID)
`payeeAddress`	string	Required	Merchant's wallet address
`payerAddress`	string	Optional	Customer's wallet address (null until payment submitted)
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals)
`status`	string	Required	Payment status (PENDING, COMPLETED, FAILED)
`createdAt`	string	Required	Payment creation timestamp (ISO 8601)
`completedAt`	string	Optional	Payment completion timestamp (ISO 8601)
`metadata`	object	Optional	Payment metadata
`blockchainTx`	object	Optional	Blockchain transaction details (txHash, blockNumber)

支付状态

支付可以具有以下状态之一：

待处理

支付已创建但尚未在区块链上确认

已完成

支付已在区块链上成功确认

失败

由于交易失败或超时导致支付失败

错误代码

Saga API 返回标准 HTTP 状态代码和描述性错误消息。所有错误响应都遵循一致的格式。

400错误请求

无效的请求参数或数据格式

{
  "error": "transactionHash is not in the expected format"
}

404未找到

支付 ID 不存在或无效

{
  "error": "Payment not found"
}

500内部服务器错误

意外的服务器错误

{
  "error": "Internal server error"
}

Webhooks

当支付状态更改时，Saga 会向您的回调 URL 发送 webhook 通知。Webhooks 在支付完成、失败和其他状态更新时发送。

何时发送 Webhooks

支付状态更新

在区块链交易确认后，当支付状态从待处理变为已完成或失败时，立即发送 webhooks

重试尝试

如果您的端点未成功响应，webhooks 会重试

Webhook 负载

Webhook 负载包含完整的支付状态响应：

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "blockchainTx": {
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "blockNumber": 12345678
  }
}

Webhook 标头

Saga 在每个 webhook 请求中包含额外的标头：

Content-Type: application/json

X-Saga-Callback-Attempt: 1

X-Saga-Sent-At: 2024-01-15T10:30:00Z

X-Saga-Callback-Secret: your-webhook-secret-key

Webhook 安全

🔒 最佳实践：始终使用 GET 请求验证

无论您是否使用 callbackSecret，始终执行 GET 请求到/pay/{paymentId} 以验证支付状态。

GET /pay/550e8400-e29b-41d4-a716-446655440000

这确保您正在处理最新的支付状态并防止重放攻击。

Webhook 验证

当您在支付请求中提供 callbackSecret 时，Saga 会在 webhook 标头中包含此密钥以进行额外验证：

X-Saga-Callback-Secret: your-webhook-secret-key

这有助于验证 webhook 的真实性，但上述 GET 请求验证仍然是主要的安全措施。

重试策略

• Webhooks 最多重试 5 次（可通过 MAX_ATTEMPTS 配置）

• 每次重试尝试在 X-Saga-Callback-Attempt 标头中包含尝试次数

• 在最大尝试次数后失败的 webhooks 被标记为失败

• 您的端点应始终返回 HTTP 200，无论处理成功或失败

• 超时设置为 5 秒（可通过 CALLBACK_TIMEOUT_MS 配置）

Found a bug or have a question?

Report an Issue