创建 Batch Transfer 对象

创建一个 batch transfer 对象来发起批量企业付款。注:微信服务商模式商户暂不支持企业付款。

请求参数描述
app required string批量企业付款对应的 app 对象 id,查看如何获取App ID
batch_no required string批量企业付款批次号,11 ~ 32 位,允许字母和英文。
channel required string渠道参数,目前支持alipay(支付宝,包含 mapi 和 openapi 接口)、unionpay(银联电子代付)、wx(微信 App)、wx_pub(微信公众号)、wx_lite(微信小程序)、allinpay(通联代付)、jdpay(京东代付)和balance(余额)。
amount required int批量企业付款总金额,单位为分。
description required string批量企业付款描述,最多 200 个字节。
recipients required string接收者信息。具体参考下表的针对各渠道的 recipients 参数说明
type required string付款类型,取值范围:b2c(打款给个人用户)和 b2b(打款给企业用户)。当前 wx、wx_pub、wx_lite、balance 仅支持:b2c ;alipay、unionpay、allinpayjdpay支持:b2b、b2c。
currency optional string三位 ISO 货币代码,人民币为 cny
metadata optional hash参考元数据

recipients 参数说明

alipay 渠道
参数描述
account required string接收者支付宝账号。
amount required int金额,单位为分
name required string接收者姓名。在 alipay 为 mapi 接口时必填,在 alipay 为 openapi 接口时选填。
description optional string批量企业付款描述,最多 200 字节。
account_type optional string账户类型,alipay openapi 渠道会用到此字段。默认值:"ALIPAY_LOGONID"。ALIPAY_USERID:支付宝账号对应的支付宝唯一用户号,以 2088 开头的 16 位纯数字组成;ALIPAY_LOGONID:支付宝登录号,支持邮箱和手机号格式。
order_no optional string订单号, 1 ~ 64 位不能重复的数字字母组合。

unionpay 渠道
参数描述
account required string接收者银行卡账号。
amount required int付款金额,单位为分。
name required string接收者姓名。
description optional string批量企业付款描述,最多 200 字节。
open_bank optional string1~15位,开户银行。
open_bank_code optional string4位,开户银行编号,详情请参考银联电子代付银行编号说明
order_no optional string订单号,1 ~ 16 位不能重复的数字字母组合。

注: open_bank_codeopen_bank 两个参数必传一个,建议使用 open_bank_code,若都传参则优先使用 open_bank_code 读取规则。


wx、wx_pub、wx_lite 渠道
参数描述
open_id required string接收者的 open_id。点此参考如何获取open_id
amount required int金额,单位为分。
name conditional string收款人姓名。当该参数为空,则不校验收款人姓名。使用企业付款至个人银行卡时,该参数必传。
description optional string不填默认使用外层参数中的 description 最多 99 个英文和数字的组合或最多 33 个中文字符,不可以包含特殊字符。
force_check optional boolean是否强制校验收款人姓名。仅当 name 参数不为空时该参数生效。使用企业付款至个人银行卡时,该参数无效。
order_no optional string订单号,1 ~ 32 位不能重复的数字字母组合。
account optional,string收款人银行卡号。传入该参数时,表示使用企业付款至个人银行卡。不能与 open_id 参数同时传入。
open_bank_code conditional,string开户银行编号。使用企业付款至个人银行卡时,该参数必传。详情请参考微信企业付款银行编号说明

allinpay 渠道
参数描述
account required string接收者银行卡账号。
amount required int付款金额,单位为分。
name required string接收者姓名。
open_bank_code required string4位,银行编号。详情请参考通联代付银行编号说明
business_code optional string5位业务代码,根据通联业务人员提供,不填使用通联提供默认值 09900。详情请参考通联代付业务代码说明
description optional string批量企业付款描述,最多 30 个 Unicode 字符。
card_type optional int银行卡号类型。0:银行卡、1:存折、2:信用卡,不填默认使用银行卡。
order_no optional string订单号,20 ~ 40 位不能重复的数字字母组合(必须以通联的商户号开头,建议组合格式:通联商户号 + 时间戳 + 固定位数顺序流水号,不包含+号),这里不传的话程序会调用商户的通联商户号加上随机数自动生成 order_no。
sub_bank conditional,stringB2B 转账必填,1~80位,开户行详细名称,也叫网点,如:中国建设银行广州东山广场分理处。详情请下载 支付行号
sub_bank_code conditional,stringB2B 转账必填,1~12位,支付行号。详情请下载 支付行号
prov conditional,stringB2B 转账必填,1~20位,省份,不带 “省” 或 “自治区”,需填写成:广东、广西、内蒙古等。详情请参考 中国邮政区号表 内的「省洲名称」列的内容填写。
city conditional,stringB2B 转账必填,1~40位,城市,不带 “市”,需填写成:广州、南宁等。如果是直辖市,则填区,如北京(市)朝阳(区)。详情请参考 中国邮政区号表 内的「地区名称」列的内容填写。

