node tenpay

Оплата WeChat для nodejs

Обзор функций

• 通知类中间件— уведомление о результате платежа, уведомление о результате возврата
• 前端支付支持— поддерживает JSAPI, WeixinJSBridge, мини-программы, APP, H5.
• 支付模式支持- код платежа/официальный аккаунт/мини-программа/приложение/H5/оплата скан-кода
• 支付工具支持- красный конверт WeChat, корпоративный платеж (поддерживает оплату на сдачу и банковскую карту)
• 营销功能支持— ваучер WeChat
• 对帐账单支持— поддерживает заявление WeChat и законопроект о фонде WeChat.
• 服务商模式支持— все API можно передавать в sub_appid, sub_mch_id.
• 微信支付仿真测试系统- поддерживает режим песочницы, используемый для завершения процесса приема платежей.

Коммуникационная группа

Группа QQ: 157964097. Присоединяйтесь к группе, чтобы задать вопросы по использованию, разработке и внести свой вклад в код.

Обязательно прочтите перед использованием

Требования к версии

узел js >= 8.3.0

О типах данных входящих значений и возвращаемых значениях WeChat

Из-за деликатных проблем, таких как задействованные суммы, API и промежуточное программное обеспечение не выполняли преобразование типов полей данных.

微信返回值XML做JSON转换之后的字段均为字符串类型, 请自行转换后再进行数据运算

сосредоточиться на проблемах

• Проблема с результатом операции со строкой и числом '1' + 0 = '10'
• Проблема с единицей суммы:微信支付中传入的金额单位为分

Об ошибке

И API, и промежуточное программное обеспечение обрабатывают все ошибки и единообразно возвращают их через ошибки, включая:

• 网络类错误– обрыв сети, таймаут соединения и т.д.
• 微信返回值检验错误— возвращаемое значение WeChat является незаконным (поддельные запросы и т. д., вероятность очень мала)
• 业务逻辑错误— дублирующиеся заказы, сумма возврата больше суммы платежа и т. д.
• 其它错误— не передаются передаваемые параметры и т. д.

О возвращаемой стоимости

Обычно возвращает данные в формате JSON, если ошибок не возникает.

• Особый случай: возвращаемое значение счета, загруженного с помощью downloadBill и downloadFundflow представляет собой строковый литерал.

Установить

npm i tenpay

# 如已安装旧版, 重新安装最新版
npm i tenpay@latest

Создать экземпляр

 const tenpay = require ( 'tenpay' ) ;
const config = {
  appid : '公众号ID' ,
  mchid : '微信商户号' ,
  partnerKey : '微信支付安全密钥' ,
  pfx : require ( 'fs' ) . readFileSync ( '证书文件路径' ) ,
  notify_url : '支付回调网址' ,
  spbill_create_ip : 'IP地址'
} ;
// 方式一
const api = new tenpay ( config ) ;
// 方式二
const api = tenpay . init ( config ) ;

// 调试模式(传入第二个参数为true, 可在控制台输出数据)
const api = new tenpay ( config , true ) ;

// 沙盒模式(用于微信支付验收)
const sandboxAPI = await tenpay . sandbox ( config ) ; 

описание конфигурации:

• appid — Официальный идентификатор аккаунта (обязательно)
• mchid — номер продавца WeChat (обязательно)
• partnerKey — ключ безопасности платежей WeChat (обязательный, полученный из интерфейса управления продавцами WeChat)
• pfx — файл сертификата (необязательно, получен из интерфейса управления торговцами WeChat)
  • Этот параметр не нужно заполнять, если нет необходимости вызывать API, использующие сертификаты.
  • Если в бизнес-процессе используется API, зависящий от сертификата, этот параметр необходимо передать во время инициализации.
• notify_url - адрес обратного вызова уведомления о результате платежа (необязательно)
  • Вы можете передать его во время инициализации и установить в качестве значения по умолчанию. Если нет, вам необходимо передать его при вызове соответствующего API.
  • Если при вызове соответствующего API передается новое значение, будет использоваться новое значение.
• refund_url — адрес обратного вызова уведомления о результате возврата (необязательно)
  • Вы можете передать его во время инициализации и установить в качестве значения по умолчанию. Если нет, используйте фоновую конфигурацию продавца WeChat.
  • Если при вызове соответствующего API передается новое значение, будет использоваться новое значение.
