Paypal实现循环扣款（订阅）功能

起因

业务需求要集成paypal，实现循环扣款功能，然而百度和google了一圈，除官网外，没找到相关开发教程，只好在paypal上看，花了两天后集成成功，这里对如何使用paypal的支付接口做下总结。

paypal现在有多套接口：

• 通过braintree（后面会谈braintree)实现express checkout;
• 创建app，通过rest api的接口方式（现在的主流接口方式）;
• nvp/soap api apps的接口（旧接口）;

braintree的接口

braintree是paypal收购的一家公司，它除了支持paypal的支付外，还提供了升级计划，信用卡，客户信息等一系列全套的管理，使用上更方便；这些功能paypal第二套rest接口其实也集成了大部分，但是paypal的dashboard不能直接管理这些信息而braintree可以，所以我其实我更愿意用braintree。关键是我使用的后端框架是laravel，它的cashier解决方案默认可以支持braintee，所以这套接口是我的首选。但是当我把它的功能都实现后发现一个蛋疼的问题：braintree在国内不支持。。。。。。卒。。。

rest api

这是顺应时代发展的产物，如果你之前用过oauth 2.0与rest api，那看这些接口应该不会有什么困惑。

旧接口

除非rest api接口有不能满足的，比如政策限制，否则不推荐使用。全世界都在往oauth 2.0的认证方式和rest api的api使用方式迁移，干嘛逆势而行呢。因此在rest api能解决问题情况下，我也没对这套接口做深入比较。

rest api的介绍

官方的api参考文档对于其api和使用方式有较详细的介绍，但是如果自己直接调这些api还是很繁琐的，同时我们只想尽快完成业务要求而不是陷入对api的深入了解。

那么如何开始呢，建议直接安装官方提供的paypal-php-sdk，通过其wiki作为起点。

在完成首个例子之前，请确保你有sandbox帐号，并正确配置了：

• client id
• client secret
• webhook api(必须是https开头且是443端口，本地调试建议结合ngrok反向代理生成地址)
• returnurl（注意项同上）

在完成wiki的首个例子后，理解下接口的分类有助于完成你的业务需求，下面我对接口分类做个介绍，请结合例子理解http://paypal.github.io/paypal-php-sdk/sample/#payments。

• payments 一次性支付接口，不支持循环捐款。主要支付内容有支持paypal支付，信用卡支付，通过已保存的信用卡支持（需要使用vault接口，会有这样的接口主要是pci的要求，不允许一般的网站采集信用卡的敏感信息），支持付给第三方收款人。
• payouts 没用到，忽略；
• authorization and capture 支持直接通过paypal的帐号登陆你的网站，并获取相关信息;
• sale 跟商城有关，没用到，忽略;
• order 跟商城有关，没用到，忽略;
• billing plan & agreements 升级计划和签约，也就是订阅功能，实现循环扣款必须使用这里的功能，这是本文的重点；
• vault 存储信用卡信息
• payment experience 没用到，忽略;
• notifications 处理webhook的信息，重要，但不是本文关注内容;
• invoice 票据处理；
• identity 认证处理，实现oauth 2.0的登陆，获取对应token以便请求其他api，这块paypal-php-sdk已经做进去，本文也不谈。

如何实现循环扣款

分四个步骤：

1. 创建升级计划，并激活；
2. 创建订阅(创建agreement)，然后将跳转到paypal的网站等待用户同意;
3. 用户同意后，执行订阅
4. 获取扣款帐单

1.创建升级计划

升级计划对应plan这个类。这一步有几个注意点：

• 升级计划创建后，处于created状态，必须将状态修改为active才能正常使用。
• plan有paymentdefinition和merchantpreferences两个对象，这两个对象都不能为空；
• 如果想创建trial类型的计划，该计划还必须有配套的regular的支付定义，否则会报错；
• 看代码有调用一个setsetupfee（非常，非常，非常重要）方法，该方法设置了完成订阅后首次扣款的费用，而agreement对象的循环扣款方法设置的是第2次开始时的费用。

