Node SDK 使用文档

简介

目前 Adapay 的 Node SDK 支持的交易模块包括 支付(Payment)、退款(Refund)、查询、关单功能,用户对象,结算账户,企业用户等功能,具体可参考 API文档

下载地址

SDK下载

SDK 版本记录

版本

日期

说明

v1.1.2

2020-07-21

增加取现结果查询功能

v1.1.0

2020-02-28

增加钱包相关接口功能

v1.0.6

2020-01-17

增加余额查询以及取现功能

v1.0.4

2020-01-08

优化接口调用,新增获取云闪付标识功能

v1.0.3

2019-11-08

新增修改结算配置功能

v1.0.2

2019-10-24

新增延时分账功能

v1.0.1

2019-10-15

增加结算明细查询功能

v1.0.0

2019-09-19

Adapay 初版

版本要求

Node8

接入方法

  • 下载 SDK

下载文件里包含 SDK 和 Demo 两个目录。SDK 目录下为待添加到项目中的文件,Demo 目录下为示例项目,供接入时参考使用。

  • 获取 API Key

API Key 是您在 Adapay 系统中的身份标识,凭此可使用 Adapay 提供的 SDK 以及 API 服务

API Key 获取路径: 「控制台」 ->「商户信息管理」->「证书管理」

  • privateKey(RSA 私钥)

privateKey 为您本地生成的 RSA 私钥 (阿里云开放平台RSA工具) 生成选择PKCS8格式, SDK 在与 Adapay 服务端进行接口请求时,会使用此私钥进行加密。

对应的公钥请上传至 `「控制台」` ->「商户信息管理」->「证书管理」

  • publicKey(RSA 公钥)

publicKey 是 Adapay 为您生成的 RSA 公钥,SDK 在与 Adapay 服务端进行接口请求时 SDK 需要 publicKey 进行解签

publicKey 可通过 「控制台」 ->「商户信息管理」->「证书管理」进行下载。

  • 导入第三方依赖库

接入本 SDK 需依赖以下第三方库

axios
form-data
log4js
mqtt
  • INotifyCallback 和异步监听

SDK 需要设置异步监听,请实现 INotifyCallback 接口并启动异步监听,以实现异步通知处理。详情请参考 异步消息

使用方法

  • 系统初始化

在使用 Adapay 前,请先完成系统初始化设置,否则可能导致交易异常。

  • 调用示例

# 建议在服务启动时初始化

 // 设置基本参数
 let config = {}
 config.debug = true
 config.prod_mode = true

 config.connect_timeout = 60000
 config.log_file_path = resolve("./logs/")
 config.log_console_enable = true

 Adapay.set_config(config)
  • 设置商户配置信息

在每次调用 Adapay 的方法之前需要先设置商户的配置信息。

Adapay.clean_config()

Adapay.Config.prod_mode = prod_mode
Adapay.Config.config_dirname = resolve('./utils/config_release')
Adapay.set_group_merchant_path("merchantNO")

发起支付

当您想发起一次支付请求时需要通过 Adapay 提供的创建方法获取一个新的 Payment对象,您可使用此 Payment对象 发起支付。对于支付结果,Adapay 会发送 异步消息 告知。

  • 调用示例

let result = await Adapay.Payment.create({
    currency: currency,
    order_no: "(new Date().valueOf())",
    app_id: "your appid",
    pay_channel: "alipay_qr",
    pay_amt:  "0.01",
    goods_title: "your goods title",
    goods_desc: "your goods desc",
})
  • 参数说明

调用参数详见 创建支付

支付订单查询

查询已存在的 Payment对象

  • 调用示例

let result = await Adapay.Payment.query(payment_id)
  • 参数说明

调用参数详见 支付查询

发起退款

当您的业务需要发起退款时,可通过 Adapay 系统提供的创建 Refund对象 方法创建一个退款对象,发起退款请求。

  • 调用示例

let result = await Adapay.Refund.create({
  refund_order_no: "refund_order_no",
  payment_id: "payment_id",
  refund_amt: "0.01"
})
  • 参数说明

调用参数详见 创建退款

退款查询

通过 Refund对象 的 id 查询一个已创建的退款记录。

  • 调用示例

