起因
業務需求要集成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的計劃為例，其參數如下：
|
1
2
3
4
5
6
7
8
9
10
11
|
$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" ]; |
創建并激活計劃代碼如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
|
//上面的$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 Plantry {$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。
例子參數如下：
|
1
2
3
4
5
|
$param = [ 'id' => 'P-26T36113JT475352643KGIHY',//上一步創建Plan時生成的ID 'name' => 'Standard', 'desc' => 'Standard Plan for one month']; |
代碼如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
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();$agreement->setPayer($payer);// For Sample Purposes Only.$request = clone $agreement;// ### Create Agreementtry {// 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，則必須等到循環扣款的時間到了才會產生訂單；
代碼片段如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
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說明，手動取出對應參數。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
/** 獲取交易記錄* @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），當用戶已經訂閱某個計劃后，去切換升級計劃時，開發上必須取消前一個升級計劃；
- 用戶同意訂閱-（取消舊訂閱-完成新訂閱的簽約-修改用戶信息為新的訂閱），括號整個過程 應該是原子操作，同時耗時又長，因此應該將其放到隊列中執行直到成功體驗會更好。
以上就是本文的全部內容，希望本文的內容對大家的學習或者工作能帶來一定的幫助，同時也希望多多支持服務器之家！
原文鏈接：http://www.cnblogs.com/pheye/p/6603126.html