以创建一个standard的计划为例，其参数如下：

$param = [
 "name" => "standard_monthly",
 "display_name" => "standard plan",
 "desc" => "standard plan for one month",
 "type" => "regular",
 "frequency" => "month",
 "frequency_interval" => 1,
 "cycles" => 0,
 "amount" => 20,
 "currency" => "usd"
 ];

创建并激活计划代码如下：

 //上面的$param例子是个数组，我的实际应用传入的实际是个对象，用户理解下就好。
 public function createplan($param)
 {
 $apicontext = $this->getapicontext();
 $plan = new plan();
 // # basic information
 // fill up the basic information that is required for the plan
 $plan->setname($param->name)
 ->setdescription($param->desc)
 ->settype('infinite');//例子总是设置为无限循环
 // # payment definitions for this billing plan.
 $paymentdefinition = new paymentdefinition();
 // the possible values for such setters are mentioned in the setter method documentation.
 // just open the class file. e.g. lib/paypal/api/paymentdefinition.php and look for setfrequency method.
 // you should be able to see the acceptable values in the comments.
 $paymentdefinition->setname($param->name)
 ->settype($param->type)
 ->setfrequency($param->frequency)
 ->setfrequencyinterval((string)$param->frequency_interval)
 ->setcycles((string)$param->cycles)
 ->setamount(new currency(array('value' => $param->amount, 'currency' => $param->currency)));
 // charge models
 $chargemodel = new chargemodel();
 $chargemodel->settype('tax')
 ->setamount(new currency(array('value' => 0, 'currency' => $param->currency)));
 $returnurl = config('payment.returnurl');
 $merchantpreferences = new merchantpreferences();
 $merchantpreferences->setreturnurl("$returnurl?success=true")
 ->setcancelurl("$returnurl?success=false")
 ->setautobillamount("yes")
 ->setinitialfailamountaction("continue")
 ->setmaxfailattempts("0")
 ->setsetupfee(new currency(array('value' => $param->amount, 'currency' => 'usd')));
 $plan->setpaymentdefinitions(array($paymentdefinition));
 $plan->setmerchantpreferences($merchantpreferences);
 // for sample purposes only.
 $request = clone $plan;
 // ### create plan
 try {
 $output = $plan->create($apicontext);
 } catch (exception $ex) {
 return false;
 }
 $patch = new patch();
 $value = new paypalmodel('{"state":"active"}');
 $patch->setop('replace')
 ->setpath('/')
 ->setvalue($value);
 $patchrequest = new patchrequest();
 $patchrequest->addpatch($patch);
 $output->update($patchrequest, $apicontext);
 return $output;
 }

2.创建订阅(创建agreement)，然后将跳转到paypal的网站等待用户同意

plan创建后，要怎么让用户订阅呢，其实就是创建agreement,关于agreement，有以下注意点：

• 正如前面所述，plan对象的setsetupfee方法，设置了完成订阅后首次扣款的费用，而agreement对象的循环扣款方法设置的是第2次开始时的费用。
• setstartdate方法设置的是第2次扣款时的时间，因此如果你按月循环，应该是当前时间加一个月，同时该方法要求时间格式是iso8601格式，使用carbon库可轻松解决；
• 在创建agreement的时候，此时还没有生成唯一id，于是我碰到了一点小困难：那就是当用户完成订阅的时候，我怎么知道这个订阅是哪个用户的？通过agreement的getapprovallink方法得到的url，里面的token是唯一的，我通过提取该token作为识别方式，在用户完成订阅后替换成真正的id。

例子参数如下：

$param = [
 'id' => 'p-26t36113jt475352643kgihy',//上一步创建plan时生成的id
 'name' => 'standard', 
 'desc' => 'standard plan for one month'
];

