README

F3-PYPL 是一个 Fat Free Framework 插件，可以帮助您通过 PayPal Classic API 快速实现 PayPal Express Checkout。

Express Checkout 快捷方式 & 标记演示
请使用沙箱账户进行支付。

快速开始配置

将以下自定义部分添加到您的项目配置中。

[PAYPAL]
user=
pass=
signature=
endpoint=sandbox
apiver=204.0
return=http://
cancel=http://
log=0

user - 您的 PayPal API 用户名
pass - 您的 PayPal API 密码
signature - 您的 PayPal API 签名
endpoint - API 终端，值可以是 'sandbox' 或 'production'
apiver - API 版本，当前版本为 204.0
return - 用户登录并点击“继续”或“支付”后，PayPal 将买家重定向到的 URL
cancel - 当买家点击“取消 & 返回”链接时，PayPal 将买家重定向到的 URL
log - 将所有 API 请求和响应记录到 paypal.log

如果您喜欢，您也可以在实例化类时传递一个包含上述值的数组。

// F3-PYPL config
$ppconfig = array(
'user'=>'apiusername',
'pass'=>'apipassword',
'signature'=>'apisignature',
'endpoint'=>'sandbox',
'apiver'=>'204.0',
'return'=>'http://',
'cancel'=>'http://',
'log'=>'1'
);

// Instantiate the class with config
$paypal=new PayPal($ppconfig);

手动安装 将 lib/paypal.php 文件复制到您的 lib/ 或 AUTOLOAD 文件夹。
或
自动安装 通过 Composer

快速开始

PayPal Express Checkout

创建一个初始化交易（SetExpressCheckout API）并重定向买家到 PayPal 的路由。

// Create & redirect
$paypal=new PayPal;
$result=$paypal->create("Sale","EUR","10.00");
$f3->reroute($result['redirect']);

买家返回您的网站后，您可以通过以下方式简单地完成交易（DoExpressCheckoutPayment API）：

// Return & Complete
$token=$f3->get('GET.token');
$payerid=$f3->get('GET.PayerID');

$paypal=new PayPal;
$result=$paypal->complete($token, $payerid);

$result 将包含一个关联数组，其中包含 API 响应。存储有用的信息，如状态和交易 ID。

PayPal Pro

// Process credit/debit card payment
$paypal=new PayPal;
$result=$paypal->dcc("Sale", "EUR", "10.00", $cardtype, $cardnumber, $expdate, $cvv, $ipaddress);

$result 将包含一个关联数组，其中包含 API 响应。存储有用的信息，如状态和交易 ID。

方法

设置收货地址

setShippingAddress() 方法允许您在创建交易之前将收货地址传递给 PayPal。该地址将在买家登录 PayPal 时显示，或将在“客人结账”页面中用于填充地址表单字段。此地址还用于 DoExpressCheckoutPayment API 调用，因此它将显示在支付收据和交易历史中。

setShippingAddress($buyerName, $addressLine1, $addressLine2, $townCity, $regionProvince, $zipCode, $countryCode);

// Example
$paypal->setShippingAddress('Sherlock Holmes', '221b Baker St', 'Marylebone', 'London City', 'London', 'NW16XE', 'GB');

传递购物车行项目

setLineItem() 方法允许您将多个购物车行项目传递给 PayPal。这将显示在买家重定向到 PayPal 时的订单摘要中，也用于 DoExpressCheckoutPayment API，因此可以在 PayPal 收据和交易历史中查看订单的详细信息。

setLineItem($itemName, $itemQty, $itemPrice);

// Example
$paypal->setLineItem("Phone Case", 1, "10.00");
$paypal->setLineItem("Smart Phone", 1, "100.00");
$paypal->setLineItem("Screen Protector", 5, "1.00");

从购物车传递行项目

copyBasket() 方法允许您将 F3 购物车行项目转移到 PayPal 并返回小计。如果未指定数量，则默认为 1。

copyBasket($basket, $name, $amount);

// Example if using the default example naming conventions
$basket->set('name','peach');
$basket->set('amount','10.00');
$basket->set('qty','1');
$basket->save();
$basket->reset();

