# 收款人创建

收款人创建

Endpoint: POST /api/v2/merch/beneficiary/create
Version: 1.0.0

## Header parameters:

  - `X-Merch-Id` (string)
    Example: "M24061911365700670"

## Request fields (application/json):

  - `request_id` (string, required)
    请求号，请求方系统内唯一

  - `type` (string, required)
    目的(必填): PAYMENT-收款、WITHDRAWAL-提现

  - `beneficiary` (object, required)
    收款人信息

  - `beneficiary.purpose` (string, required)
    收款类型 PFG-货款 LWF-物流仓储费 ASF-广告服务费 TSF-技术服务费 CSF-咨询服务费 OTHER-其他 数据字典:PAYEE_TYPE
    Enum: "PFG", "LWF", "ASF", "TSF", "CSF", "OTHER"

  - `beneficiary.purpose_desc` (string)
    收款类型说明,其他收款类型的时候需要填(最长100字符)，purpose为OTHER时必填

  - `beneficiary.country` (string, required)
    国家代码,使用ISO3166-2标准2位国家代码,非制裁国家(见附录)

  - `beneficiary.industry` (integer)
    主营行业(见附件)，对公账户且为收款人时必填

  - `beneficiary.nick_name` (string)
    账户昵称(最长100字符)

  - `beneficiary.first_name` (string)
    受益人first name(境外收款人对私必填)(最长100字符)

  - `beneficiary.last_name` (string)
    受益人last name(境外收款人对私必填)(最长100字符)

  - `beneficiary.doc_type` (string)
    证件类型(境内个人账户必填), 境内个人账户必填且为ID_CARD

  - `beneficiary.id_number` (string)
    证件号码(境内个人账户必填)(最长100字符)

  - `beneficiary.uni_social_credit` (string)
    统一社会信用代码(境内对公账户必填)(最长18字符)

  - `beneficiary.address` (object)
    受益人地址信息

  - `beneficiary.address.province` (string, required)
    州/省(美国/加拿大/墨西哥且银行币种账户非CNY必填)

  - `beneficiary.address.city` (string, required)
    城市(境外必填)

  - `beneficiary.address.zipcode` (string, required)
    邮编(境外必填)

  - `beneficiary.address.address1` (string, required)
    银行账户持有人地址(境外必填)

  - `beneficiary.address.address2` (string)
    地址行2

  - `bank_acc` (object, required)
    银行账户信息

  - `bank_acc.country` (string, required)
    国家代码,使用ISO3166-2标准2位国家代码,非制裁国家(见附录)

  - `bank_acc.currency` (string, required)
    币种: EUR-欧元, USD-美元, CNY-人民币, GBP-英镑, JPY-日元, AUD-澳元, CAD-加元, SGD-新加坡元, HKD-港币, PHP-菲律宾比索, CNH-离岸人民币
    Enum: "EUR", "USD", "CNY", "GBP", "JPY", "AUD", "CAD", "SGD", "HKD", "PHP", "CNH"

  - `bank_acc.acc_name` (string, required)
    账户名称(最长100字符)

  - `bank_acc.acc_type` (string, required)
    账户类型: PRIVATE-个人账户, COMPANY-企业对公
    Enum: "PRIVATE", "COMPANY"

  - `bank_acc.acc_no` (string)
    银行账号，acc_no和iban二选一

  - `bank_acc.payment_type` (string, required)
    支付清算网络：LOCAL-本地支付，SWIFT-国际支付
    Enum: "LOCAL", "SWIFT"

  - `bank_acc.routing_code_type1` (string)
    LOCAL清算网络时必须(随业务发展后会扩展枚举值）：ABA、SORT_CODE、BANK_CODE(境内详见银行编码附件，境外如加拿大如实填写)

  - `bank_acc.routing_code_value1` (string)
    routing_code_type1不为空时必须

  - `bank_acc.routing_code_type2` (string)
    LOCAL清算网络子类型(随业务发展后会扩展枚举值）：BRANCH_BANK_CODE(境内详见银行编码附件，境外如加拿大如实填写)

  - `bank_acc.routing_code_value2` (string)
    routing_code_type2不为空时必须

  - `bank_acc.iban` (string)
    IBAN，欧元区账户特有，acc_no和iban二选一

  - `bank_acc.bic_swift` (string)
    swift code或bic，SWIFT清算网络时其它国家与地区均需要上传该字段(只支持8位或11位)

  - `bank_acc.bank_acc_type` (string)
    银行账户类型 CHECKING-支票 SAVINGS-储蓄卡
    Enum: "CHECKING", "SAVINGS"

  - `bank_acc.bank_addr` (string)
    开户银行详细地址(境外账户必填)(最长100字符)

  - `bank_acc.bank_name` (string)
    开户银行名称(境外账户必填; 最长100字符)

  - `bank_acc.branch_bank_name` (string)
    开户银行支行名称(最长100字符)

  - `bank_acc.phone` (string)
    银行预留手机号(大陆人民币对私提现)

  - `bank_acc.province` (string)
    开户银行所属省份(境内企业对公账户必填, 见附件)

  - `bank_acc.city` (string)
    开户银行所属城市(境内企业对公账户必填, 见附件)

  - `bank_acc.district` (string)
    开户银行所属区(境内企业对公账户必填, 见附件)

  - `attachment` (object)
    其他文件附件

  - `attachment.other_file_ids` (array)
    附件文件id 最多7个

  - `attachment.contract_file_id` (integer)
    合同文件-上传文件接口返回的id(目的为收款时, 合同/PI/物流文件必传其一)

  - `attachment.logistics_file_id` (integer)
    物流文件-上传文件接口返回的id(目的为收款时, 合同/PI/物流文件必传其一)

  - `attachment.pi_file_id` (integer)
    PI文件-上传文件接口返回的id(目的为收款时, 合同/PI/物流文件必传其一)

## Response 200 fields (*/*):

  - `msg` (string)
    结果说明，失败时不为空

  - `payee_id` (string)
    收款人id, 仅创建成功并审核通过后返回；付款时可通过指定收款人 id 发起付款

  - `status` (string, required)
    付款人审核状态 PENDING-待审核 NORMAL-正常 REJECTED-审核未通过
    Enum: "PENDING", "NORMAL", "REJECTED"

## Response 400 fields (*/*):

  - `ret_code` (string, required)
    代表请求处理的结果

  - `ret_msg` (string, required)
    代表请求处理的结果消息

## Response 401 fields (*/*):

  - `ret_code` (string, required)
    代表请求处理的结果

  - `ret_msg` (string, required)
    代表请求处理的结果消息

## Response 404 fields (*/*):

  - `ret_code` (string, required)
    代表请求处理的结果

  - `ret_msg` (string, required)
    代表请求处理的结果消息

## Response 429 fields (*/*):

  - `ret_code` (string, required)
    代表请求处理的结果

  - `ret_msg` (string, required)
    代表请求处理的结果消息

## Response 500 fields (*/*):

  - `ret_code` (string, required)
    代表请求处理的结果

  - `ret_msg` (string, required)
    代表请求处理的结果消息