let result = await Adapay.Refund.query(payment_id)
  • 参数说明

调用参数详见 退款查询

关闭订单

针对已经创建的 Payment对象,您可以调用关单接口进行交易的关闭。

  • 调用示例

let result = await Adapay.Payment.close({
  payment_id: "payment_id",
  reason:"reason",
  expend:"expend",
  notify_url:"notify_url"
})
  • 参数说明

调用参数详见 关单

创建支付确认对象

创建支付确认对象适用于延时分账的场景。只有已支付完成且延时分账的Payment对象,才支持调用创建支付确认对象。支持一次全额或多次部分确认,多次部分确认时,当前确认金额 + 已确认金额 + 已撤销金额不能大于原支付金额。

  • 调用示例

let result = await Adapay.Payment.confirm({
  payment_id: "payment_id",
  order_no: "order_no",
  confirm_amt: "confirm_amt",
  description: "description",
  div_members: "div_members"
})
  • 参数说明

调用参数详见 创建支付确认对象

查询支付确认对象

查询支付确认对象

  • 调用示例

let result = await Adapay.Payment.queryConfirm({
  payment_confirm_id: "payment_confirm_id"
})
  • 参数说明

调用参数详见 查询支付确认对象

查询支付确认对象列表

查询支付确认对象列表

  • 调用示例

let result = await Adapay.Payment.queryConfirmList({
  app_id: "app_id",
  payment_id: "payment_id",
  page_index: "page_index",
  page_size: "page_size",
  created_gte: "created_gte",
  created_lte: "created_lte"
})
  • 参数说明

调用参数详见 查询支付确认对象列表

创建支付撤销对象

延时分账已支付的订单撤销功能,支持一个订单多笔撤销,撤销次数最多不超过10次。

  • 调用示例

let result = await Adapay.Payment.reverse({
  app_id: "app_id",
  payment_id: "payment_id",
  order_no: "order_no",
  notify_url: "notify_url",
  reverse_amt: "reverse_amt",
  reason: "reason",
  expand: "expand",
  device_info: "device_info"
})
  • 参数说明

调用参数详见 创建支付撤销对象

查询支付撤销对象

功能描述:延时分账已支付的订单的撤销查询功能,根据用户提供的支付撤销id查询撤销信息。

  • 调用示例

let result = await Adapay.Payment.queryReverse({
  reverse_id: "reverse_id"
})
  • 参数说明

调用参数详见 查询支付撤销对象

查询支付撤销对象列表

功能描述:延时分账已支付的支付的撤销查询功能,根据应用id批量查询支付撤销。

  • 调用示例

let result = await Adapay.Payment.queryReverseList({
  app_id: "app_id",
  payment_id: "payment_id",
  page_index: "page_index",
  page_size: "page_size",
  created_gte: "created_gte",
  created_lte: "created_lte"
})
  • 参数说明

调用参数详见 查询支付撤销对象列表

创建用户对象

创建用户对象用于将商户 member_id 与 Adapay 系统做关联,商户需要保证 member_id 在应用 app_id 下唯一。关联完成后,可以创建结算账户用于用户分账功能,也可以更新用户对象禁用用户状态,禁用用户所有交易功能。

  • 调用示例

var md5 = crypto.createHash('md5');
var date = (new Date()).valueOf()
var member_id = md5.update(`${date}`).digest('hex');

let result = await Adapay.Member.create({
  app_id: "app_id",
  member_id: member_id,
  location: "上海市徐汇区宜山路",
  email: "123@163.com",
  gender: "MALE",
  tel_no: "13153333333",
  nickname: "nick_name"
})
  • 参数说明

调用参数详见 创建用户对象

查询用户对象

查询已创建的单个用户对象

  • 调用示例

let result = await Adapay.Member.query({
  app_id, member_id
})
  • 参数说明

调用参数详见 查询用户对象

更新用户对象

对创建完成用户对象更新用户基本信息,可对用户状态禁用,禁用后用户不能做其它交易。

  • 调用示例

let result = await Adapay.Member.update({
  app_id: "app_id",
  member_id: "member_id",
  location: "上海市徐汇区宜山路1",
  email: "1234@163.com",
  gender: "MALE",
  tel_no: "13153333333",
  nickname: "nickname",
})
  • 参数说明

