支付

结账流程

创建会话后，您的客户会在托管结账页面的 checkout_url 上完成支付。该页面负责收集 UPI 支付信息、交易参考号和可选的凭证，您无需自行构建这些步骤。

客户需要执行的操作

在结账页面上，客户通过 UPI 支付页面显示的 amount，然后从其支付应用中提交 12 位交易参考号（UTR）。我们会将该参考号与入账的银行款项进行匹配，并确认支付。

后续端点

这些端点为结账页面提供支持。它们使用 URL 中的会话令牌，不需要您的 API 密钥。托管结账页面会代您调用这些端点；此处记录它们是为了帮助您了解完整的生命周期。

提交 UTR

POST /payments/session/{session_token}/submit-utr

请求体：{"utr":"312482855519"}。成功时返回 {"status":"UTR_SUBMITTED","message":"UTR received — verifying payment"}。

情况

状态

响应

缺少 UTR

400

{"error":"utr required"}

UTR 格式无效

422

{"error":{"code":"INVALID_UTR_FORMAT","message":"That doesn't look like a UTR — check the 12-digit reference number in your payment app"}}

未知会话

404

{"error":"Session not found"}

会话已处于最终状态

409

{"error":"Session is already <STATUS>"}

会话已过期

410

{"error":"Session expired"}

同一会话每分钟提交次数超过 10 次

429

{"error":{"code":"UTR_SUBMISSION_RATE_LIMITED","message":"Too many UTR submissions. Please wait a minute and try again."}}

上传支付凭证

POST /payments/session/{session_token}/proof

以 multipart/form-data 格式发送，文件字段名为 proof。支持 JPG、PNG、WebP 或 HEIC，文件大小上限为 5 MB。成功时返回 {"ok":true,"uploadedAt":"..."}。每个会话 15 分钟内最多上传 5 次，每个 IP 地址每分钟最多上传 10 次。

取消会话

POST /payments/session/{session_token}/cancel

无需请求体。只有状态为 CREATED 或 UTR_SUBMITTED 的会话可以取消；会话将变为 FAILED，并发送 FAILED Webhook。

情况

状态

响应

未知会话

404

{"error":"Session not found"}

当前状态无法取消

409

{"error":"Cannot cancel session with status <STATUS>"}

这对您有帮助吗？
这对您有帮助吗？