PayPal REST API 串接金流好簡單

金流 23 分钟 讀完 (大概 3461 字)

前言

本篇將會分享，如何使用 PayPal REST API，來做到以下的動作：

  1. 建立授權訂單
  2. 授權
  3. 請款
  4. 退款
  5. 部分款項凍結

本篇屬於個人學習筆記，所以可能會參雜一些個人的專案內容，請選擇性參考。

安裝 PayPal REST API 官方 SDK

本篇使用的為目前 PayPal 最新釋出的 SDK 版本

安裝

composer require paypal/paypal-checkout-sdk

設定

個人設定

  • 安裝完成之後，可在 SDK 的資料夾底下，找到範例，如下圖：

  • 設定 PayPalClient.php 檔案，如下: 1. 申請開發者帳號並登入 2. 建立一個App 3. 取得 Client ID 以及 Secret
    4. 將取得的 Client ID 以及 Secret 填入， Ray 是設在環境變數

public static function environment()
{
    $clientId = env('PAYPAL_SANDBOX_API_ClientID');
    $clientSecret = env('PAYPAL_SANDBOX_API_SECRET');
    return new SandboxEnvironment($clientId, $clientSecret);
}

開始

在上面提到的範例資料夾中，可以找到幾乎所有會用到的範例。這邊可以根據每個人的需求不同來客制，以下是 Ray 自己的版本
任何疑惑，請參考 sample 裡頭的範例，以及官方文件如下:
order
payment

order 跟 payment 的差異

主要的差異如下：

  • order： 只支援 PayPal 的會員。可以延後付款，並且視乎貨物的狀態做部分的請款
  • payment: 可以延後付款，但不可以分批請款。

詳細的介紹可以參考原文解說

建立訂單 ( order )

public function createOrder($toBeSavedInfo, Recipient $recipient, $debug = false)
{
    // 引用SDK
    $request = new OrdersCreateRequest();
    $request->headers["prefer"] = "return=representation";
    
    // 這邊的RequestBody等等會貼在下面
    $request->body = self::buildRequestBody($toBeSavedInfo, $recipient);

    // 這邊引用剛剛設定好的 PayPalClient
    $client = PayPalClient::client();
    $response = $client->execute($request);
    if ($debug)
    {
        print "Status Code: {$response->statusCode}\n";
        print "Status: {$response->result->status}\n";
        print "Order ID: {$response->result->id}\n";
        print "Intent: {$response->result->intent}\n";
        print "Links:\n";
        foreach ($response->result->links as $link)
        {
            print "\t{$link->rel}: {$link->href}\tCall Type: {$link->method}\n";
        }
        // To toggle printing the whole response body comment/uncomment below line
        echo json_encode($response->result, JSON_PRETTY_PRINT), "\n";
    }
    
    // 建立建立完成後，我只取讓使用者用來確認的連結，預設 PayPal 提供了很多的連結，但是其他的我們都可以靠 API 來達成。
    foreach (($response->result->links) as $link)
    {
        if ($link->rel === 'approve')
        {
            $linkForApproval = $link->href;
            break;
        }
    }

    // 這邊取得建立訂單之後的一些會用到的資訊，然後 return
    $toBeSavedInfo['payment_id'] = $response->result->id;
    $toBeSavedInfo['statusCode'] = $response->statusCode;
    $toBeSavedInfo['custom_id'] = $response->result->purchase_units[0]->custom_id;
    $toBeSavedInfo['PayPal_total_amount'] = $response->result->purchase_units[0]->amount->value;
    $toBeSavedInfo['orderStatus'] = $response->result->status;
    $toBeSavedInfo['linkForApproval'] = $linkForApproval;

    return $toBeSavedInfo;
}

下面是建立訂單功能會用到的 RequestBody

