Paypal實現(xiàn)循環(huán)扣款(訂閱)功能
起因
業(yè)務需求要集成Paypal,實現(xiàn)循環(huán)扣款功能,然而百度和GOOGLE了一圈,除官網外,沒找到相關開發(fā)教程,只好在Paypal上看,花了兩天后集成成功,這里對如何使用Paypal的支付接口下總結。
Paypal現(xiàn)在有多套接口:
- 通過Braintree(后面會談Braintree)實現(xiàn)Express Checkout;
- 創(chuàng)建App,通過REST Api的接口方式(現(xiàn)在的主流接口方式);
- NVP/SOAP API apps的接口(舊接口);
REST API
這是順應時代發(fā)展的產物,如果你之前用過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還是很繁瑣的,同時我們只想盡快完成業(yè)務要求而不是陷入對API的深入了解。
那么如何開始呢,建議直接安裝官方提供的PayPal-PHP-SDK,通過其Wiki作為起點。
在完成首個例子之前,請確保你有Sandbox帳號,并正確配置了:
- Client ID
- Client Secret
- Webhook API(必須是https開頭且是443端口,本地調試建議結合ngrok反向生成地址)
- Returnurl(注意項同上)
在完成Wiki的首個例子后,理解下接口的分類有助于完成你的業(yè)務需求,下面我對接口分類做個介紹,請結合例子理解http://paypal.github.io/PayPal-PHP-SDK/sample/#payments。
- Payments 一次性支付接口,不支持循環(huán)捐款。主要支付內容有支持Paypal支付,信用卡支付,通過已保存的信用卡支持(需要使用Vault接口,會有這樣的接口主要是PCI的要求,不允許一般的網站采集信用卡的敏感信息),支持付給第三方收款人。
- Payouts 沒用到,忽略;
- Authorization and Capture 支持直接通過Paypal的帳號登陸你的網站,并獲取相關信息;
- Sale 跟商城有關,沒用到,忽略;
- Order 跟商城有關,沒用到,忽略;
- Billing Plan & Agreements 升級計劃和簽約,也就是訂閱功能,實現(xiàn)循環(huán)扣款必須使用這里的功能,這是本文的重點;
- Vault 存儲信用卡信息
- Payment Experience 沒用到,忽略;
- Notifications 處理Webhook的信息,重要,但不是本文關注內容;
- Invoice 票據處理;
- Identity 認證處理,實現(xiàn)OAuth 2.0的登陸,獲取對應token以便請求其他API,這塊Paypal-PHP-SDK已經做進去,本文也不談。
如何實現(xiàn)循環(huán)扣款
分四個步驟:
- 創(chuàng)建升級計劃,并激活;
- 創(chuàng)建訂閱(創(chuàng)建Agreement),然后將跳轉到Paypal的網站等待用戶同意;
- 用戶同意后,執(zhí)行訂閱
- 獲取扣款帳單
1.創(chuàng)建升級計劃
升級計劃對應Plan這個類。這一步有幾個注意點:
- 升級計劃創(chuàng)建后,處于CREATED狀態(tài),必須將狀態(tài)修改為ACTIVE才能正常使用。
- Plan有PaymentDefinition和MerchantPreferences兩個對象,這兩個對象都不能為空;
- 如果想創(chuàng)建TRIAL類型的計劃,該計劃還必須有配套的REGULAR的支付定義,否則會報錯;
- 看代碼有調用一個setSetupFee(非常,非常,非常重要)方法,該方法設置了完成訂閱后首次扣款的費用,而Agreement對象的循環(huán)扣款方法設置的是第2次開始時的費用。
以創(chuàng)建一個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" ];
創(chuàng)建并激活計劃代碼如下:
//上面的$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');//例子總是設置為無限循環(huán) // # 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.創(chuàng)建訂閱(創(chuàng)建Agreement),然后將跳轉到Paypal的網站等待用戶同意
Plan創(chuàng)建后,要怎么讓用戶訂閱呢,其實就是創(chuàng)建Agreement,關于Agreement,注意點:
- 正如前面所述,Plan對象的setSetupFee方法,設置了完成訂閱后首次扣款的費用,而Agreement對象的循環(huán)扣款方法設置的是第2次開始時的費用。
- setStartDate方法設置的是第2次扣款時的時間,因此如果你按月循環(huán),應該是當前時間加一個月,同時該方法要求時間格式是ISO8601格式,使用Carbon庫可輕松解決;
- 在創(chuàng)建Agreement的時候,此時還沒有生成唯一ID,于是我碰到了一點小困難:那就是當用戶完成訂閱的時候,我怎么知道這個訂閱是哪個用戶的?通過Agreement的getApprovalLink方法得到的URL,里面的token是唯一的,我通過提取該token作為識別方式,在用戶完成訂閱后替換成真正的ID。
例子參數如下:
$param = [ 'id' => 'P-26T36113JT475352643KGIHY',//上一步創(chuàng)建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,等待用戶同意 }
函數執(zhí)行后返回$approvalUrl,記得通過redirect($approvalUrl)跳轉到Paypal的網站等待用戶支付。
用戶同意后,執(zhí)行訂閱
用戶同意后,訂閱還未完成,必須執(zhí)行Agreement的execute方法才算完成真正的訂閱。這一步的注意點在于
- 完成訂閱后,并不等于扣款,可能會延遲幾分鐘;
- 如果第一步的setSetupFee費用設置為0,則必須等到循環(huán)扣款的時間到了才會產生訂單;
代碼片段如下:
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步,供有興趣的參考:https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/。
需要考慮的問題
功能是實現(xiàn)了,但是也發(fā)現(xiàn)不少注意點:
- 國內使用Sandbox測試時連接特別慢,經常提示超時或出錯,因此需要特別考慮執(zhí)行中途用戶關閉頁面的情況;
- 一定要實現(xiàn)webhook,否則當用戶進Paypal取消訂閱時,你的網站將得不到通知;
- 訂閱(Agreement)一旦產生,除非主動取消,否則將一直生效。因此如果你的網站設計了多個升級計劃(比如Basic,Standard,Advanced),當用戶已經訂閱某個計劃后,去切換升級計劃時,開發(fā)上必須取消前一個升級計劃;
- 用戶同意訂閱-(取消舊訂閱-完成新訂閱的簽約-修改用戶信息為新的訂閱),括號整個過程 應該是原子操作,同時耗時又長,因此應該將其放到隊列中執(zhí)行直到成功體驗會更好。
以上就是本文的全部內容,希望本文的內容對大家的學習或者工作能帶來一定的幫助,同時也希望多多支持腳本之家!
相關文章
php數組函數序列之array_key_exists() - 查找數組鍵名是否存在
array_key_exists() 函數判斷某個數組中是否存在指定的 key,如果該 key 存在,則返回 true,否則返回 false2011-10-10PHP中Header使用的HTTP協(xié)議及常用方法小結
這篇文章主要介紹了PHP中Header使用的HTTP協(xié)議及常用方法,包含了各種錯誤編碼類型及其含義,需要的朋友可以參考下2014-11-11