> For the complete documentation index, see [llms.txt](https://docs.topay.mobi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.topay.mobi/cn/reference/api-reference/fiat-payments/payin.md).

# 法币代收 API

{% hint style="warning" %}
每个请求都必须包含[公共参数](/cn/reference/api-reference/common-parameters.md)。
{% endhint %}

通过直连接入创建法币代收订单。

<mark style="color:green;">`POST`</mark> `https://api.topay.mobi/v1/order/pay`

#### 请求体 <a href="#request-body" id="request-body"></a>

| 名称                                                  | 类型         | 说明                                                                                  |
| --------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark>       | String     | 商户提供的外部交易 ID                                                                        |
| payment\_method<mark style="color:red;">\*</mark>   | String     | 支付方式：法币直连接入使用 `direct`                                                              |
| amount<mark style="color:red;">\*</mark>            | String     | 订单金额                                                                                |
| currency<mark style="color:red;">\*</mark>          | String     | 订单币种                                                                                |
| remark                                              | String     | 收银台页面展示的商品详细信息                                                                      |
| product\_name<mark style="color:red;">\*</mark>     | String     | 收银台页面展示的商品名称                                                                        |
| return\_url                                         | String     | 付款完成后的网页跳转地址，按需提供                                                                   |
| notify\_url                                         | String     | Webhook 通知地址                                                                        |
| payment\_channel                                    | String     | 支付方式为 direct 时必填，参阅[枚举](/cn/reference/enums/payment-type.md)                        |
| payment\_type                                       | String     | 支付方式为 direct 时必填，参阅[枚举](/cn/reference/enums/payment-type.md)                        |
| customer\_ref\_id<mark style="color:red;">\*</mark> | String     | 客户唯一标识                                                                              |
| pay\_currency                                       | String     | 支付币种                                                                                |
| customer                                            | JSONString | 客户信息，签名前使用 `JSON.toJSONString(customer)` 序列化。下方列出的国家及渠道组合要求提供此字段。                   |
| customer.email                                      | String     | 客户电子邮箱                                                                              |
| customer.phone                                      | String     | 客户手机号码                                                                              |
| customer.name                                       | String     | 客户姓名                                                                                |
| customer.document\_id                               | String     | 客户身份证件号码；巴西 PIX 渠道必填。                                                               |
| customer.document\_type                             | String     | 客户身份证件类型；巴西 PIX 示例使用 `CPF`；秘鲁（country=PE）取值：DNI、RUC、CE、PASSPORT、MILITARY、PAR、OTHER。 |
| customer.userLevel                                  | String     | 客户用户分级；土耳其（country=TR）必填，取值 `FTD`、`STD`、`VIP`（真实用户分级，渠道风控要求）。                       |

`customer.*` 各行描述序列化 JSON 字符串内部的字段，并非独立的顶层请求参数。

| 国家 / 渠道     | 客户信息要求                                                                                                                                         |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 印度尼西亚 / 钱包  | `customer` 和 `customer.phone` 必填。                                                                                                              |
| 印度 / UPI 钱包 | `customer` 必填。手机号码为 10 位，不包含国家代码，且不以 0 开头。                                                                                                     |
| 巴西 / PIX    | `customer.name`、`customer.phone`、`customer.email`、`customer.document_id` 和 `customer.document_type` 必填。本示例的证件类型使用 `CPF`。                       |
| 美国 / 信用卡    | `customer.name`、`customer.phone` 和 `customer.email` 必填。                                                                                        |
| 秘鲁 / 收银台    | `customer.name`、`customer.phone`、`customer.email`、`customer.document_id` 和 `customer.document_type` 均为选填、建议提供；未提供时由系统自动生成。                     |
| 土耳其 / 银行转账  | `customer` 必填：`customer.name`（付款人真实完整姓名）与 `customer.userLevel`（`FTD` / `STD` / `VIP`）必填；`customer_ref_id`（真实用户 ID）必填。渠道按真实信息风控，缺失或不完整会掉单 / 退回。 |

请只序列化一次 `customer`，然后在签名和请求体中使用完全相同的字符串。参阅[身份认证](/cn/integration/authentication.md#customer-serialization)。

此流程中请将 `payment_method` 设为 `direct`。渠道特定要求请参阅各国示例。

## 响应示例 <a href="#response-example" id="response-example"></a>

```json
{"code":"200",
 "data":{
   "request_id":"1675157000687",
   "partner_id":"2000051",
   "order_no":"2023013120000600262092321146",
   "currency":"IDR",
   "order_amount":"0.3",
   "status":11,
   "payment_method":"direct",
   "checkout_url":"https://example.com/checkout/example",
   "wallet_url":"http://ovo.com/vfsjdkfdst",
   "qrcode_string":"abccddafdsfdasfsfas",
   "account_name":"BCA",
   "account_number":"2342432434343",
   "account_type":"virtual_account"
 },
 "message":"success"
 }
```

## 示例

* [示例](/cn/reference/api-reference/fiat-payments/payin/country-examples.md)