查看文章列表

充值退款

  • 语言
  • 渠道

接入 Ping++ 发起余额充值退款，仅需要 Ping++ Server SDK 即可。服务器端需要做的就是向 Ping++ 请求 Refund 接口，并且监听和获取 Webhooks 通知，具体步骤如下：

  1. 设置 API-Key
  2. SDK 验证签名设置
  3. 服务端发起退款请求获取 Refund 对象
  4. 接收 Webhooks 通知
  5. 验证 Webhooks 签名

第一步：设置 API-Key

Ping++ API 交易时需要设置 API-Key，Server SDK 提供了设置的方法。如果你直接使用 API ，需要在 header 中加入 Authorization，格式是 Authorization: Bearer API-Key。

\Pingpp\Pingpp::setApiKey('sk_test_ibbTe5jLGCi5rzfH4OqPW9KC');
Pingpp.apiKey = "sk_test_ibbTe5jLGCi5rzfH4OqPW9KC";
var pingpp = require('pingpp')('sk_test_ibbTe5jLGCi5rzfH4OqPW9KC');
pingpp.api_key = 'sk_test_ibbTe5jLGCi5rzfH4OqPW9KC'
Pingpp.api_key = "sk_test_ibbTe5jLGCi5rzfH4OqPW9KC"
pingpp.Key = "sk_test_ibbTe5jLGCi5rzfH4OqPW9KC"
Pingpp.Pingpp.SetApiKey("sk_test_ibbTe5jLGCi5rzfH4OqPW9KC");

第二步：SDK 验证签名设置

为了进一步增强交易请求的安全性，Ping++ 交易接口针对所有的 POST 和 PUT 请求已经新增 RSA 加密验签功能。该接口必须使用该签名验证功能，你需要生成密钥，然后将私钥配置到你的代码中，公钥上传至 Ping++ 管理平台并启用验签开关。首先你需要本地生成 RSA 公钥和私钥，生成方法请参考：如何获取 RSA 公钥和私钥？

设置请求签名密钥

你需要在代码中设置请求签名的私钥(rsa_private_key.pem)，可以读取配置私钥文件的路径或者直接定义变量。你如果通过 API 接口校验的话，需要生成 RSA 签名(SHA256)并在请求头中添加 Pingplusplus-Signature，如果使用 SDK 的话只需要配置私钥即可。

\Pingpp\Pingpp::setPrivateKeyPath(__DIR__ . '/your_rsa_private_key.pem');
Pingpp.privateKeyPath = "/path/to/your_rsa_private_key.pem";
pingpp.setPrivateKeyPath(__dirname + "/your_rsa_private_key.pem");
pingpp.private_key_path = 'your_rsa_private_key.pem'
Pingpp.private_key_path = File.dirname(__FILE__) + '/your_rsa_private_key.pem'
privateKey, err := ioutil.ReadFile("your_rsa_private_key.pem")
Pingpp.Pingpp.SetPrivateKeyPath(@"../../your_rsa_private_key.pem");

上传公钥至 Ping++ 管理平台

设置完代码中的私钥，你需要将已经生成的公钥(rsa_public_key.pem)填写到 Ping++ 管理平台上。 配置路径： 登录 Ping++ 管理平台->点击右上角公司名称->企业面板->开发参数->商户 RSA 公钥->将你的公钥复制粘贴进去并且保存->先启用 Test 模式进行测试->测试通过后启用 Live 模式

rsa_keys_setting

注意： 一旦上传公钥至 Ping++ 管理平台并启用 Live 模式，则验证签名功能即时生效，Ping++ 会立即验证你的真实线上交易验签请求。如果私钥为空或错误，则会交易失败，所以请确保测试模式正常后再启用 Live 开关。

第三步：服务端发起退款请求获取 Refund 对象

调用 Ping++ Server SDK 发起余额充值退款请求，发起请求所需参数具体可参考 API 文档。

\Pingpp\Recharge::refund('221170807730968330240000', [
        'description' => 'Rechage refund description',
        'metadata' => [],
    ]);
  Pingpp.apiKey = "sk_test_ibbTe5jLGCi5rzfH4OqPW9KC";
  Map<String, Object> params = new HashMap<>();
  params.put("description", "Recharge Refund Description"); // 必传
  // 创建 recharge_refund 方法
  // 参数一: rechargeId
  // 参数二: params
  Refund obj = RechargeRefund.create(rechargeId, params);
