表单提交支付

概述

表单提交支付是最低摩擦的 MakePay 集成方式。普通 HTML 表单把订单字段提交给 MakePay，MakePay 创建托管结账支付链接，并把购物者重定向到支付页面。

当你的网站可以渲染 HTML 表单，但暂时不想编写服务器端 API 客户端时使用它。对于高级电商平台、插件、SDK 或服务器订单系统，优先使用支付链接 API、OAuth 应用或官方店铺模块。

安全模型

表单 action 使用 MakePay API key ID 作为公开表单密钥：

https://makepay.io/gateway/pay/{makepayKeyId}

API secret 不会在浏览器中使用。启用表单前，请打开 MakeCrypto 仪表盘，创建或选择 MakePay 集成密钥，并在 Allowed origins 中加入精确网站 origin，例如：

https://merchant.example

MakePay 只接受 Origin 或 Referer 与允许 origin 匹配的浏览器提交。没有 allowed origins 的密钥会被表单网关拒绝。

基础表单

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="title" value="Order #1042" />
  <input type="hidden" name="description" value="Checkout for order #1042" />
  <input type="hidden" name="amount" value="129.99" />
  <input type="hidden" name="fiat_currency" value="USD" />
  <input type="hidden" name="currency" value="USDT" />
  <input type="hidden" name="order_id" value="order_1042" />
  <input type="hidden" name="customer_email" value="buyer@example.com" />
  <input
    type="hidden"
    name="success_url"
    value="https://merchant.example/orders/1042/success"
  />
  <input
    type="hidden"
    name="failure_url"
    value="https://merchant.example/orders/1042/failed"
  />
  <input
    type="hidden"
    name="return_url"
    value="https://merchant.example/orders/1042"
  />
  <input type="hidden" name="metadata[cart_id]" value="cart_7M2V" />

  <button type="submit">Pay with crypto</button>
</form>

购物者提交表单后，MakePay 会创建一次性支付链接，并用 303 See Other 响应托管结账 URL。

字段

字段	必填	说明
amount	是	正数十进制金额，最多 8 位小数。
currency	否	首选加密结算币种，例如 USDT、USDC、BTC、ETH、LTC 或 DOGE。
asset	否	当同一 symbol 存在于多条链上时，使用精确目标资产标识符。
fiat_currency	否	USD 或 EUR 等展示币种。也接受 fiatCurrency、display_currency 和 displayCurrency。
title	否	结账标题。也接受 name 和 label。
description	否	结账描述。
order_id	否	商户订单或发票 ID。也接受 orderId、invoice_id 和 invoiceId。
client_id	否	商户客户 ID。也接受 clientId。
customer_email	否	客户邮箱。也接受 customerEmail 和 email。
customer_name	否	客户姓名。也接受 customerName。
return_url	否	通用返回目标的绝对 http 或 https URL。
success_url	否	成功付款后使用的绝对 http 或 https URL。
failure_url	否	付款失败和表单校验错误时使用的绝对 http 或 https URL。
expiration_time	否	15m、1h、12h、24h、72h 或 never。默认 12h。
send_payment_request_email	否	设为 true、1、yes 或 on 时同时发送支付请求邮件。需要 customer_email。
metadata[key]	否	额外字符串 metadata。key 可包含字母、数字、_、.、: 和 -，最多 25 个 metadata 字段。

动态表单

请在服务器端用真实订单金额和订单 ID 渲染表单。除非服务器会校验或重建金额，否则不要信任客户可编辑页面提交的金额。

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="amount" value="{{ order.total }}" />
  <input type="hidden" name="fiat_currency" value="{{ order.currency }}" />
  <input type="hidden" name="order_id" value="{{ order.id }}" />
  <input type="hidden" name="customer_email" value="{{ customer.email }}" />
  <button type="submit">Pay with MakePay</button>
</form>

重定向行为

成功的表单提交会重定向到托管 MakePay 结账。success_url、failure_url 和 return_url 字段会保存在支付链接上，并由结账流程在付款后使用。

如果校验失败且 failure_url 有效，MakePay 会带着这些查询参数重定向回来：

?makepay_status=error&makepay_error=invalid_amount&makepay_error_message=...

Origin 或认证失败会显示 MakePay 错误页，而不会重定向到不可信 URL。

Webhook

使用 MakePay Webhook 更新最终订单状态。客户重定向有助于用户体验，但 Webhook 才是支付状态、少付、多付、退款和过期的可靠事实来源。

请参阅 Webhook 指南了解签名验证和事件载荷。

故障排查

• Allowed origin required：把你的网站 origin 加到 MakePay 集成密钥。
• Origin not allowed：提交表单的域名、协议或端口与配置的 allowed origin 不一致。
• invalid_amount：amount 缺失、为零、为负数或不是十进制数。
• invalid_currency：请使用 USD、USDT 或 BTC 等币种符号。
• invalid_url：重定向字段必须是绝对 http 或 https URL。
• onboarding_required：商户尚未配置默认 MakePay 结算资产。