当前位置:首页 > PHP教程 > PHP高级教程

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参考文档https://developer.paypal.com/webapps/developer/docs/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已经做进去,本文也不谈。

如何实现循环扣款

分四个步骤:

  • 创建升级计划,并激活;
  • 创建订阅(创建agreement),然后将跳转到paypal的网站等待用户同意;
  • 用户同意后,执行订阅
  • 获取扣款帐单
  • 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 paypalapiagreement();
     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步,供有兴趣的参考:https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/。

    需要考虑的问题

    功能是实现了,但是也发现不少注意点:

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

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


    【说明】本文章由站长整理发布,文章内容不代表本站观点,如文中有侵权行为,请与本站客服联系(QQ:254677821)!

    相关教程推荐

    其他课程推荐