> For the complete documentation index, see [llms.txt](https://docs.jgopay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jgopay.com/jian-ti-zhong-wen/create-payment.md). # 创建支付 ## 接口 ```http POST /payment/request Authorization: Bearer Content-Type: application/json ``` ## 请求参数 | 字段 | 类型 | 必填 | 说明 | | ---------------- | ------ | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | number | 是 | 支付金额（见[金额规则](#金额规则)） | | `currency` | string | 否 | ISO 4217 货币代码（`MYR`）。默认为您配置的货币 | | `reference_id` | string | 是 | 您的唯一订单号/发票号（最长 100 字符，**仅限字母和数字**） | | `customer_name` | string | 是 | 客户姓名 | | `customer_phone` | string | 是 | 客户手机号（含国家区号，不带 `+`） | | `callback_url` | string | 否 | 支付结果回调地址。未传时使用商户默认回调地址 | | `redirect_url` | string | 否 | 支付完成后客户跳转的地址 | | `payment_method` | string | 是 | 支付方式代码（`QR_PAYMENT`、`BANK_TRANSFER`、`MOBILE_WALLET`） | | `metadata` | object | 否 | 随交易存储的自定义键值数据。**不会**在回调中返回 — 请用 `reference_id` 做关联。**`BANK_TRANSFER` 时必填：** 需包含 `provider_channel_id`（见[支付方式](https://docs.jgopay.com/jian-ti-zhong-wen/pages/SbTu79bJ3Qq30bam3c80#fpx-银行代码)） | > **安全要求：** 生产环境中 `callback_url` 和 `redirect_url` 必须使用 HTTPS（`https://`）。HTTP 地址会被拒绝并返回 HTTP 422。这可以防止包含支付状态和签名的回调数据被截获。 > **警告：** `redirect_url` 不会与预先登记的域名做校验。如果您的 API 密钥泄露，攻击者可以创建支付并在支付后将您的客户重定向到钓鱼网站。缓解措施： > > * API 密钥仅限后端服务器使用 — 切勿暴露在客户端代码中 > * 监控支付创建日志中异常的 `redirect_url` 值 > * 怀疑泄露时立即轮换 API 密钥（见[身份认证](https://docs.jgopay.com/jian-ti-zhong-wen/pages/yHdOmArxE1211bmtApyH#紧急吊销)） ## 字段校验 | 字段 | 规则 | 说明 | | ---------------- | ------------------------ | -------------------------------------- | | `reference_id` | **仅限字母和数字**（a-z、A-Z、0-9） | 不允许空格、连字符或特殊字符，否则返回 `VALIDATION_ERROR` | | `customer_phone` | 字符串，1-50 个字符 | 含国家区号，不带 `+`（例如 `60123456789`） | | `amount` | 正数 | 最多 2 位小数 | > **`BANK_TRANSFER`（FPX）：** 使用 `payment_method: "BANK_TRANSFER"` 时，必须在 `metadata.provider_channel_id` 中传入客户的银行代码。完整列表见[支付方式](https://docs.jgopay.com/jian-ti-zhong-wen/pages/SbTu79bJ3Qq30bam3c80#fpx-银行代码)。 ## 金额规则 | 货币 | 格式 | 最小金额 | 最大金额 | | ------- | -------- | ----- | ---------- | | **MYR** | 最多 2 位小数 | 5 MYR | 50,000 MYR | ## 响应 您将收到网关相关数据： ```json { "status": "success", "data": { "payment_id": "PAY_MYR12346", "payment_url": "https://payment.yourbrand.com/p/MYR12346", "status": "PROCESSING", "amount": 100.00, "currency": "MYR", "reference_id": "ORDER20260325002", "expires_in": 1800, "expires_at": "2026-03-25T12:30:00Z", "gateway": { "behavior": "REDIRECT_EXTERNAL", "redirect_url": "https://gateway.example.com/pay/xyz789", "qr_data_string": null } } } ``` ### 响应字段 | 字段 | 类型 | 说明 | | ---------------------- | ------ | -------------------------------------------------- | | `payment_id` | string | 支付唯一标识 | | `payment_url` | string | 支付页面 URL — `QR_PAYMENT` 时引导客户到此地址 | | `status` | string | 初始状态（`PROCESSING`） | | `amount` | number | 确认的支付金额 | | `currency` | string | 货币代码 | | `reference_id` | string | 您的订单号 | | `expires_in` | number | 距离过期的秒数 | | `expires_at` | string | 过期时间（ISO 8601） | | `gateway.behavior` | string | 响应的处理方式 | | `gateway.redirect_url` | string | 跳转地址 — `BANK_TRANSFER` 和 `MOBILE_WALLET` 时引导客户到此地址 | ### 客户应跳转到哪个地址 | `payment_method` | 引导客户到 | | ---------------- | ---------------------------------- | | `QR_PAYMENT` | `payment_url` — 支付页面显示 DuitNow 二维码 | | `BANK_TRANSFER` | `gateway.redirect_url` — 银行授权页面 | | `MOBILE_WALLET` | `gateway.redirect_url` — TNG 授权页面 | ## 查询支付状态 查询某笔支付的当前状态。 ```http GET /payment/status/:identifier Authorization: Bearer ``` `:identifier`可传 JGoPay 的 `payment_id`（`PAY_xxx`），也可传您自己的 `reference_id` — 无需保存我们的支付标识即可查询。`reference_id` 仅含字母数字，无需 URL 编码。若匹配到 `payment_id` 则以其为准；否则在您的账户内按 `reference_id` 查询。 ### 响应 ```json { "status": "success", "data": { "payment_id": "PAY_MYR12345", "reference_id": "ORDER20260325001", "amount": 100.00, "currency": "MYR", "status": "SUCCESS", "gateway_reference": "TXN_20260325_ABC123", "created_at": "2026-03-25T12:00:00Z", "completed_at": "2026-03-25T12:15:30Z", "expires_at": "2026-03-25T12:30:00Z" } } ``` | 字段 | 类型 | 说明 | | ------------------- | ------ | -------------------------------------------------------------------------------- | | `payment_id` | string | JGoPay 支付标识 | | `reference_id` | string | 您的原始订单号 | | `amount` | number | 支付金额 | | `currency` | string | 货币代码 | | `status` | string | 当前状态（`PENDING`、`PROCESSING`、`SUCCESS`、`FAILED`、`EXPIRED`、`CANCELLED`、`REFUNDED`） | | `gateway_reference` | string | 网关的交易流水号（处理前为 `null`） | | `created_at` | string | 创建时间（ISO 8601） | | `completed_at` | string | 完成时间（未完成为 `null`） | | `expires_at` | string | 过期时间（未设置为 `null`） | > 未收到回调时可用此接口兜底核实支付状态。请勿将其作为获取状态的主要手段 — 应以[回调通知](/jian-ti-zhong-wen/webhooks.md)为准。 ## 网关行为 | 行为 | 处理方式 | 适用方式 | | ------------------- | ------- | ------------------ | | `REDIRECT_EXTERNAL` | 跳转到网关页面 | DuitNow QR、FPX、TNG | 所有 MYR 支付方式均采用跳转流程 — 各方式的详细说明见[支付方式](/jian-ti-zhong-wen/payment-methods.md)。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.jgopay.com/jian-ti-zhong-wen/create-payment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.