• spbill_create_ip — IP-адрес (необязательно)
  • Вы можете передать его во время инициализации и установить в качестве значения по умолчанию. Если вы не передадите его, значение по умолчанию будет 127.0.0.1
  • Если при вызове соответствующего API передается новое значение, будет использоваться новое значение.

Рекомендации по использованию необязательных параметров:

• Если в бизнес-процессе используется API, содержащий запрос сертификата, изначально необходимо передать параметр pfx.
• Если адрес обратного вызова не требуется изменять в зависимости от бизнеса, рекомендуется передать единый адрес обратного вызова во время инициализации.
• Если IP-адрес не требуется изменять в зависимости от бизнеса, рекомендуется передать единый IP-адрес во время инициализации.

Промежуточное ПО・Уведомление о сообщении WeChat

• Параметры промежуточного программного обеспечения: pay<支付结果通知, 默认> refund<退款结果通知> nativePay<扫码支付模式一回调>
• Вам необходимо самостоятельно добавить bodyParser для получения данных публикации.
• Промежуточное программное обеспечение проверит законность сообщения уведомления, преобразует сообщение в формат json и поместит его в req.weixin(Express) или ctx.request.weixin(Koa).
• ответ() автоматически инкапсулирует сообщение УСПЕХ, ответ('некоторая ошибка_msg') автоматически инкапсулирует сообщение НЕУДАЧА

Используется в экспрессе

 app . use ( bodyParser . text ( { type : '*/xml' } ) ) ;

// 支付结果通知/退款结果通知
router . post ( '/xxx' , api . middlewareForExpress ( 'pay' ) , ( req , res ) => {
  let info = req . weixin ;

  // 业务逻辑...

  // 回复消息(参数为空回复成功, 传值则为错误消息)
  res . reply ( '错误消息' || '' ) ;
} ) ;

// 扫码支付模式一回调
router . post ( '/xxx' , api . middlewareForExpress ( 'nativePay' ) , ( req , res ) => {
  let info = req . weixin ;

  // 业务逻辑和统一下单获取prepay_id...

  // 响应成功或失败(第二个可选参数为输出错误信息)
  res . replyNative ( prepay_id , err_msg ) ;
} ) ; 

Используется в Коа

 app . use ( bodyParser ( {
  enableTypes : [ 'json' , 'form' , 'text' ] ,
  extendTypes : {
    text : [ 'text/xml' , 'application/xml' ]
  }
} ) ) ;

router . post ( '/xxx' , api . middleware ( 'refund' ) , async ctx => {
  let info = ctx . request . weixin ;

  // 业务逻辑...

  // 回复消息(参数为空回复成功, 传值则为错误消息)
  ctx . reply ( '错误消息' || '' ) ;

  // 扫码支付模式一模式
  ctx . replyNative ( prepay_id ) ;
} ) ; 

Список API

• Некоторые API задают значения по умолчанию для определенных обязательных полей. Если при вызове не передаются никакие параметры, будут использоваться значения по умолчанию.
• Параметры, переданные во время инициализации, не нужно передавать повторно при вызове, например appid mchid
• Подпись будет автоматически обработана при вызове API, нет необходимости передавать ее вручную.
• Случайная строка (nonce_str) будет автоматически обработана при вызове API, нет необходимости передавать ее вручную.

getPayParams: получить параметры оплаты WeChat JSSDK (автоматическое размещение заказа, совместимое с мини-программами)

 let result = await api . getPayParams ( {
  out_trade_no : '商户内部订单号' ,
  body : '商品简单描述' ,
  total_fee : '订单金额(分)' ,
  openid : '付款用户的openid'
} ) ; 

Связанные значения по умолчанию:

• trade_type — JSAPI

getPayParamsByPrepay: получить параметры оплаты WeChat JSSDK (через идентификатор сеанса предоплаты, совместимый с мини-программами)

 // 该方法需先调用api.unifiedOrder统一下单, 获取prepay_id;
let result = await api . getPayParamsByPrepay ( {
  prepay_id : '预支付会话标识'
} ) ;

getAppParams: получить параметры оплаты приложения (автоматическое размещение заказа).

 let result = await api . getAppParams ( {
  out_trade_no : '商户内部订单号' ,
  body : '商品简单描述' ,
  total_fee : '订单金额(分)'
} ) ; 

Связанные значения по умолчанию:

• trade_type -APP

getAppParamsByPrepay: получить параметры оплаты приложения (через идентификатор сеанса предоплаты).

 // 该方法需先调用api.unifiedOrder统一下单<注意传入trade_type: 'APP'>, 获取prepay_id;