var params_create = {
  'description': 'Recharge Refund Description'  // 描述 必传
};
pingpp.recharge.createRefund(APP_ID,
  '220170901352207144960002',       // Recharge ID
  params_create,
  function(err, recharge) {
    if (err != null){
      console.log('pingpp.recharge.createRefund fail:', err);
    }
    // YOUR CODE
});                      
    refund_param = {
        "description": "Your description",
        "metadata": {}
    }
    pingpp.RechargeRefund.create(rechargeid, **refund_param)
o = Pingpp::Recharge.refund(
          recharge_to_refund, # Recharge 对象 ID
          {
            # required.
            :description => '退款信息',
          },
          { :app => get_app_id } # App 信息
        )
 
	rechargeParams := &pingpp.RechargeRefundParams{
		Description: "充值退款",
		}
	return recharegRefund.New(c.demoAppID, c.demoRechargeID, rechargeParams)
RechargeRefund.Create(appId, rechargeid, new Dictionary<string, object> 
            {
                {"description", "Your Description"},
                {"metadata", new Dictionary<string,object>{}}
            });

Ping++ 收到退款请求后返回给你的服务器一个 Refund 对象，下面是 Refund 对象的一个示例：

{
  "id": "re_vXr14Se1GOGKyjzj5KPKizv9",
  "object": "refund",
  "order_no": "vXr14Se1GOGKyjzj5KPKizv9",
  "amount": 1000,
  "created": 1496743652,
  "succeed": false,
  "status": "pending",
  "time_succeed": null,
  "description": "Refund Description",
  "failure_code": null,
  "failure_msg": null,
  "metadata": {},
  "charge": "ch_SejbHOrzbjvPunjHmD08SCi9",
  "charge_order_no": "20170711102300167",
  "transaction_no": null,
  "extra": {}
}

第四步：接收 Webhooks 通知

当退款完成后 Ping++ 会给你配置在 Ping++ 管理平台的 Webhooks 通知地址主动发送退款结果，我们称之为 Webhooks 通知。 Webhooks 通知是以 POST 形式发送的 JSON，放在请求的 body 里，内容是 Event 对象，退款成功的事件类型为 refund.succeeded ，你需要监听并接收 Webhooks 通知，接收到 Webhooks 后需要返回服务器状态码 2xx 表示接收成功，否则请返回状态码 500。

$event = json_decode(file_get_contents("php://input"));
// 对异步通知做处理
if (!isset($event->type)) {
    header($_SERVER['SERVER_PROTOCOL'] . ' 400 Bad Request');
    exit("fail");
}
switch ($event->type) {
    case "recharge.succeeded":
        // 开发者在此处加入对充值异步通知的处理代码
        header($_SERVER['SERVER_PROTOCOL'] . ' 200 OK');
        break;
    case "refund.succeeded":
        // 开发者在此处加入对退款异步通知的处理代码
        header($_SERVER['SERVER_PROTOCOL'] . ' 200 OK');
        break;
    default:
        header($_SERVER['SERVER_PROTOCOL'] . ' 400 Bad Request');
        break;
}
import com.pingplusplus.model.Event;
import com.pingplusplus.model.Webhooks;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.BufferedReader;
import java.io.IOException;
public class ServletDemo extends HttpServlet {
    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        request.setCharacterEncoding("UTF8");
        //获取头部所有信息
        Enumeration headerNames = request.getHeaderNames();
        while (headerNames.hasMoreElements()) {
            String key = (String) headerNames.nextElement();
            String value = request.getHeader(key);
            System.out.println(key+" "+value);
        }
        // 获得 http body 内容
        BufferedReader reader = request.getReader();
        StringBuffer buffer = new StringBuffer();
        String string;
        while ((string = reader.readLine()) != null) {
            buffer.append(string);
        }
        reader.close();
        // 解析异步通知数据
        Event event = Webhooks.eventParse(buffer.toString());
        if ("recharge.succeeded".equals(event.getType())) {
            response.setStatus(200);
        } else if ("refund.succeeded".equals(event.getType())) {
            response.setStatus(200);
        } else {
            response.setStatus(500);
        }
    }
}
var http = require('http');
http.createServer(function (req, res) {
  req.setEncoding('utf8');
  var postData = "";
  req.addListener("data", function (chunk) {
    postData += chunk;
  });
  req.addListener("end", function () {
    var resp = function (ret, status_code) {
      res.writeHead(status_code, {
        "Content-Type": "text/plain; charset=utf-8"
      });
      res.end(ret);
    }
    try {
      var event = JSON.parse(postData);
      if (event.type === undefined) {
        return resp('Event 对象中缺少 type 字段', 400);
      }
      switch (event.type) {
        case "recharge.succeeded":
          // 开发者在此处加入对充值异步通知的处理代码
          return resp("OK", 200);
          break;
        case "refund.succeeded":
          // 开发者在此处加入对退款异步通知的处理代码
          return resp("OK", 200);
          break;
        default:
          return resp("未知 Event 类型", 400);
          break;
      }
    } catch (err) {
      return resp('JSON 解析失败', 400);
    }
  });
}).listen(8080, "0.0.0.0");
import json
from flask import Flask, request, Response
# 使用 flask
@app.route('/webhooks', methods=['POST'])
def webhooks():
    event = request.get_json()
    if event['type'] == 'recharge.succeeded':
        return Response(status=200)
    elif event['type'] == 'refund.succeeded':
        return Response(status=200)
    return Response(status=500)
 