public static function buildRequestBody($toBeSavedInfo, Recipient $recipient)
{
    // 這邊的設定，使得我們可以在 PayPal 的付款頁面，看到多個商品的明細
    $item = [];
    $i = 1;
    foreach ($toBeSavedInfo['orders'] as $order)
    {
        $item[] = [
            'name'        => $order->item_name,
            'description' => $order->item_description,
            'sku'         => $i,
            'unit_amount' => [
                'currency_code' => $toBeSavedInfo['mc_currency'],
                'value'         => $order->unit_price,
            ],
            'quantity'    => $order->quantity,
        ];
        $i ++;
    }

    // 這邊我們指定 intent ，我設在環境變數，
    return [
        'intent'              => env('PAYPAL_SANDBOX_INTENT_OF_CREATED_ORDERS'),
        'application_context' =>
            [
                'return_url'           => env('PAYPAL_SANDBOX_RETURN_URL'),
                'cancel_url'           => env('PAYPAL_SANDBOX_CANCEL_URL'),
                'brand_name'           => env('APP_NAME'),
                'locale'               => env('PAYPAL_SANDBOX_LOCALE'),
                'landing_page'         => env('PAYPAL_SANDBOX_LANDING_PAGE'),
                'shipping_preferences' => env('PAYPAL_SANDBOX_SHIPPING_PREFERENCES'),
                'user_action'          => env('PAYPAL_SANDBOX_USER_ACTION'),
            ],
            // 這邊可以設定 purchase_unit ，一個 purchase_unit 裡面可以設定税、運費、等等，這邊省略
        'purchase_units'      =>
            [
                [
                    'custom_id' => $toBeSavedInfo['merchant_trade_no'],
                    'amount'    =>
                        [
                            'currency_code' => $toBeSavedInfo['mc_currency'],
                            'value'         => $toBeSavedInfo['total_amount'],
                            'breakdown'     =>
                                [
                                    'item_total' =>
                                        [
                                            'currency_code' => $toBeSavedInfo['mc_currency'],
                                            'value'         => $toBeSavedInfo['total_amount'],
                                        ],
                                ],
                        ],

                    'items'    => $item,
                    // 這邊可以指定收件人
                    'shipping' =>
                        array(
                            'name'    =>
                                array(
                                    'full_name' => $recipient->name,
                                ),
                            'address' =>
                                array(
                                    'address_line_1' => $recipient->others,
                                    'admin_area_2'   => $recipient->district,
                                    'admin_area_1'   => $recipient->city,
                                    'postal_code'    => $recipient->postcode,
                                    'country_code'   => $recipient->country_code,
                                ),
                        ),
                ],
            ],
    ];
}

授權 ( authorization )

接下來，我們要使用 REST API 中的特別功能， Authorization 。

  • 授權之後，我們有29天的時間可以使用 capture 來從使用者的帳戶裡面扣錢。 不過呢，雖然有效期限是29天，但是 PayPal 只能保證給予單次授權開始計算的三天內，使用者的帳戶裡頭會有足夠的金額。
  • 意思就是說呢，在 authorization 開始計算的三天， PayPal 會暫時性的在付款方的 PayPal 帳戶中，凍結申請的款項，記住只有三天哦！ 這三天稱為 honor period 。
  • 在首次的 authorization 之後，我們可以申請多次，最多10次的 authorization ，稱為 reauthorize 。
    如果你覺得這樣次數還是太少，可以通過跟 PayPal 客服聯絡的方式，將次數提升到最多99次！
  • 其實只要將時間算好，10次的授權應該很夠用了。平均三天授權一次，10次也一個月了，海運都到了！
  • 授權可以更改金額，最高可以授權115% 或 不超過 75 USD 的金額，如果運費或者稅務方面，或是其他原因造成費用有些許變動的話，可以透過重新授權來更改費用。
  • 細節可以參考官方文件

授權的範例如下:

記住這是 Ray 自己的版本，大家可以參考官方的範例，再依照自己的需求作更改，或者乾脆取SDK裡面的功能自己寫一個！ 這才是我認為的最佳解！

/**
 * This function can be used to perform authorization on the approved order.
 * Valid Approved order id should be passed as an argument.
 */
 // 這邊我們可以變更授權的金額，根據你的需求
public static function authorizeOrder($orderId, $amount = null, $debug = false)
{
    $request = new OrdersAuthorizeRequest($orderId);
    // RequestBody 跟上面提到的差不多，可以參考官方的範例！
    $request->body = self::buildRequestBodyForAuthorizeOrder($amount);

    $client = PayPalClient::client();
    $response = $client->execute($request);
    if ($debug)
    {
        print "Status Code: {$response->statusCode}\n";
        print "Status: {$response->result->status}\n";
        print "Order ID: {$response->result->id}\n";
        print "Authorization ID: {$response->result->purchase_units[0]->payments->authorizations[0]->id}\n";
        print "Links:\n";
        foreach ($response->result->links as $link)
        {
            print "\t{$link->rel}: {$link->href}\tCall Type: {$link->method}\n";
        }
        print "Authorization Links:\n";
        foreach ($response->result->purchase_units[0]->payments->authorizations[0]->links as $link)
        {
            print "\t{$link->rel}: {$link->href}\tCall Type: {$link->method}\n";
        }
        // To toggle printing the whole response body comment/uncomment below line
        echo json_encode($response->result, JSON_PRETTY_PRINT), "\n";
    }

    return $response;
}

授權之後呢，我們需要驗證授權是否成功，所以我利用回傳的response，寫一個驗證的 function，如下：

