> 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-withdrawal.md).

# 创建提现

发起一笔提现（代付），付款至马来西亚银行账户或电子钱包。

## 接口

```http
POST /payment/withdraw
Authorization: Bearer <access_token>
Content-Type: application/json
```

## 请求参数

| 字段               | 类型     | 必填 | 说明                                                   |
| ---------------- | ------ | -- | ---------------------------------------------------- |
| `amount`         | number | 是  | 提现金额（最多 2 位小数，**50.00 – 50,000.00 MYR**）             |
| `currency`       | string | 是  | ISO 4217 货币代码（`MYR`）                                 |
| `reference_id`   | string | 是  | 您的唯一提现单号（最长 100 字符，**仅限字母和数字**）                      |
| `bank_code`      | string | 是  | 银行或电子钱包代码（见[银行代码](/jian-ti-zhong-wen/bank-codes.md)） |
| `account_number` | string | 是  | 收款人银行账号                                              |
| `account_name`   | string | 是  | 收款人账户姓名                                              |
| `method`         | string | 是  | MYR 提现固定为 `BANK`                                     |
| `phone_number`   | string | 否  | 收款人手机号（部分网关要求）                                       |
| `callback_url`   | string | 否  | 提现结果回调地址。未传时使用商户默认回调地址                               |
| `metadata`       | object | 否  | 随提现存储的自定义键值数据。**不会**在回调中返回 — 请用 `reference_id` 做关联   |

> **安全要求：** 生产环境中 `callback_url` 必须使用 HTTPS（`https://`）。HTTP 地址会被拒绝并返回 HTTP 422。这可以防止包含提现状态和账户信息的回调数据被截获。

## 字段校验

| 字段               | 规则                             | 说明                                        |
| ---------------- | ------------------------------ | ----------------------------------------- |
| `amount`         | 50.00 – 50,000.00 MYR，最多 2 位小数 | 超出范围将返回 `INVALID_AMOUNT`                  |
| `reference_id`   | **仅限字母和数字**（a-z、A-Z、0-9）       | 不允许空格、连字符或特殊字符                            |
| `account_number` | 字符串，1-50 个字符                   | 银行账号或电子钱包号                                |
| `account_name`   | 字符串，1-100 个字符                  | 必须与账户持有人一致                                |
| `bank_code`      | 必须是有效的 MYR 代码                  | 见[银行代码](/jian-ti-zhong-wen/bank-codes.md) |

## 请求示例

```json
{
  "amount": 500.00,
  "currency": "MYR",
  "reference_id": "WD20260325001",
  "bank_code": "MY_MBB",
  "account_number": "1234567890",
  "account_name": "Ahmad bin Ali",
  "method": "BANK"
}
```

> 电子钱包付款（如 Touch 'n Go）时，`account_number` 填钱包注册号码，`bank_code` 填钱包代码（如 `MY_TNG`）— `method` 仍为 `BANK`。

## 响应

```json
{
  "status": "success",
  "data": {
    "payment_id": "PAY_WD1A2B3C4D",
    "reference_id": "WD20260325001",
    "amount": 500.00,
    "currency": "MYR",
    "transaction_type": "WITHDRAWAL",
    "status": "PENDING",
    "gateway_reference": null,
    "created_at": "2026-03-25T10:30:00Z"
  }
}
```

### 响应字段

| 字段                  | 类型     | 说明                      |
| ------------------- | ------ | ----------------------- |
| `payment_id`        | string | 提现唯一标识                  |
| `reference_id`      | string | 您的提现单号                  |
| `amount`            | number | 确认的提现金额                 |
| `currency`          | string | 货币代码                    |
| `transaction_type`  | string | 固定为 `"WITHDRAWAL"`      |
| `status`            | string | 初始状态（`PENDING`）         |
| `gateway_reference` | string | 网关流水号（初始为 `null`，处理时填充） |
| `created_at`        | string | 创建时间（ISO 8601）          |

## 状态流转

```
PENDING → PROCESSING → SUCCESS
                     → FAILED
```

| 状态           | 说明             |
| ------------ | -------------- |
| `PENDING`    | 提现请求已创建，排队等待处理 |
| `PROCESSING` | 网关正在处理提现       |
| `SUCCESS`    | 资金已转入收款账户      |
| `FAILED`     | 提现被拒绝或失败       |

提现到达终态（`SUCCESS` 或 `FAILED`）时，您会收到[回调通知](/jian-ti-zhong-wen/webhooks.md)。

## 提现错误

| 错误代码                   | HTTP 状态码 | 说明                                                 |
| ---------------------- | -------- | -------------------------------------------------- |
| `VALIDATION_ERROR`     | 400      | 一个或多个字段校验失败                                        |
| `INVALID_AMOUNT`       | 400      | 金额超出允许范围                                           |
| `INVALID_BANK_CODE`    | 400      | 不支持的银行代码。见[银行代码](/jian-ti-zhong-wen/bank-codes.md) |
| `DUPLICATE_REFERENCE`  | 409      | `reference_id` 已被使用                                |
| `NO_GATEWAY_AVAILABLE` | 503      | 无可用的提现网关                                           |
| `GATEWAY_ERROR`        | 502      | 上游网关返回错误                                           |


---

# 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-withdrawal.md?ask=<question>&goal=<endgoal>
```

`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.