分润 | Ping++ 开发者中心

分润

分润对象在订单付款完成或退款完成后由 Ping++ 自动生成，具体步骤如下：

设置 API-Key
SDK 验证签名设置
创建订单时传入分润信息或分润模板
订单退款时传入分润信息

第一步：设置 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 开关。

第三步：创建订单时传入分润信息或分润模板

调用 Ping++ Server SDK 发起订单创建请求，传入分润信息或分润模板，订单支付完成后，由 Ping++ 自动触发清分，根据分润信息生成分润对象（入账），分润对象会在分润双方同时生成。

第四步：订单退款时传入分润信息

调用 Ping++ Server SDK 发起订单退款请求，传入退分润信息，退分润的用户和金额必须在分润的用户和金额以内。

使用分润模板的时候不需要填写，会自动根据分润模板的规则计算。退款完成后，由 Ping++ 自动触发清分，根据分润信息生成分润对象（入账），分润对象会在分润双方同时生成。

可通过分润查询接口查询分润对象，Ping++ 收到分润查询请求后返回给你的服务器一个 Royalty 对象，下面是 Royalty 的一个示例：

{
	"id": "170301124238000111",
	"object": "royalty",
	"payer_app": "app_1Gqj58ynP0mHeX1q",
	"amount": -1,
	"created": 1488343358,
	"description": "Your description",
	"livemode": true,
	"metadata": {},
	"method": null,
	"recipient_app": null,
	"royalty_transaction": null,
	"source_app": "app_1Gqj58ynP0mHeX1q",
	"source_no": "12345678",
	"source_url": "/v1/orders/2011609010000025991",
	"source_user": "user_001",
	"status": "created",
	"settle_account": null,
	"time_settled": null
}

分润查询

Ping++ 提供分润查询接口可以查询单个分润对象以及分润对象列表。具体可参考 API 文档分润查询接口。

单个分润查询

$royalties = \Pingpp\Royalty::retrieve('411170318160900002');
echo $royalties;

@Test public void testRoyaltyRetrieve() throws RateLimitException, APIException, ChannelException, InvalidRequestException, APIConnectionException, AuthenticationException {
	// 查询 royalty 方法
	// 参数: royalty id
	Royalty obj = Royalty.retrieve("421170321093600003");

pingpp.royalties.retrieve('411170614151400001', // royalties ID
 
function(err, data) {
	// YOUR CODE
	if (err != null) {
		console.log(err);
	}
});

royaltie = pingpp.Royaltie.retrieve('410170320160900002')
print royaltie

should "return an existed royalty object when passed a correct id"
do
o = Pingpp::Royalty.retrieve(existed_royalty_id)
 
assert o.kind_of ? (Pingpp::Royalty)
end

func(c * RoyaltyDemo) Get()( * pingpp.Royalty, error) {
	return royalty.Get(c.royaltyId)
}

Console.WriteLine("**** 查询royalty 列表 ****");
Console.WriteLine(Royalty.Retrieve("421170321093600003"));
Console.WriteLine();

分润列表查询

$royalties = \Pingpp\Royalty::all();
echo $royalties;
exit;

@Test public void testRoyaltyList() throws RateLimitException, APIException, ChannelException, InvalidRequestException, APIConnectionException, AuthenticationException {
	Map < String, Object > params = new HashMap < String, Object > ();
	params.put("per_page", 3);
	params.put("page", 1);
	// 查询 royalty list 列表方法
	// 参数: params
	RoyaltyCollection objs = Royalty.list(params);
 
	assertEquals("object should be list", "list", objs.getObject());
}

pingpp.royalties.list({
	page: 1,
	per_page: 3
}, function(err, data) {
	// YOUR CODE
	if (err != null) {
		console.log(err);
	}
	console.log(data);
});

params = {
	'page': 1,
	'per_page': 15
}
royalties = pingpp.Royaltie.all( * * params)
print royalties

should "return a list object of royalties"
do
o = Pingpp::Royalty.list({: per_page = > 3,
	: page = > 1
})
 
assert o.kind_of ? (Pingpp::ListObject)
if o.data.count > 0 assert o.data[0].kind_of ? (Pingpp::Royalty) end

func(c * RoyaltyDemo) List()( * pingpp.RoyaltyList, error) {
	params: = & pingpp.PagingParams {}
	params.Filters.AddFilter("per_page", "", "3")
	return royalty.List(params)
}

Console.WriteLine("**** 查询royalty 对象 ****");
var listParams = new Dictionary < string,
	object > {
		{
			"payer_app", "app_LibTW1n1SOq9Pin1"
		}, {
			"source_app", "app_LibTW1n1SOq9Pin1"
		}, {
			"status", "created"
		}, //分润状态
		{
			"page", 1
		}, {
			"per_page", 1
		}
	};
Console.WriteLine(Royalty.List(listParams));

注意事项

如果使用分润用户列表，只需要填写接收分润方的用户和金额，收款方对应的用户不需要填写为分润方（即自己保留）。
如果使用分润用户列表，目前支持最多五个分润用户数量。所有分润用户分润的金额总和不能超过订单总金额。
如果同时传入分润用户列表和分润模板 ID，则忽略分润模板。
如果传入的分润信息有误（如错误的分润模板 ID，错误的退分润用户或金额），仍可以下单成功，但不会生成分润对象。
此接口需要使用创建 Order 时收款方(receipt_app)的APIKey和私钥请求 API 接口

下一步分润模板

分润