public static function checkIfAuthorizedSuccessfully($response)
{
    $newPayPal = (new NewPayPal())->where('payment_id', request()->token)->first();
    // 確認授權是否完成
    if (($response->result->status) !== 'COMPLETED')
        return 'Authorization isn\'t completed';

    // 確認授權是否已開始
    if (($response->result->purchase_units[0]->payments->authorizations[0]->status) !== 'CREATED')
        return 'Authorization was not created';

    // 確認幣別是否一致
    if (($response->result->purchase_units[0]->payments->authorizations[0]->amount->currency_code) !== ($newPayPal->mc_currency))
        return 'The currency is mismatched';

    // 確認授權金額是否正確。這邊是我自己的版本，有需要變動授權金額的話，這邊可以變一下。
    if (intval($response->result->purchase_units[0]->payments->authorizations[0]->amount->value) !== ($newPayPal->total_amount))
        return 'The total amount is not correct';
}

提款 ( capture )

  • 就像上面提到的，成功授權之後，我們可以在29天內隨時向買家請款。
  • 不過 PayPal 只有保證三天買家帳戶裡頭會有足夠的金額，又稱 honor period
  • 一般來說，我們只要把時間算好，可以透過 授權 以及 再次授權 ，將 這筆金額臨時凍結30天。

以下是提款 ( capture ) 的範例：

public static function captureAuthorization(NewPayPal $newPayPal, $final_capture = false, $debug = false)
{
    $NewPayPal = (new NewPayPal)->where('merchant_trade_no', $newPayPal->merchant_trade_no)->first();
    // 提款功能，需要帶入授權id
    $request = new AuthorizationsCaptureRequest($newPayPal->authorization_id);
    // 這邊帶入要提款的金額，如上所敘，提款金額是可以分批次的！ Final_capture 如果設定為true的話，會結束此次授權，此次授權之後無法再進行提款，若要提款需要再重新授權。
    $request->body = self::buildRequestBodyForCaptureAuthorization($NewPayPal->to_be_captured_amount, $final_capture, $newPayPal->mc_currency);
    $client = PayPalClient::client();
    $response = $client->execute($request);

    if ($debug)
    {
        print "Status Code: {$response->statusCode}\n";
        print "Status: {$response->result->status}\n";
        print "Capture ID: {$response->result->id}\n";
        print "Links:\n";
        foreach ($response->result->links as $link)
        {
            print "\t{$link->rel}: {$link->href}\tCall Type: {$link->method}\n";
        }
        // To toggle printing the whole response body comment/uncomment below line
        echo json_encode($response->result, JSON_PRETTY_PRINT), "\n";
    }
    return $response;
}

以下是提款 ( capture ) 的 RequestBody

public static function buildRequestBodyForCaptureAuthorization($amount = null, $final_capture = false, $currency = 'USD')
{
    if ($amount != null)
    {
    // 指定提款的金額與幣別，需要跟授權的一致
        return [
            "amount"        => [
                'currency_code' => $currency,
                'value'         => $amount,
            ],
            'final_capture' => $final_capture
        ];
    }

    return "{}";
}

以下是提款的邏輯

Ray 的邏輯是設定一個提款期限來決定什麼時候提款，因為每次退款都會扣掉手續費，所以 Ray 的想法是利用金額凍結取代退款，在提款期限之前，如果買家申請退款的話， Ray 這邊只需要去更改要提款的最終數字，這樣就可以避免掉手續費的部分。 Ray 自己設定的容許退款期限為七天，所以 Ray 會將這筆金額凍結七天，在七天後等到一切都確定了再依照最終的提款金額一次提款。
所以下面的function每天都會跑一次，如果已經過了提款期限就會真正執行提款，並更新該訂單在所有資料庫裡頭相對應的狀態。

public static function dailyCaptureAuthorization()
{
    $toBeCapturedPayments = NewPayPal::whereNotNull('authorization_id')->whereNull('capture_id')->where('to_be_captured_date', '<', Carbon::now()->toDateTimeString())->get();
    foreach ($toBeCapturedPayments as $toBeCapturedPayment)
    {
        $response = NewPayPal::captureAuthorization($toBeCapturedPayment);
        if (($response->result->status) === 'COMPLETED')
        {
            $toBeCapturedPayment->update(['capture_id' => $response->result->id, 'status' => 7]);
            foreach ($toBeCapturedPayment->orderRelations as $orderRelation)
            {
                if (($orderRelation->status == 5) || ($orderRelation->status == 6))
                {
                    $orderRelation->order->update(['status' => 7]);
                    $orderRelation->update(['status' => 7]);
                }
            }
        }
    }
}