$basketcontents = $basket->find();  // array of basket items

$paypal = new PayPal;
$itemtotal=$paypal->copyBasket($basketcontents);

// Example if using your own naming conventions
$basket->set('item','peach');
$basket->set('cost','10.00');
$basket->set('quantity','2');
$basket->save();
$basket->reset();

$basketcontents = $basket->find();  // array of basket items

$paypal = new PayPal;
$itemtotal=$paypal->copyBasket($basketcontents,'item','quantity','cost'); // returns 20.

设置运费金额

setShippingAmt() 方法允许您指定总运费金额。

setShippingAmt($amount);

// Example
$paypal->setShippingAmt('10.00');

设置税费金额

setTaxAmt() 方法允许您指定总税费金额。

setTaxAmt($amount);

// Example
$paypal->setTaxAmt('10.00');

创建交易

create() 方法将使用 SetExpressCheckout API 调用设置交易。如果成功，将返回一个唯一的令牌，该令牌用于识别您新创建的交易。买家应随后被重定向到 PayPal，并将 EC-Token 添加到 URL 中，他们将在那里被提示登录或以客人身份结账。

create($paymentAction,$currencyCode,$totalAmount,$optional[]);

// Example
$result=$paypal->create("Sale","EUR","171.00");

// Check the API call was successful
if ($result['ACK']!='Success'){
// Handle the API error
die('Error with API call -'.$result["L_ERRORCODE0"]);
} else {
// Redirect the buyer to PayPal
$f3->reroute($result['redirect']);
}

从 PayPal 获取详细信息

一旦买家从 PayPal 返回到您的返回 URL，您可以使用 getDetails() 方法通过 GetExpressCheckoutDetails API 在完成交易之前检索所有交易和买家详细信息。所有详细信息都作为数组返回。

getDetails($ecToken);

// Example
// Retrieve EC Token from the URL
$token=$f3->get('GET.token');
// Retrieve the buyers shipping address via the GetExpressCheckout API
$address=$paypal->getDetails($token);

更新买家的收货地址

updateShippingAddress() 方法可以用来更新买家在 PayPal 结账过程中通过 GetExpressCheckoutDetails API 选定或添加的收货地址。（使用 getDetails() 获取此信息）。

该地址将添加或更新与 Express Checkout 令牌关联的当前用户会话中。该地址将用于最终 API 调用，因此地址将出现在付款收据上。

updateShippingAddress($token, $name, $street1, $street2, $city, $state, $zip, $countrycode);

// Example
// Retrieve EC Token from the URL
$token=$f3->get('GET.token');
// Retreive the buyers shipping address via the GetExpressCheckout API
$paypal = new PayPal;
$buyerdetails = $paypal->getDetails($token);

$paypal->updateShippingAddress($token, $buyerdetails[SHIPTONAME], $buyerdetails[SHIPTOSTREET], $buyerdetails[SHIPTOSTREET2], $buyerdetails[SHIPTOCITY], $buyerdetails[SHIPTOSTATE], $buyerdetails[SHIPTOZIP], $buyerdetails[SHIPTOCOUNTRYCODE]);

完成交易

complete() 方法调用 DoExpressCheckoutPayment API 并完成交易。

complete($ecToken, $payerId);

// Example
// Retrieve EC Token & PayerID from the URL
$token=$f3->get('GET.token');
$payerid=$f3->get('GET.PayerID');

//Complete the Transaction
$result=$paypal->complete($token, $payerid);

// Check the API call was successful
if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning'){
// Handle the API error
die('Error with API call -'.$result["L_ERRORCODE0"]);
} else {
// Redirect the buyer a receipt or order confirmation page
// Store the status & transaction ID for your records
}

退款交易

refund() 方法调用 RefundTransaction API 并退款交易。有两种类型的退款：全额退款，将退还全部金额；部分退款，将退还指定的金额。

refund($txnId, [$type, $currencycode, $amt]);

// Fake Transaction ID for 20..
$txnId='FAKETXNID';

//Partial Refund
refund($txnId, 'Partial', 'EUR', '10.00']);

//Full Refund
refund($txnId);

Express Checkout 标记（ECM）