if __name__ == '__main__':
    app.run(debug=False, host='0.0.0.0', port=8080)
require 'webrick'
require 'json'
class Webhooks < WEBrick::HTTPServlet::AbstractServlet
  def do_POST(request, response)
    status = 400
    response_body = '' # 可自定义
    begin
      event = JSON.parse(request.body)
      if event['type'].nil?
        response_body = 'Event 对象中缺少 type 字段'
      elsif event['type'] == 'recharge.succeeded'
        # 开发者在此处加入对充值异步通知的处理代码
        status = 200
        response_body = 'OK'
      elsif event['type'] == 'refund.succeeded'
        # 开发者在此处加入对退款异步通知的处理代码
        status = 200
        response_body = 'OK'
      else
        response_body = '未知 Event 类型'
      end
    rescue JSON::ParserError
      response_body = 'JSON 解析失败'
    end
    response.status = status
    response['Content-Type'] = 'text/plain; charset=utf-8'
    response.body = response_body
  end
end
server = WEBrick::HTTPServer.new(:Port => 8000)
server.mount '/webhooks', Webhooks
trap 'INT' do server.shutdown end
server.start
func webhook(w http.ResponseWriter, r *http.Request) {
  if strings.ToUpper(r.Method) == "POST" {
    buf := new(bytes.Buffer)
    buf.ReadFrom(r.Body)
    signature := r.Header.Get("x-pingplusplus-signature")
    webhook, err := pingpp.ParseWebhooks(buf.Bytes())
    fmt.Println(webhook.Type)
    if err != nil {
      w.WriteHeader(http.StatusInternalServerError)
      fmt.Fprintf(w, "fail")
      return
    }
    if webhook.Type == "recharge.succeeded" {
      // TODO your code for charge
      w.WriteHeader(http.StatusOK)
    } else if webhook.Type == "refund.succeeded" {
      // TODO your code for refund
      w.WriteHeader(http.StatusOK)
    } else {
      w.WriteHeader(http.StatusInternalServerError)
    }
  }
 
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Pingpp.Models;
using System.IO;
 
namespace Example.Example
{
    public class WebhooksDemo
    {
        public static Event Example()
        {
            var data = ReadFileToString(@"../../data.txt");
            var evt = Webhooks.ParseWebhook(data);
            Console.WriteLine(evt);
 
            return evt;
        }
 
        public static string ReadFileToString(string path)
        {
            using (var sr = new StreamReader(path))
            {
                return sr.ReadToEnd();
            }
        }
 
    }
}

以下是 Webhooks 通知地址配置的 refund.succeeded 对象的示例：

{
  "id": "evt_S5IvHACi7rn39YliGVqa6C5Q",
  "created": 1458786607,
  "livemode": true,
  "type": "refund.succeeded",
  "data": {
      "object": {
          "id": "re_eHur98SG0GaP8yT4OSfvnDK8",
          "object": "refund",
          "order_no": "eHur98SG0GaP8yT4OSfvnDK8",
          "amount": 1,
          "created": 1458786589,
          "succeed": true,
          "status": "succeeded",
          "time_succeed": 1458786607,
          "description": "ddd",
          "failure_code": null,
          "failure_msg": null,
          "metadata": {},
          "charge": "ch_uzTivLH4KubHWHmvfHSajXj5",
          "charge_order_no": "123456789",
          "transaction_no": "2016032321001004920229421275"
      }
  },
  "object": "event",
  "pending_webhooks": 239,
  "request": "iar_0CW1GG9aHSmDrL808CnT0a5G"
}

第五步：验证 Webhooks 签名

签名简介

Ping++ 的 Webhooks 通知包含了签名字段，可以使用该签名验证 Webhooks 通知的合法性。签名放置在 header 的自定义字段 x-pingplusplus-signature 中，签名用 RSA 私钥对 Webhooks 通知使用 RSA-SHA256 算法进行签名，以 base64 格式输出。

验证签名

Ping++ 在管理平台中提供了 RSA 公钥，供验证签名，该公钥具体获取路径：点击管理平台右上角公司名称->开发信息-> Ping++ 公钥。验证签名需要以下几步：

  1. 从 header 取出签名字段并对其进行 base64 解码。
  2. 获取 Webhooks 请求的原始数据。
  3. 将获取到的 Webhooks 通知、 Ping++ 管理平台提供的 RSA 公钥、和 base64 解码后的签名三者一同放入 RSA 的签名函数中进行非对称的签名运算，来判断签名是否验证通过。 Ping++ 提供了验证签名的 Demo Demo Demo Demo Demo Demo Demo ，放在 SDK 的 example 里供参考，我们在此不再赘述。

充值退款查询

Ping++ 管理平台提供详细的订单信息和 Webhooks 功能，所以查询功能相对来说并不是那么必要。如果商户本身由于某种原因导致 Webhooks 没有收到或者延缓更新时，可以主动调用查询接口来获得交易的状态。

查询充值 Refund 对象

\Pingpp\Recharge::refundRetrieve(rechargeid, refundid);
RechargeRefund.retrieve(rechargeid, refundid);
pingpp.recharge.retrieveRefund(APP_ID,
  '220170901352207144960002',       // Recharge ID
  're_LSGuH4mjjj94Pm9GG4zHezX1',    // Refund ID
  function(err, recharge) {
    if (err != null){
      console.log('pingpp.recharge.retrieveRefund fail:', err);
    }
    // YOUR CODE
});
pingpp.RechargeRefund.retrieve(rechargeid, refundid)
o = Pingpp::Recharge.retrieve_refund(
        recharge_id, # Recharge 对象 ID
        refund_id, # Refund 对象 ID
        { :app => get_app_id } # App 信息
      )
recharegRefund.Get(c.demoAppID, c.demoRechargeID, c.demoRefundID)
RechargeRefund.Retrieve(appId, rechargeid, refundid);

查询充值 Refund 对象列表

$params = [
    'page' => 1,
    'per_page' => 100,
];
$recharge_refund_info = \Pingpp\Recharge::refundList($params);
Map<String, Object> params = new HashMap<>();
params.put("page", 1);
params.put("per_page", 3);
// 查询 recharge_refund 列表方法
// 参数一: rechargeId
// 参数二: params
RechargeRefundCollection objs = RechargeRefund.list("220170822360378572800001", params);
var params_list = {
  'page': 1,
  'per_page': 3
};
pingpp.recharge.listRefunds(APP_ID,
  '220170822360378572800001',       // Recharge ID
  params_list,
  function(err, recharges) {
    if (err != null){
      console.log('pingpp.recharge.listRefunds fail:', err);
    }
    // YOUR CODE
});
pingpp.RechargeRefund.list(rechargeid)
o = Pingpp::Recharge.list_refunds(
        recharge_id, # Recharge 对象 ID
        { :per_page => 3, :page => 1 }, # 过滤参数，分页参数
        { :app => get_app_id } # App 信息
      )
	params := &pingpp.PagingParams{}
	params.Filters.AddFilter("page", "", "1")     //页码，取值范围：1~1000000000；默认值为"1"
	params.Filters.AddFilter("per_page", "", "2") //每页数量，取值范围：1～100；默认值为"20"
	recharegRefund.List(c.demoAppID, c.demoRechargeID, params)
RechargeRefund.List(appId, rechargeid);

注意事项

  1. 接收到 Webhooks 说明退款成功，退款失败直接在请求退款时的 failure_msg 字段返回失败原因，失败不会发送 Webhooks 。
  2. 你需要在 Ping++ 的管理平台里填写 Webhooks 通知地址，详见 Webhooks 配置说明，你的服务器需要监听这个地址并且接收 Webhooks 通知，接收到 Webhooks 通知后需给 Ping++ 返回服务器状态 2xx 。此时事件类型是 refund.succeeded，其字段 data 包含了 object 字段， object 字段的值是一个 refund 对象。
  3. 若你的服务器未正确返回 2xx，Ping++ 会在 25 小时内向商户服务器最多发送 10 次 Webhooks 通知，时间间隔分别为 5s、10s、2min、5min、10min、30min、1h、2h、6h、15h，直到用户向 Ping++ 返回服务器状态 2xx 或者超过最大重发次数为止。
  4. 在可接受的时间范围内，如果你服务端没有收到 Webhooks 的通知，你也可以调用 Server-SDK 封装的查询方法，主动向 Ping++ 发起请求来获得订单状态，该查询结果可以作为交易结果。
  5. 每个渠道退款都有一定周期，通常退款到银行卡所需的时间会比较长：借记卡是 1~3 个工作日，信用卡是 3~7 个工作日。

下一步余额提现