jdpay 渠道
参数描述
account required string接收者银行卡账号。
amount required int付款金额,单位为分。
name required string接收者姓名。
open_bank_code required string4位,银行编号。
order_no optional string订单号,jdpay 限长 1~64 位不能重复的数字字母组合。
card_type optional int银行卡号类型。0:银行卡、2:信用卡,不填默认使用银行卡。
description optional string批量企业付款描述,最多 100 个 Unicode 字符。

balance 渠道
参数描述
user required string接收者用户 ID。
amount required int付款金额,单位为分。
order_no optional string订单号,1~64 位不能重复的数字字母组合。
description optional string批量企业付款描述,最多 100 个 Unicode 字符。

返回

返回一个 batch transfer 对象或者一个错误,详见 错误

定义

POST https://api.pingxx.com/v1/batch_transfers
$batch_tr = \Pingpp\BatchTransfer::create();
public BatchTransfer create();
此语言 SDK 暂不支持该接口。
pingpp.batchTransfers.create();
此语言 SDK 暂不支持该接口。
func ExampleBatchTransfer_new();
public static BatchTransfer alipayBatchTransfer(String appId) {}

请求示例

curl https://api.pingxx.com/v1/batch_transfers \
-H "Content-Type: application/json; charset=utf-8" \
-H "Pingplusplus-Signature: SIGNATURE" \
-H "Pingplusplus-Request-Timestamp: 1476067085" \
-u sk_test_ibbTe5jLGCi5rzfH4OqPW9KC: \
-d '{
    "amount": 8000,
    "app": "app_ribgW1n2SOqcPxn1",
    "batch_no": "2016101010380007",
    "channel": "alipay",
    "description": "付款说明",
    "recipients": [
        {
            "account": "account01@alipay.com",
            "amount": 5000,
            "name": "张三"
        },
        {
            "account": "account02@alipay.com",
            "amount": 3000,
            "name": "李四"
        }
    ],
    "type": "b2c"
}'
try {
    $batch_tr = \Pingpp\BatchTransfer::create(
        [
            'amount'      => 8000,
            'app'         => APP_ID,
            'batch_no'    => uniqid('btr'),         //批量退款批次号,3-24位,允许字母和英文
            'channel'     => 'alipay',              //
            'description' => 'Your Description',    //批量退款详情,最多 255 个 Unicode 字符
            'recipients'  => [                      //需要退款的  charge id 列表,一次最多 100 个
                [
                    'account' => 'account01@alipay.com',
                    'amount'  => 5000,
                    'name'    => '张三'
                ],
                [
                    'account' => 'account02@alipay.com',
                    'amount'  => 3000,
                    'name'    => '李四'
                ]
            ],
            'type'      => 'b2c'
        ]
    );
    echo $batch_tr;                                 // 输出 Ping++ 返回的 batch transfer 对象
} catch (\Pingpp\Error\Base $e) {
    if ($e->getHttpStatus() != null) {
        header('Status: ' . $e->getHttpStatus());
        echo $e->getHttpBody();
    } else {
        echo $e->getMessage();
    }
}
public BatchTransfer create() {
    BatchTransfer obj = null;
    String orderNo = new SimpleDateFormat("yyyyMMddhhmmss").format(new Date()) + Main.randomString(7);
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("app", appId);
    params.put("channel", "alipay");
    params.put("batch_no", orderNo); // 企业转账使用的商户内部订单号。wx(新渠道)、wx_pub 规定为 1 ~ 50 位不能重复的数字字母组合
    params.put("amount", 2000); // 订单总金额, 人民币单位:分(如订单总金额为 1 元,此处请填 100,企业付款最小发送金额为 1 元)
    params.put("type", "b2c"); // 付款类型,当前仅支持 b2c 企业付款
    params.put("currency", "cny");
    params.put("description", "your description");
    List<Map<String, Object>> recipients = new ArrayList<Map<String, Object>>();

    Map<String, Object> recipient = new HashMap<String, Object>();
    recipient.put("account", "user001@gmail.com");
    recipient.put("amount", 2000);
    recipient.put("name", "NAME");
    recipients.add(recipient);

    params.put("recipients", recipients);
    try {
        obj = BatchTransfer.create(params);
        System.out.println(obj);
    } catch (AuthenticationException e) {
        e.printStackTrace();
    } catch (InvalidRequestException e) {
        e.printStackTrace();
    } catch (APIConnectionException e) {
        e.printStackTrace();
    } catch (APIException e) {
        e.printStackTrace();
    } catch (ChannelException e) {
        e.printStackTrace();
    } catch (RateLimitException e) {
        e.printStackTrace();
    }
      return obj;
  }