以下是一个快速指南，说明如何实现 PayPal Express Checkout 作为支付方式（Express Checkout 标记）并创建一个立即扣款的销售交易。在此流程中，买家在您收集了他们的所有信息（如姓名、电子邮件、收货地址和账单地址）之后，将启动 Express Checkout 流程。

当买家选择使用 PayPal 进行支付时，Express Checkout 流程开始。

定义一个新的路由，该路由将用于设置 Express Checkout 交易并将买家重定向到 PayPal。

$f3->route('GET /expresscheckout',
function ($f3) {

//Instantiate the class
$paypal = new PayPal;

// Set the shipping address (if required).
$paypal->setShippingAddress('John Doe', 'Test Address 1', 'Test Address 2', 'Test City', 'Test Province', 'D15', 'IE');

// Set Cart Items
$paypal->setLineItem("Phone Case", 1, "10.00"); //10.00
$paypal->setLineItem("Smart Phone", 1, "200.00"); //200.00
$paypal->setLineItem("Screen Protector", 5, "1.00"); //5.00

// Set Shipping amount
$paypal->setShippingAmt("10.00");

// Set Tax
$paypal->setTaxAmt("21.00");

/*
Prevent the buyer from changing the 
shipping address on the PayPal website.
*/
$optional=array('ADDROVERRIDE'=>1);

// Create Transaction, Total amount = Cart Items + Shipping Amount + Tax Amount
$result = $paypal->create("Sale", "EUR", "246.00", $optional);

// Reroute buyer to PayPal with resulting transaction token
if ($result['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Redirect Buyer to PayPal
$f3->reroute($result['redirect']);
}

}
);

当创建交易时，响应中会返回一个令牌值。买家将被重定向到一个特定的 URL，其中包含定义的令牌值，这样 PayPal 就知道要显示给买家的交易。

为了简单起见，正确的 URL 作为 'redirect' 值从 create() 方法返回。

买家在登录或填写付款信息后，将被重定向回您项目配置中 PayPal 部分定义的 URL。

URL 将附加两个值，令牌和 PayerID。令牌将是您首次创建交易时返回的相同 EC 令牌，而 PayerID 是买家 PayPal 账户的唯一标识符。

在此阶段，您可以选择显示带有完成选项的订单审查，或者简单地完成交易并显示订单收据/摘要。

###订单审查页面 - 可选步骤要显示订单审查页面，我们可以使用 getDetails() 方法请求 PayPal 中的所有交易详情。这将包括您创建交易时定义的所有内容，如果买家在 PayPal 上更改了他们的收货地址，我们也可以从这里获取更新后的地址。

$f3->route('GET /review',
function($f3) {
// grab token from URL
$token=$f3->get('GET.token');

//Instantiate the Class
$paypal=new PayPal;

// Get Express Checkout details from PayPal
$result=$paypal->getDetails($token);

// Check for successful response
if ($result['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Use details to render an order review page
// Show shipping address order details
}

}
);

###完成交易/订单摘要您可以使用 complete() 方法简单地完成交易并向买家显示订单摘要/收据页面。

$f3->route('GET /summary',
function($f3) {
// grab token & PayerID from URL
$token=$f3->get('GET.token');
$payerid=$f3->get('GET.PayerID');

//Instantiate the Class
$paypal=new PayPal;

// complete the transaction
$result=$paypal->complete($token, $payerid);

// Check for successful response
if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Update back office - save transaction id, payment status etc
// Display thank you/receipt to the buyer.
}

}
);

Express Checkout 简捷方式（ECS）

以下是一个快速指南，说明如何在购物车/篮子中实现 PayPal Express Checkout 并创建一个立即扣款的销售交易。在此流程中，买家从购物车/篮子中启动 Express Checkout 简捷方式流程，绕过注册和地址表单，因为我们利用 API 从 PayPal 获取这些详细信息。

当买家点击“使用 PayPal 结账”时，Express Checkout 流程开始。

定义一个新的路由，该路由将用于设置 Express Checkout 交易并将买家重定向到 PayPal。

$f3->route('GET /expresscheckout',
function ($f3) {

//Instantiate the class
$paypal = new PayPal;

// Set Cart Items manually or use copyBasket method.
$paypal->setLineItem("Phone Case", 1, "10.00"); //10.00
$paypal->setLineItem("Smart Phone", 1, "200.00"); //200.00

// Set Tax
$paypal->setTaxAmt("21.00");

// Create Transaction, Total amount = Cart Items + Shipping Amount + Tax Amount
$result = $paypal->create("Sale", "EUR", "231.00", $optional);

// Reroute buyer to PayPal with resulting transaction token
if ($result['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Redirect Buyer to PayPal
$f3->reroute($result['redirect']);
}

}
);

当创建交易时，响应中会返回一个令牌值。买家将被重定向到一个特定的 URL，其中包含定义的令牌值，这样 PayPal 就知道要显示给买家的交易。

为了简单起见，正确的 URL 作为 'redirect' 值从 create() 方法返回。

买家在登录或填写付款信息后，将被重定向回您项目配置中 PayPal 部分定义的 URL。

URL 将附加两个值，令牌和 PayerID。令牌将是您首次创建交易时返回的相同 EC 令牌，而 PayerID 是买家 PayPal 账户的唯一标识符。

在此阶段，您可以选择显示带有完成选项的订单审查，或者简单地完成交易并显示订单收据/摘要。

###订单审查页面要显示订单审查页面，我们可以使用 getDetails() 方法请求 PayPal 中的所有交易详情。这将包括您创建交易时定义的所有内容，如果买家在 PayPal 上更改了他们的收货地址，我们也可以从这里获取更新后的地址。

$f3->route('GET /review',
function($f3) {
// grab token from URL
$token=$f3->get('GET.token');

//Instantiate the Class
$paypal=new PayPal;

// Get Express Checkout details from PayPal
$buyerdetails=$paypal->getDetails($token);

// Check for successful response
if ($buyerdetails['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $buyerdetails["L_ERRORCODE0"]);
} else {
// Use details of $result to render an order review page
// Show shipping address order details

// Update the session to store the new shipping address
// this address is passed in the final API call
$paypal->updateShippingAddress($token, $buyerdetails[SHIPTONAME], $buyerdetails[SHIPTOSTREET], $buyerdetails[SHIPTOSTREET2], $buyerdetails[SHIPTOCITY], $buyerdetails[SHIPTOSTATE], $buyerdetails[SHIPTOZIP], $buyerdetails[SHIPTOCOUNTRYCODE]);

// Update the session & order total with a new shipping amount
$paypal->updateShippingAmt($token, '10.00');

}

}
);

###完成交易/订单摘要您可以使用 complete() 方法简单地完成交易并向买家显示订单摘要/收据页面。

$f3->route('GET /summary',
function($f3) {
// grab token & PayerID from URL
$token=$f3->get('GET.token');
$payerid=$f3->get('GET.PayerID');

//Instantiate the Class
$paypal=new PayPal;

// complete the transaction
$result=$paypal->complete($token, $payerid);

// Check for successful response
if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Update back office - save transaction id, payment status etc
// Display thank you/receipt to the buyer.
}

}
);

周期性付款

以下是一个快速指南，说明如何通过经典 API 实现周期性付款（订阅）。

定义一个新的路由，该路由将用于设置周期性付款并将买家重定向到 PayPal。

$f3->route('GET /rp',
function ($f3) {

//Instantiate the Recurring Payments Class
$paypal = new PayPalRP;

//Set a descriptive name for the Recurring Payment
$result = $paypal->setupRP("Test Subscription");

// Reroute buyer to PayPal with resulting transaction token
if ($result['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Redirect Buyer to PayPal
$f3->reroute($result['redirect']);
}
}
);

就像 Express Checkout 一样（我们正在利用相同的 API 调用），当我们创建周期性付款时，响应中会返回一个令牌值。买家将被重定向到一个特定的 URL，其中包含定义的令牌值，这样 PayPal 就知道要显示给买家的交易。

为了简单起见，正确的 URL 作为 'redirect' 值从 create() 方法返回。

在买家登录并同意循环支付后，他们将被重定向回您项目配置中PayPal部分定义的URL。

该URL将附加一个值 token。该token与您首次创建循环支付时返回的token相同。

我们现在设置循环支付的条款并创建配置文件。

$f3->route('GET /rpcreate',
function ($f3) {

//Instantiate the Recurring Payments Class
$paypal = new PayPalRP;

//Define the terms of the recurring payment profile.
$amt="10.00";
$startdate=date('Y-m-d')."T00:00:00Z"; // UTC/GMT format eg 2016-10-25T18:00:00Z
$period="Day"; // Day, Week, SemiMonth, Month, Year
$frequency="2"; // Cannot exceed one year
$currency="EUR";

$paypal->setRPDetails($amt, $startdate, $period, $frequency, $currency);

// grab token from URL
$token = $f3->get('GET.token');

//Create Recurring Payment Profile
$result = $paypal->createRP($token);

// Reroute buyer to PayPal with resulting transaction token
if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
exit(print_r($result));
}

}
);

参考交易 / 计费协议

以下是通过经典API实现Express Checkout参考交易的快速指南。

定义一个新的路由，用于设置计费协议并将买家重定向到PayPal。

$f3->route('GET /basetup',
function ($f3) {

//Instantiate the Reference Transactions Class
$paypal = new PayPalRT;

//Set a descriptive name for the Recurring Payment
$result = $paypal->setupRP("Test Subscription");

// Reroute buyer to PayPal with resulting transaction token
if ($result['ACK'] != 'Success') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
// Redirect Buyer to PayPal
$f3->reroute($result['redirect']);
}
}
);

当买家从PayPal返回时，我们使用EC Token通过CreateBillingAgreement API请求创建计费协议。成功响应将包含['BILLINGAGREEMENTID']值。请保存此值，因为它在创建未来的参考交易时是必需的。

$f3->route('GET /bacreate',
    function ($f3) {

        // grab token & PayerID from URL
        $token = $f3->get('GET.token');

        // complete the transaction
        $paypal = new PayPalRT;
        $result = $paypal->createBA($token);

		if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
            // Handle API error code
            die('Error with API call - ' . $result["L_ERRORCODE0"]);
        } else {
            print_r($result);
            // Update back office - save the billing agreement id.
            // Display thank you/receipt to the buyer.
        }

    }
);

