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

