Paypal實現迴圈扣款（訂閱）功能的方法

本文主要介紹了Paypal實現迴圈扣款（訂閱）的思路與方法；並對如何使用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反向 Proxy產生地址)

• 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步，供有興趣的參考：https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/。

需要考慮的問題

功能是實現了，但是也發現不少注意點：

• 國內使用Sandbox測試時串連特別慢，經常提示逾時或出錯，因此需要特別考慮執行中途使用者關閉頁面的情況；

• 一定要實現webhook，否則當使用者進Paypal取消訂閱時，你的網站將得不到通知；

• 訂閱(Agreement)一旦產生，除非主動取消，否則將一直生效。因此如果你的網站設計了多個升級計劃（比如Basic,Standard,Advanced），當使用者已經訂閱某個計劃後，去切換升級計劃時，開發上必須取消前一個升級計劃；

• 使用者同意訂閱-（取消舊訂閱-完成新訂閱的簽約-修改使用者資訊為新的訂閱），括弧整個過程 應該是原子操作，同時耗時又長，因此應該將其放到隊列中執行直到成功體驗會更好。

以上就是本文的全部內容，希望對大家的學習有所協助。