let result = await api . getAppParamsByPrepay ( {
  prepay_id : '预支付会话标识'
} ) ;

getNativeUrl: сканировать код для оплаты (режим 1)

 let result = await api . getNativeUrl ( {
  product_id : '商品ID'
} ) ;

Сканируйте QR-код для оплаты (режим 2)

 // 使用统一下单API可直接获取code_url, 需自行生成二维码图片
let { prepay_id , code_url } = await api . unifiedOrder ( {
  out_trade_no : '商户内部订单号' ,
  body : '商品简单描述' ,
  total_fee : '订单金额(分)' ,
  openid : '用户openid' ,
  trade_type : 'NATIVE' ,
  product_id : '商品id'
} ) ;

микропей: оплата картой

 let result = await api . micropay ( {
  out_trade_no : '商户内部订单号' ,
  body : '商品简单描述' ,
  total_fee : '订单金额(分)' ,
  auth_code : '授权码'
} ) ;

unifiedOrder: унифицированный порядок заказа WeChat.

 let result = await api . unifiedOrder ( {
  out_trade_no : '商户内部订单号' ,
  body : '商品简单描述' ,
  total_fee : '订单金额(分)' ,
  openid : '用户openid'
} ) ; 

Связанные значения по умолчанию:

• trade_type — JSAPI
• notify_url — по умолчанию используется значение, переданное во время инициализации, или пустое.
• spbill_create_ip — по умолчанию используется значение, переданное во время инициализации, или 127.0.0.1

orderQuery: порядок запроса

 let result = await api . orderQuery ( {
  // transaction_id, out_trade_no 二选一
  // transaction_id: '微信的订单号',
  out_trade_no : '商户内部订单号'
} ) ;

реверс: отменить заказ

 let result = await api . reverse ( {
  // transaction_id, out_trade_no 二选一
  // transaction_id: '微信的订单号',
  out_trade_no : '商户内部订单号'
} ) ;

closeOrder: закрыть ордер

 let result = await api . closeOrder ( {
  out_trade_no : '商户内部订单号'
} ) ;

возврат: подать заявку на возврат

 let result = await api . refund ( {
  // transaction_id, out_trade_no 二选一
  // transaction_id: '微信的订单号',
  out_trade_no : '商户内部订单号' ,
  out_refund_no : '商户内部退款单号' ,
  total_fee : '订单金额(分)' ,
  refund_fee : '退款金额(分)'
} ) ; 

Связанные значения по умолчанию:

• op_user_id - по умолчанию номер продавца (это поле появляется в платежном документе мини-программы)
• notify_url — по умолчанию используется URL-адрес возврата, переданный во время инициализации. Без этого параметра будет использоваться адрес уведомления о возврате, настроенный в серверной части продавца.

returnQuery: Запросить возврат средств

 let result = await api . refundQuery ( {
  // 以下参数 四选一
  // transaction_id: '微信的订单号',
  // out_trade_no: '商户内部订单号',
  // out_refund_no: '商户内部退款单号',
  refund_id : '微信退款单号'
} ) ;

скачатьБилл: Скачать заявление

 /**
 * 新增一个format参数(默认: false), 用于自动转化帐单为json格式
 * json.total_title: 统计数据的标题数组 - ["总交易单数","总交易额","总退款金额", ...],
 * json.total_data: 统计数据的数组 - ["3", "88.00", "0.00", ...],
 * json.list_title: 详细数据的标题数组 - ["交易时间","公众账号ID","商户号", ...],
 * json.list_data: 详细数据的二维数据 - [["2017-12-26 19:20:39","wx12345", "12345", ...], ...]
 */
let result = await api . downloadBill ( {
  bill_date : '账单日期'
} , true ) ; 

Связанные значения по умолчанию:

• bill_type -ВСЕ
• format -ложь

downloadFundflow: скачать выписку по фонду

 /**
 * 新增一个format参数(默认: false), 用于自动转化帐单为json格式
 * json.total_title: 统计数据的标题数组 - ["资金流水总笔数","收入笔数","收入金额", ...],
 * json.total_data: 统计数据的数组 - ["20.0", "17.0", "0.35", ...],
 * json.list_title: 详细数据的标题数组 - ["记账时间","微信支付业务单号","资金流水单号", ...],
 * json.list_data: 详细数据的二维数据 - [["2018-02-01 04:21:23","12345", "12345", ...], ...]
 */