调用参数详见 更新用户对象

查询用户对象列表

对创建完成用户对象更新用户基本信息,可对用户状态禁用,禁用后用户不能做其它交易。

  • 调用示例

let result = await Adapay.Member.list({
  app_id: "app_id",
  page_index: "1",
  page_size: "20",
  created_gte: "created_gte",
  created_lte: "created_lte"
})
  • 参数说明

调用参数详见 用户对象列表

创建企业用户对象

通过本接口您可以创建企业用户,企业用户需要人工审核,审核完成后会发送异步消息通知,若审核成功,则商户用户 member_id 与 Adapay 系统关联成功,若审核失败,则可再次调用本接口提交正确的资料信息。

  • 调用示例

var md5 = crypto.createHash('md5');
var date = (new Date()).valueOf()
var member_id = md5.update(`${date}`).digest('hex');

// obj JSON对象入参  filePath 文件地址
let result = await Adapay.CorpMember.create({
  member_id: member_id,
  app_id: "app_id",
  order_no: `${(new Date()).valueOf()}`,
  social_credit_code_expires: "1111",
  business_scope: "123",
  name: "中国测试有限公司",
  prov_code: "0011",
  area_code: "1100",
  social_credit_code: "201932658452655",
  legal_person: "张测试",
  legal_cert_id: "321485199014234852",
  legal_cert_id_expires: "20220112",
  legal_mp: "13958465215",
  address: "中国上海",
  telphone: "41164452",
  email: "ceshi@qq.com",
  bank_code: "652142",
  bank_acct_type: "1",
  card_no: "622546895642156",
  card_name: "中国测试有限公司",
}, "/Adapay/files/file.zip")
  • 参数说明

调用参数详见 创建企业用户对象

查询企业用户对象

查询已创建的企业用户对象

  • 调用示例

let result = await Adapay.CorpMember.query({
  member_id: "member_id",
  app_id: "app_id",
})
  • 参数说明

调用参数详见 查询企业用户对象

创建结算账户对象

商户的 member_id 与 Adapay 系统做关联后,可以创建结算账户,用于用户分账功能,目前只支持绑定银行卡。

  • 调用示例

var md5 = crypto.createHash('md5');
var date = (new Date()).valueOf()
var member_id = md5.update(`${date}`).digest('hex');

let result = await Adapay.Account.create({
  member_id: member_id,
  app_id: "app_id",
  channel: "bank_account",
  account_info: {
    card_id: "6222021703001692221",
    card_name: "袁电茜",
    cert_id: "310109200006062491",
    cert_type: "00",
    tel_no: "18888888881",
    bank_code: "03060000",
    bank_acct_type: "1",
    prov_code: "0031",
    area_code: "3100"
  }
})
  • 参数说明

调用参数详见 创建结算账户对象

查询结算账户对象

查询已绑定的结算账户对象。

  • 调用示例

let result = await Adapay.Account.query({
  app_id: "app_id",
  member_id: "member_id",
  settle_account_id: "settle_account_id"
})
  • 参数说明

调用参数详见 查询结算明细列表

查询结算明细列表

使用 Adapay 系统生成的结算账户对象 id 查询已创建的结算账户对象信息。

  • 调用示例

let result = await Adapay.Account.querySettleDetail({
  app_id: "app_id",
  member_id: "member_id",
  settle_account_id: "settle_account_id",
  begin_date: "20190908",
  end_date: "20191009"
})
  • 参数说明

调用参数详见 查询结算明细列表

删除结算账户对象

删除已绑定的结算账户对象。

  • 调用示例

let result = await Adapay.Account.deleteAccount({
  app_id: "app_id",
  member_id: "member_id",
  settle_account_id: "settle_account_id"
})
  • 参数说明

调用参数详见 删除结算账户对象

修改结算配置

修改用户结算账户配置,可配置用户结算的起始金额、结算留存金额、结算信息摘要等。

注:本接口不能更改结算卡,如需更改结算账户的结算卡,请先删除结算账户,再重新创建结算账户。

  • 调用示例