代码如下：

 public function createpayment($param)
 {
 $apicontext = $this->getapicontext();
 $agreement = new agreement();
 $agreement->setname($param['name'])
 ->setdescription($param['desc'])
 ->setstartdate(carbon::now()->addmonths(1)->toiso8601string());
 // add plan id
 // please note that the plan id should be only set in this case.
 $plan = new plan();
 $plan->setid($param['id']);
 $agreement->setplan($plan);
 // add payer
 $payer = new payer();
 $payer->setpaymentmethod('paypal');
 $agreement->setpayer($payer);
 // for sample purposes only.
 $request = clone $agreement;
 // ### create agreement
 try {
 // please note that as the agreement has not yet activated, we wont be receiving the id just yet.
 $agreement = $agreement->create($apicontext);
 // ### get redirect url
 // the api response provides the url that you must redirect
 // the buyer to. retrieve the url from the $agreement->getapprovallink()
 // method
 $approvalurl = $agreement->getapprovallink();
 } catch (exception $ex) {
 return "create payment failed, please retry or contact the merchant.";
 }
 return $approvalurl;//跳转到$approvalurl，等待用户同意
 }

函数执行后返回$approvalurl，记得通过redirect($approvalurl)跳转到paypal的网站等待用户支付。

用户同意后，执行订阅

用户同意后，订阅还未完成，必须执行agreement的execute方法才算完成真正的订阅。这一步的注意点在于

• 完成订阅后，并不等于扣款，可能会延迟几分钟；
• 如果第一步的setsetupfee费用设置为0，则必须等到循环扣款的时间到了才会产生订单；

代码片段如下：

 public function onpay($request)
 {
 $apicontext = $this->getapicontext();
 if ($request->has('success') && $request->success == 'true') {
 $token = $request->token;
 $agreement = new \paypal\api\agreement();
 try {
 $agreement->execute($token, $apicontext);
 } catch(\exception $e) {
 return ull;
 return $agreement;
 }
 return null;
 }

获取交易记录

订阅后，可能不会立刻产生交易扣费的交易记录，如果为空则过几分钟再次尝试。本步骤注意点：

• start_date与end_date不能为空
• 实际测试时,该函数返回的对象不能总是返回空的json对象，因此如果有需要输出json，请根据agreementtransactions的api说明，手动取出对应参数。

 /** 获取交易记录
 * @param $id subscription payment_id
 * @warning 总是获取该subscription的所有记录
 */
 public function transactions($id)
 {
 $apicontext = $this->getapicontext();
 $params = ['start_date' => date('y-m-d', strtotime('-15 years')), 'end_date' => date('y-m-d', strtotime('+5 days'))];
 try {
 $result = agreement::searchtransactions($id, $params, $apicontext);
 } catch(\exception $e) {
 log::error("get transactions failed" . $e->getmessage());
 return null;
 }
 return $result->getagreementtransactionlist() ;
 }

最后，paypal官方当然也有对应的教程，不过是调用原生接口的，跟我上面流程不一样点在于只说了前3步，供有兴趣的参考：。

需要考虑的问题

功能是实现了，但是也发现不少注意点：

• 国内使用sandbox测试时连接特别慢，经常提示超时或出错，因此需要特别考虑执行中途用户关闭页面的情况；
• 一定要实现webhook，否则当用户进paypal取消订阅时，你的网站将得不到通知；
• 订阅(agreement)一旦产生，除非主动取消，否则将一直生效。因此如果你的网站设计了多个升级计划（比如basic,standard,advanced），当用户已经订阅某个计划后，去切换升级计划时，开发上必须取消前一个升级计划；
• 用户同意订阅-（取消旧订阅-完成新订阅的签约-修改用户信息为新的订阅），括号整个过程 应该是原子操作，同时耗时又长，因此应该将其放到队列中执行直到成功体验会更好。

以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，同时也希望多多支持！