退款 ( refund )

  • 退款的規則是，可以針對特定授權，進行一次性或者分批次的退款。
  • 若屬於分批次，可以指定退款金額
  • 若想要一次性，可以將整個 RequestBody 留空，像官方範例那樣
    public static function refundOrder($captureId, $amount, $currency, $debug = false)
    {
        $request = new CapturesRefundRequest($captureId);
        // 這邊帶入指定的退款金額以及幣別，幣別必須要跟授權的一樣哦
        $request->body = self::buildRequestBodyForRefundOrder($amount, $currency);
        $client = PayPalClient::client();
        $response = $client->execute($request);

        if ($debug)
        {
            print "Status Code: {$response->statusCode}\n";
            print "Status: {$response->result->status}\n";
            print "Order ID: {$response->result->id}\n";
            print "Links:\n";
            foreach ($response->result->links as $link)
            {
                print "\t{$link->rel}: {$link->href}\tCall Type: {$link->method}\n";
            }
            // To toggle printing the whole response body comment/uncomment below line
            echo json_encode($response->result, JSON_PRETTY_PRINT), "\n";
        }

        return $response;
    }

以下是退款的 RequestBody

public static function buildRequestBodyForRefundOrder($amount = null, $currency = 'USD', $final_capture = false)
{
    // 若金額有指定就為指定值，若無指定便為預設格式
    if ($amount != null)
    {
        return [
            "amount"        => [
                'currency_code' => $currency,
                'value'         => $amount,
            ],
            'final_capture' => $final_capture
        ];
    }

    return "{}";
}

退款的邏輯

  • 相對應提款時所做的操作，在商家真正對買家做出提款之前，買家所申請的退款請求都只是去更改資料庫的數字。
  • 如果過了七天，但實屬特殊案例，買家也還是可以申請退款，不過到時候就會有手續費產生
  • 以上邏輯只適用於 PayPal ，因為本專案整合兩家金流，所以上面的邏輯並不適用於歐付寶，不過總體來說，對買家來說都是沒有影響的。
    public static function refund(Order $order, NewPayPal $paymentServiceInstance, OrderRelations $orderRelation)
    {
        // 當該申請訂單為已授權，但尚未請款
        if (($paymentServiceInstance->capture_id === null) && ($paymentServiceInstance->authorization_id !== null))
        {
            // 如上所敘，我們只更新資料庫的請款金額
            $paymentServiceInstance->update([
                'to_be_captured_amount' => $paymentServiceInstance->to_be_captured_amount - $order->total_amount,
                'total_amount'          => $paymentServiceInstance->total_amount - $order->total_amount
            ]);
            $order->update(['status' => 4]);
            $orderRelation->update(['status' => 4]);
        }

        // 當該訂單已經請款了
        if ($paymentServiceInstance->capture_id !== null)
        {
            // 真正執行退款 API ，將款項退給買家
            $response = self::refundOrder($paymentServiceInstance->capture_id, $order->total_amount, $paymentServiceInstance->mc_currency);
            // 如果退款確定成功，更新訂單狀態
            if ($response->result->status == 'COMPLETED')
            {
                $order->update(['status' => 4]);
                $orderRelation->update(['status' => 4]);
                $paymentServiceInstance->update([
                    'total_amount' => $paymentServiceInstance->total_amount - $order->total_amount
                ]);
            }
        }
    }

取消授權

取消方法非常簡單，只要使用官方範例，並且依照格式帶入授權的id就可以，這邊就不特別舉例！
授權id在你成功授權的時候會回傳，在那時記得把它存起來！

取得授權資料

取得授權方法非常簡單，只要使用官方範例，並且依照格式帶入授權的id就可以，這邊就不特別舉例！
授權id在你成功授權的時候會回傳，在那時記得把它存起來！

取得提款資料

取得提款方法非常簡單，只要使用官方範例，並且依照格式帶入提款的id就可以，這邊就不特別舉例！
提款id在你成功提款的時候會回傳，在那時記得把它存起來！

總結

依照官方文件， PayPal REST API 是可以搭配 JavaScript 的 Smart Button 一起使用的，不過 Ray 負責的是後端的角色，所以這一部分就沒有深究。
看起來還蠻有趣的！有興趣的可以花時間研究一下！
PayPal 不愧是國際的金流系統，各項的支援都十分全面以及功能也十分多樣，可惜已經退出台灣了！不過據了解應該是因為相關法令的關係，退出在另一個角度來說也是在捍衛台灣的稅法，未嘗不是一件好事，這邊就不多做評論。
這陣子算是針對 PayPal 的金流深入的研究了一下，當然還有許多比較細緻的功能因為時間的關係還沒有去接觸到，待之後有時間有機會再來好好研究，再把心得過程都記錄下來分享給大家！

歡迎轉載，但麻煩請註明出處，感謝！

#PayPal REST API #PayPal 退款 #PayPal 授權 #PayPal 請款 #PayPal 取消授權 #PayPal 建立授權訂單 #PayPal 款項凍結
伸縮自如的 git flow 利用 PayPal 付款標準版 (PayPal Payment Standard) 以及 PayPal 即時付款通知 (PayPal IPN) 方式結帳付款

留言

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×