let result = await Adapay.Account.modify({
  app_id, member_id, settle_account_id, min_am, remained_amt, channel_remark
})
  • 参数说明

调用参数详见 修改结算配置

下载对账单

您可通过本接口下载您交易日期的对账单。比如掉单、系统错误等导致商户侧和 Adapay 侧数据不一致,通过对账单核对后可校正支付状态。

  • 调用示例

let result = await Adapay.Bill.download({bill_date})
  • 请求参数

参数

类型

描述

bill_date

String(8)

对账单的日期,格式:20180808

  • 返回参数

参数

类型

描述

bill_download_url

String(8)

对账单文件下载 url

  • 参数说明

调用参数详见 下载对账单

获取银联云闪付用户标识

该接口是聚合支付,银联云闪付 H5 支付的前置接口。 商户在自己的平台上通过银联接口获取用户的授权码后,调用本接口同步换取对应用户在银联体系的用户唯一标识。发起银联云闪付 H5 支付时用户唯一标识 user_identity_id 是必填的请求参数。

  • 调用示例

let result = await Adapay.Union.userIdentity({
  order_no, app_id, user_auth_code, app_up_identifier
})
  • 参数说明

调用参数详见 获取银联云闪付用户标识

查询账户余额

通过本接口查询账户余额

  • 调用示例

let result = await Adapay.Account.queryBalance({
          app_id, member_id, settle_account_id
})
  • 请求参数

调用参数详见 查询账户余额

取现

通过该接口,实现对指定商户或者商户下用户的结算账户可用余额发起主动提现操作,金额从账户中提到绑定的结算银行卡中。取现结果以异步通知为准。

  • 调用示例

let result = await Adapay.Cashs.createCashs({
          app_id, order_no, cash_type, cash_amt, member_id, notify_url
})
  • 请求参数

调用参数详见 钱包取现

取现查询

通过该接口,可以查询已发起的取现交易状态。

  • 调用示例

// 查询取现状态
let result = await Adapay.Cashs.queryCashsStat({
    order_no
})
  • 请求参数

调用参数详见 取现查询

钱包登录

通过该接口,实现对商户登录钱包功能,登录成功返回跳转地址

  • 调用示例

let result = await Adapay.Wallet.walletLogin({
    app_id, member_id, ip
})
  • 请求参数

调用参数详见 钱包登录

钱包支付

通过该接口,实现对商户钱包支付功能,下单成功返回支付跳转地址

  • 调用示例

let result = await Adapay.Wallet.pay({
    app_id,
    order_no, pay_amt, currency, description, div_members, goods_title,
    goods_desc, callback_url, notify_url
})
  • 请求参数

调用参数详见 钱包支付

创建收银台对象

通过该接口,实现对商户钱包收银台支付功能,下单成功返回支付跳转地址

  • 调用示例

let result = await Adapay.Wallet.createCheckOut({
  app_id, order_no, member_id, pay_amt, currency, goods_title, goods_desc,
  callback_url
})
  • 请求参数

调用参数详见 创建收银台对象

异步消息监听

Adapay 在支付成功、支付失败、关单成功、关单失败、退款成功、退款失败时,都会推送终态结果给到您,请务必监听异步结果并做好并发处理。

请实现以下方法

示例

// 设置基本参数
let config = {}
config.debug = true
config.prod_mode = true

config.connect_timeout = 60000
config.log_file_path = resolve("./logs/")
config.log_console_enable = true

// 消息订阅
var Message = require('./utils/sdk/adapay-sdk/adapay-core/Message')
var payMsg = new Message(config, resolve('./utils/merchantConfig.json'))

payMsg.on('connect', function() {
  console.log('消息链接成功!')
})

payMsg.on('error', function(err) {
  console.log('mqtt connect error: ' + err.toString())
})

//topic
payMsg.on('message', function(topic, message) {
// message is Buffer
  console.log('mqtt connect message: ' + message.toString())
})

payMsg.on('subscribe', function(error, granted) {
  if (error) {
    console.log('mqtt subscribe error: ' + message.toString())
  }
  console.log('消息订阅成功!')
})
  • 返回数据示例

不同事件异步消息返回数据,详见 异步消息数据示例