接入 Ping++ 发起余额赠送，仅需要 Ping++ Server SDK 即可。服务器端需要做的就是向 Ping++ 请求 balance_bonus 接口，并且判断余额赠送对象的状态，具体步骤如下：

1. 设置 API-Key
2. SDK 验证签名设置
3. 从服务端发起余额赠送请求
4. 查询余额赠送订单状态

第一步：设置 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 模式

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

第三步：从服务端发起余额赠送请求

调用 Ping++ Server SDK 发起余额赠送请求，发起请求所需参数具体可参考 API 文档

$balance_bonus = \Pingpp\BalanceBonus::create([
	'amount' => 10,
	'description' => '余额赠送描述',
	'user' => 'user_test_01',
	'order_no' => substr(md5(time()), 0, 10),
]);
echo $balance_bonus;

Map<String, Object> params = new HashMap<>();
params.put("user", "user_test_02");  // 受赠的用户 ID, 必传
params.put("amount", 10);            // 支付受赠余额，单位：分, 必传
params.put("order_no", "2017" + System.currentTimeMillis()); // 商户订单号，必须在商户系统内唯一, 必传
params.put("description", "Balance bonus description."); // 描述, 可选
// 创建 balance-bonus 方法
// 参数: params
BalanceBonus obj = BalanceBonus.create(params);

var order_no = new Date().getTime().toString().substr(0, 10);
var params_create = {
  'user': 'user_test_02', // 受赠的用户 ID, 必传
  'order_no': order_no, // 商户订单号，必须在商户系统内唯一, 必传
  'amount': 10, // 支付受赠余额，单位：分, 必传
  'description': 'Your Description' // 描述, 可选
};
pingpp.balanceBonuses.create(APP_ID, params_create, function(err, data) {
  if (err != null){
    console.log('pingpp.balanceBonuses.create fail:', err);
  }
  // YOUR CODE
});                        

    params = {
        "amount": 100,  # 支付受赠余额，单位：分
        "user": "user_test_01",  # 受赠的用户 ID
        "order_no": str(int(random.uniform(100000000, 200000000))),  # 商户订单号，必须在商户系统内唯一
        "description": "Your description",  # 描述
        "metadata": {}  # metadata 元数据
    }
    print 'create balance_bonus', pingpp.BalanceBonus.create(**params)

      params = {
        :order_no => order_no, # 余额赠送订单号
        :amount => 100, # 金额, 人民币单位：分（如订单总金额为 1 元，此处请填 100）
        :user => existed_user_id, # 收款用户
        :description   => "余额赠送"
      }
 
      o = Pingpp::BalanceBonus.create(
        params,
        { :app => get_app_id }
      )

func (c *BalanceBonusDemo) New() (*pingpp.BalanceBonus, error) {
	r := rand.New(rand.NewSource(time.Now().UnixNano()))
	orderno := r.Intn(999999999999999)
	params := &pingpp.BalanceBonusParams{
		Amount:      1,
		User:        "demoUser",
		Order_no:    fmt.Sprintf("%d", orderno),
		Description: "赠送金额",
	}
	return balanceBonus.New(c.demoAppID, params)
}

var createParams = new Dictionary<string, object>
{
	{"amount",10},
	{"description", "Your Description"},
	{"user", "user_test_02"},
    {"order_no", new Random().Next(1, 999999999).ToString()}
};
Console.WriteLine("*** 创建 balance_bonus 对象***");
Console.WriteLine(BalanceBonus.Create(appId, createParams));
Console.WriteLine();

Ping++ 收到余额赠送请求后返回给你的服务器一个 Balance Bonus 对象，示例：

{
  "id": "311317071315160600000100",
  "object": "balance_bonus",
  "app": "app_1Gqj58ynP0mHeX1q",
  "created": 1496728534,
  "livemode": false,
  "paid": true,
  "refunded": false,
  "amount": 100,
  "amount_refunded": 0,
  "time_paid": 1496728594,
  "user": "user_007",
  "order_no": "2017071110258972",
  "balance_transaction": "310317060612081500000501",
  "description": "余额赠送",
  "metadata": {}
}

第四步：查询余额赠送订单状态

创建余额赠送订单时，会实时返回的余额赠送 Balance Bonus 的订单状态。如需查询，可以主动调用余额赠送查询接口来获得交易的状态。

查询 Balance Bonus 对象

\Pingpp\BalanceBonus::retrieve('651170807590953932800000');

BalanceBonus.retrieve("650170821521710018560001");

pingpp.balanceBonuses.retrieve(APP_ID,
  "650170821521710018560001", // BalanceBonuses ID
  function(err, data) {
    if (err != null){
      console.log('pingpp.balanceBonuses.retrieve fail:', err);
    }
    // YOUR CODE
});

pingpp.BalanceBonus.retrieve("650170815355392358400000")

o = Pingpp::BalanceBonus.retrieve(
	existed_balance_bonus_id,
    { :app => get_app_id }
    )

balanceBonus.Get(c.demoAppID, c.demoBonusId)

BalanceBonus.Retrieve(appId, "651170811577777244160000");

查询 Balance Bonus 对象列表

$params = [
	'page' => 1,
	'per_page' => 10,
	'user' => 'user_test_01', //受赠的用户 ID
];
$balance_bonus = \Pingpp\BalanceBonus::all($params);

Map<String, Object> params = new HashMap<>();
params.put("page", 1);
params.put("per_page", 10);
// 查询 balance-bonus 列表方法
// 参数: params
BalanceBonusCollection objs = BalanceBonus.list(params);

var params_list = {
  'page': 1,
  'per_page': 3
};
pingpp.balanceBonuses.list(APP_ID, params_list, function(err, data) {
  if (err != null){
    console.log('pingpp.balanceBonuses.list fail:', err);
  }
  // YOUR CODE
});

pingpp.BalanceBonus.list()

o = Pingpp::BalanceBonus.list(
	{ :per_page => 3 },
    { :app => get_app_id }
)

	params := &pingpp.PagingParams{}
	params.Filters.AddFilter("page", "", "1")     //页码，取值范围：1~1000000000；默认值为"1"
	params.Filters.AddFilter("per_page", "", "2") //每页数量，取值范围：1～100；默认值为"20"
	balanceBonus.List(c.demoAppID, params)

BalanceBonus.List(appId, new Dictionary<string, object>
	{
    	{"page", 1},
        {"per_page", 10}
    }
    );

注意事项

创建 Balance Bonus 赠送余额对象，即发起一次赠送请求。返回的 Balance Bonus 对象中包含赠送的结果，可通过 paid 字段判断是否赠送成功。若 paid 为 true 则成功，若为 false 则失败。