let result = await api . downloadFundflow ( {
  bill_date : '账单日期'
} , true ) ; 

Связанные значения по умолчанию:

• account_type -Базовый
• format -ложь

sendCoupon: выдавать купоны

 let result = await api . sendCoupon ( {
  coupon_stock_id : '代金券批次id' ,
  partner_trade_no : '商户单据号' ,
  openid : '用户openid'
} ) ;

queryCouponStock: запросы пакетов ваучеров.

 let result = await api . queryCouponStock ( {
  coupon_stock_id : '代金券批次id'
} ) ;

queryCouponInfo: запрос информации о купоне.

 let result = await api . queryCouponInfo ( {
  coupon_id : '代金券id' ,
  openid : '用户openid' ,
  stock_id : '批次号'
} ) ;

переводы: корпоративные платежи

 let result = await api . transfers ( {
  partner_trade_no : '商户内部付款订单号' ,
  openid : '用户openid' ,
  re_user_name : '用户真实姓名' ,
  amount : '付款金额(分)' ,
  desc : '企业付款描述信息'
} ) ; 

Связанные значения по умолчанию:

• check_name - FORCE_CHECK
• spbill_create_ip — по умолчанию используется значение, переданное во время инициализации, или 127.0.0.1

TransfersQuery: Запрос корпоративных платежей

 let result = await api . transfersQuery ( {
  partner_trade_no : '商户内部付款订单号'
} ) ;

payBank: Бизнес-платежи на банковские карты

 let result = await api . payBank ( {
  partner_trade_no : '商户内部付款订单号' ,
  bank_code : '收款方开户行' ,
  enc_bank_no : '收款方银行卡号' ,
  enc_true_name : '收款方用户名' ,
  amount : '付款金额(分)' ,
  desc : '企业付款到银行卡描述信息'
} ) ;

queryBank: Запрос корпоративного платежа на банковскую карту

 let result = await api . queryBank ( {
  partner_trade_no : '商户内部付款订单号'
} ) ;

sendRedpack: отправлять обычные красные пакеты.

 let result = await api . sendRedpack ( {
  // mch_billno, mch_autono 二选一
  // mch_billno: '商户内部付款订单号',
  mch_autono : '10位当日唯一数字, 用于自动生成mch_billno' ,
  send_name : '商户名称' ,
  re_openid : '用户openid' ,
  total_amount : '红包金额(分)' ,
  wishing : '红包祝福语' ,
  act_name : '活动名称' ,
  remark : '备注信息'
} ) ; 

Сопутствующие значения по умолчанию и другие инструкции:

• mch_billno — внутренний номер заказа продавца (если его передать, mch_autono будет недействительным)
• mch_autono - 10-значный уникальный номер дня, используемый для автоматической обработки внутренней логики номера заказа продавца.
• total_num - 1
• client_ip — по умолчанию используется значение параметра spbill_create_ip во время инициализации или 127.0.0.1
• scene_id — пусто, должно быть отправлено, когда сумма в красном конверте превышает 2元(в документе WeChat указано, что это 200 юаней, фактическое измерение — 2 юаня)

sendGroupRedpack: отправлять красные пакеты деления.

 let result = await api . sendGroupRedpack ( {
  // mch_billno, mch_autono 二选一
  // mch_billno: '商户内部付款订单号',
  mch_autono : '10位当日唯一数字, 用于自动生成mch_billno' ,
  send_name : '商户名称' ,
  re_openid : '种子用户openid' ,
  total_amount : '红包金额(分)' ,
  wishing : '红包祝福语' ,
  act_name : '活动名称' ,
  remark : '备注信息'
} ) ; 

Сопутствующие значения по умолчанию и другие инструкции:

• mch_billno — внутренний номер заказа продавца (если его передать, mch_autono будет недействительным)
• mch_autono - 10-значный уникальный номер дня, используемый для автоматической обработки внутренней логики номера заказа продавца.
• total_num — 3, необходимое значение для разделения красного конверта — от 3 до 20.
• amt_type -ALL_RAND
• scene_id — пусто, необходимо передать, когда сумма в красном конверте превышает 2元(в документе не указано)

redpackQuery: запрос записей красных пакетов.

 api . redpackQuery ( {
  mch_billno : '商户内部付款订单号'
} ) ; 

Связанные значения по умолчанию:

• bill_type -MCHT