一旦您为买家获取有效的计费协议ID，您就可以使用DoReferenceTransaction API代表他们创建/完成交易。

// Create the transaction
$paypal = new PayPalRT;
$result = $paypal->doRT($billingAgreementId, 'Sale', 'EUR', '10.00');

if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
    // Handle API error code
    die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
    print_r($result);
    // Update back office - save transaction id, payment status etc
    // Display thank you/receipt to the buyer if present.
}

PayPal Pro

要直接处理信用卡/借记卡号，您可以使用dcc()方法。

$f3->route('GET /dcc',
function ($f3) {

//Instantiate the PayPal Class
$paypal = new PayPal;

$paymentaction="Sale"; // Can be Sale or Authorization
$currencycode="EUR"; // 3 Character currency code
$amount="10.00"; // Amount to charge
$cardtype='Visa'; // Visa, MasterCard, Discover etc
$cardnumber='XXXXXXXXXXXXXXXX'; // Valid card number
$expdate='122020'; // format MMYYYY
$cvv='123'; // Valid security code
$ipaddress='127.0.0.1';

$result=$paypal->dcc($paymentaction, $currencycode, $amount, $cardtype, $cardnumber, $expdate, $cvv, $ipaddress);

// $result will contain an associative array of the API response.  Store the useful bits like status & transaction ID.

if ($result['ACK'] != 'Success' && $result['ACK'] != 'SuccessWithWarning') {
// Handle API error code
die('Error with API call - ' . $result["L_ERRORCODE0"]);
} else {
exit(print_r($result));
}

}
);

许可证

F3-PYPL受GPL v.3许可。

kreative / f3-pypl

维护者

详细信息

README

快速开始配置

快速开始

PayPal Express Checkout

PayPal Pro

方法

Express Checkout 标记（ECM）

Express Checkout 简捷方式（ECS）

周期性付款

参考交易 / 计费协议

PayPal Pro

许可证