此语言 SDK 暂不支持该接口。
pingpp.batchTransfers.create({
  "app": APP_ID,
  "batch_no": new Date().getTime().toString(), // 批量付款批次号
  "channel": "alipay", // 目前只支持 alipay
  "amount": 8000, // 批量付款总金额
  "description": "Your Description",
  "recipients": [
    {
      "account": "account01@alipay.com", // 接收者支付宝账号
      "amount": 5000, // 付款金额
      "name": "张三" // 接收者姓名
    },
    {
      "account": "account02@alipay.com", // 接收者支付宝账号
      "amount": 3000, // 付款金额
      "name": "李四" // 接收者姓名
    }
  ],
  "type": "b2c" // 付款类型,当前仅支持 b2c 企业付款
}, function(err, transfer) {
  if (err!=null){
    console.log("pingpp.batchTransfers.create fail:",err)
  }
  // YOUR CODE
});
此语言 SDK 暂不支持该接口。
func ExampleBatchTransfer_new() {
  recipients := []pingpp.BatchTransferRecipient{
    {Account: "account01@alipay.com", Amount: 5000, Name: "AA", Description: "Your description"},
    {Account: "account01@alipay.com", Amount: 5000, Name: "BB", Description: "Your description"},
  }
  params := &pingpp.BatchTransferParams{
    App:         "app_1Gqj58ynP0mHeX1q",
    Amount:      10000,
    Batch_no:    "2016101110380007",
    Channel:     "alipay",
    Description: "Your description",
    Type:        "b2c",
    Recipients:  recipients,
  }

  batchTransfer, err := batchTransfer.New(params)
  if err != nil {
    log.Fatal(err)
    return
  }
  content, _ := json.Marshal(batchTransfer)
  fmt.Println(string(content))
}
public static BatchTransfer alipayBatchTransfer(String appId)
{
    List<Dictionary<string, object>> list = new List<Dictionary<string, object>>();
    list.Add(new Dictionary<string, object>
    {
        // 必须,接收者支付宝账号。
        {"account", "account01@alipay.com"},
        //必须,金额,单位为分。
        {"amount", 5000},
        // 必须,接收者姓名
        {"name", "张三"},
        //可选,批量企业付款描述,最多 200 字节。
        {"description", "Your description"},
        // 可选,账户类型,alipay 2.0 渠道会用到此字段,取值范围: 1、ALIPAY_USERID:支付宝账号对应的支付宝唯一用户号。2088开头的16位纯数字组成。
        //                                                  2、ALIPAY_LOGONID(默认值):支付宝登录号,支持邮箱和手机号格式。
        {"account_type", "ALIPAY_LOGONID"},
        //可选,订单号, 1 ~ 64 位不能重复的数字字母组合。
        {"order_no", "123456789"}
    });
    list.Add(new Dictionary<string, object>
    {
        {"account", "account02@alipay.com"},
        {"amount", 3000},
        {"name", "李四"},
    });

    var btParams = new Dictionary<string, object>
    {
        {"amount",8000},//批量付款总金额,单位为分。为 recipients 中 amount 的总和。
        {"app", appId},
        {"batch_no", "2017042810380015"},//批量转账批次号,3-24位,允许字母和英文
        {"channel", "alipay"},  //目前支持 渠道。支付宝:alipay,银联:unionpay,微信公众号:wx_pub,通联:allinpay,京东:jdpay
        {"description", "Batch trans description."},
        {"type", "b2c"}, //付款类型 (当前 alipay、wx_pub 仅支持: b2c, unionpay、allinpay、jdpay 支持:  b2b、b2c)
        {"recipients", list}
    };

    return BatchTransfer.Create(btParams);
}

返回示例

{
  "id": "181610101014367590",
  "object": "batch_transfer",
  "app": "app_ribgW1n2SOqcPxn1",
  "amount": 8000,
  "batch_no": "2016101010380007",
  "channel": "alipay",
  "currency": "cny",
  "created": 1476067087,
  "description": "付款说明",
  "extra": {},
  "failure_msg": null,
  "fee": 0,
  "livemode": true,
  "metadata": {},
  "recipients": [
      {
          "account": "account01@alipay.com",
          "amount": 5000,
          "name": "张三",
          "transfer": "tr_jHWfvDnTKG0SiPmbfPbHW1eH",
          "status": "pending"
      },
      {
          "account": "account02@alipay.com",
          "amount": 3000,
          "name": "李四",
          "transfer": "tr_8u1yPK1eHWv9D08OePzDe1CK",
          "status": "pending"
      }
  ],
  "status": "pending",
  "time_succeeded": null,
  "type": "b2c"
}