README

     _                 _             
 ___(_)_ __ ___  _ __ | | ___  _ __  
/ __| | '_ ` _ \| '_ \| |/ _ \| '_ \ 
\__ \ | | | | | | |_) | | (_) | | | |
|___/_|_| |_| |_| .__/|_|\___/|_| |_|
                |_|                  
                                        _   
 _ __   __ _ _   _ _ __ ___   ___ _ __ | |_ 
| '_ \ / _` | | | | '_ ` _ \ / _ \ '_ \| __|
| |_) | (_| | |_| | | | | | |  __/ | | | |_ 
| .__/ \__,_|\__, |_| |_| |_|\___|_| |_|\__|
|_|          |___/

Simplon Payment

版本 0.5.8

简介

Simplon Payment 是为了托管不同支付服务提供商的兼容库而构建的。在本模块编写时，它包含两个库： PayPal 和 Skrill。这两个库都是通过应用 Builder 模式创建的。

确保为这两个库都创建了测试账户。设置 PayPal 的测试账户非常简单。

Skrill 稍微有点挑战性。实账和测试账户的设置是相同的。但是，为了将账户激活为测试账户，您需要通过电子邮件向支持人员发送询问。请包含您的账户号码。这需要一些时间。不过，最快的方法是联系您的 Skrill 关键账户经理来处理设置 - 如果您有关键账户经理的话。

安装

您可以通过从 GitHub 下载包或通过 Composer 安装来安装 Simplon/Payment。我鼓励您后者。

{
  "require": {
    "php": ">=5.4",
    "simplon/payment": "0.5.*"
  }
}

注意

这份文档仍在进行中。因此，如果您有任何问题，请查看代码或给我发消息。

PayPal

PayPal 的结账流程包括三个步骤

请求结账令牌（响应：会话令牌）
请求结账详情（响应：所有支付详情）
请求结账支付（响应：所有支付详情 + 交易ID）

要求

PayPal 要求注册一系列认证凭据，这些凭据必须与 PayPal 的商户服务进行注册。注册成功后，以下凭据将可用：

商户用户名
商户密码
签名

请求结账令牌

PayPal 总是要求进行认证，这由我们的 Auth 类处理

$authPayPal = \Simplon\Payment\PayPal\Auth::init()
  ->setUsername('MERCHANT_USER')
  ->setPassword('MERCHANT_PASSWORD')
  ->setSignature('MERCHANT_SIGNATURE')
  ->setSandboxMode(TRUE); // for production = FALSE

在我们发送请求之前，我们需要一个产品。这将由我们的 ProductItem 类创建。正如您将看到的，我们可以创建不仅仅是一个产品。所有产品项都将存储在简单的数组中

$items = array();

// add item
$items[] = (new \Simplon\Payment\ProductItem())
  ->setRefId('12345')
  ->setName('Super Mega Pack')
  ->setDescription('500 Diamonds with 50% discount')
  ->setPrice(15)
  ->setQuantity(1)
  ->setTax(19);

// add item
$items[] = (new \Simplon\Payment\ProductItem())
  ->setName('Strong Hammer')
  ->setPrice(3.99)
  ->setQuantity(1);

好的，让我们完成这个并请求 checkoutToken

// create instance of PayPalStart
$paypal = new \Simplon\Payment\PayPal\PayPalStart($authPayPal);

// request token
$paypal
  ->setOrderItemsMany($items)
  ->setUrlSuccess(URL_SUCCESS)
  ->setUrlCancel(URL_CANCEL)
  ->setCommitOnPayPal(TRUE)
  ->requestCheckoutToken();

// show token
echo $paypal->getCheckoutToken(); // prints checkoutToken

单凭令牌本身并不能走得太远。我们实际上需要 PayPal 的商店 URL

$urlPayPalLogin = $paypalSession->getUrlPayPalLogin();
echo '<a href="' . $urlPayPalLogin . '" target="_blank">' . $urlPayPalLogin . '</a>';

好的，这将在我们的页面上打印一个锚点，带我们到 PayPal 的商店，我们可以在那里输入我们的数据。

请求结账详情

我们的下一步操作将在用户在 PayPal 端输入所有信息后立即执行。如果一切顺利，PayPal 将调用我们先前定义的 urlSuccess，并通过 GET 参数 $_GET['token'] 传递。我们的 urlSuccess 后面的脚本应该执行以下操作以获取 CheckoutDetails

// auth
$authPayPal = \Simplon\Payment\PayPal\Auth::init(); // do the same as above ...

// create instance of PayPalProcess
$paypal = new \Simplon\Payment\PayPal\PayPalProcess($authPayPal);

// set received checkoutToken
$paypal->setCheckoutToken($_GET['token']);

// request checkout details based on checkoutToken
$paypal->requestGetExpressCheckoutDetails();

// get created VO
$detailsResponseVo = $paypalSession->getGetExpressCheckoutDetailsResponseVo();

GetExpressCheckoutDetailsResponseVo() 现在包含我们调用中的所有基本数据。查看类以了解还有哪些其他内容可用。VO 可以根据需要进行扩展。

请求结账支付

这是结账的最后一步，以便完成结账。要运行这个最后请求，我们需要从我们刚刚填写的 VO GetExpressCheckoutDetailsResponseVo() 中获取三个值

$detailsResponseVo->getPayerId()
$detailsResponseVo->getOrderAmount()
$detailsResponseVo->getCurrencyCode()

订单金额和货币代码必须与我们的初始结账请求中的值匹配。好吧，假设我们仍然处于上一次示例的脚本中。现在，让我们弄一些钱

// here goes code for request checkout details ...

$paypal->requestDoExpressCheckoutPayment(
  $detailsResponseVo->getPayerId(),
  $detailsResponseVo->getOrderAmount(),
  $detailsResponseVo->getCurrencyCode()
);

// resonse data are within this VO
$paymentResponseVo = $paypalSession->getDoExpressCheckoutPaymentResponseVo();

如果没有发生异常，结账就成功了，我们也收到了一些钱。要完成PayPal结账，只需将响应数据保存到数据库中，以便我们能够进行持久访问。

沙盒模式

注意，在沙盒模式下，唯一接受的货币是USD。如果您使用其他货币进行结账，PayPal将抛出异常，您将无法完成测试预订。

Skrill

Skrill的结账流程有两个步骤

请求结账令牌（响应：会话令牌）
请求结账支付数据（响应：所有支付详情 + 交易ID）

要求

Skrill需要激活的商户账户，该账户将通过商户的电子邮件地址进行引用。您还需要确保所有支付方式都为您账户激活。信用卡需要Skrill的特别审计。

为了获取所有最终结账数据，我们需要使用Skrill的商户查询接口（MQI）。为此，我们需要一个密码，该密码需要在您的商户账户中定义。

请求结账令牌

当涉及到认证时，Skrill只要求商户的电子邮件地址。与PayPal一样，我们通过ProductItem类定义我们的产品并将其缓存到数组中。

$items = [];

$items[] = (new \Simplon\Payment\ProductItem())
  ->setRefId('12345')
  ->setName('Product A')
  ->setPrice(15.99)
  ->setQuantity(1);

$items[] = (new \Simplon\Payment\ProductItem())
  ->setRefId('678910')
  ->setName('Product B')
  ->setPrice(9.99)
  ->setQuantity(1);

在我们可以请求结账令牌之前，我们需要定义我们希望向客户提供的支付选项。由于Skrill提供了相当多的支付选项，这些选项因国家/地区而异，我们需要找到一种轻松定义它们的方法。好吧，让我们再次使用我们的Builder模式。

// create country payment methods instance
$enabledPaymentMethods = new \Simplon\Payment\Skrill\PaymentMethods\SkrillPaymentMethodsGermany();

// enable payment methods
$enabledPaymentMethods
  ->useBankSofortueberweisung()
  ->useBankOnlineBankTransfer()
  ->useCardVisa();

好吧，这里发生了什么？首先，我们创建了一个具有德国所有可能支付选项的实例。然后，我们启用了Sofortueberweisung、BankOnlineTransfer和Visa选项。

好吧，现在我们已经拥有了所有需要的东西，让我们获取checkoutToken或相应的checkoutUrl。

// request checkoutToken
$skrill = (new \Simplon\Payment\Skrill\SkrillStart())
  ->setUrlReturn(URL_RETURN)
  ->setUrlCancel(URL_CANCEL)
  ->setUrlCallback(URL_CALLBACK)
  ->setMerchantAccountEmail(MERCHANT_EMAIL)
  ->setOrderTransactionId('8473d989-4ad0-4c83-b6e3-5cc0ed74a408')
  ->setOrderCurrency('EUR')
  ->setOrderItemsMany($items)                                  // our defined items array
  ->setOrderEnabledPaymentMethods($enabledPaymentMethods)      // our enabled options
  ->addOrderCustomCallbackData('customField1', 'customValue')  // add a custom field
  ->addOrderCustomCallbackData('customField2', 'customValue')  // another custom field
  ->addOrderCustomCallbackData('customField3', 'customValue')  // and so on...
  ->requestCheckoutToken();

// get checkoutUrl
$checkoutUrl = $skrill->getCheckoutUrl();

正如我们所看到的，有几个空白需要填写

URL_RETURN：在Skrill页面上成功输入数据后的重定向URL
URL_CANCEL：在Skrill页面上取消时的重定向URL
URL_CALLBACK：在成功预订时的回调URL。通过POST接收所有预订数据（可选）
MERCHANT_EMAIL：在您的商户账户中定义的电子邮件

如果一切顺利，我们应该收到一个checkoutUrl。重定向到该URL将显示Skrill表单页面，其中包含所有必需的字段。

在Skrill页面上成功输入数据和所有确认后，用户将被重定向到URL_RETURN。

请求结账支付数据

如果我们定义了URL_CALLBACK，Skrill将通过POST发送给我们所有预订数据。从那里开始，如何处理这些数据取决于我们。

另一种方法是通过setUrlOrEmailCallback()设置一个URL或EMAIL。Skrill将发送所有数据到给定的URL或EMAIL，无论交易是否成功。如果您需要另一个回调，可以使用setUrlOrEmailCallbackAlternative()。适用于此方法的规定与先前方法相同。

然而，还有一种替代方案，允许我们随时获取预订数据。为此，我们必须使用上述商户查询接口（MQI），结合我们的MERCHANT_EMAIL、GATEWAY_PASSWORD和MERCHANT_TRANSACTION_ID。

重要提示：MERCHANT_TRANSACTION_ID是我们传递给Skrill的ID。在我们的示例中，它将是'8473d989-4ad0-4c83-b6e3-5cc0ed74a408'。

// credentials
$merchantAccountEmail = "[MERCHANT_EMAIL]";
$merchantApiMqiPassword = "[MERCHANT_GATEWAY_PASSWORD]";
$merchantTransactionId = "[MERCHANT_TRANSACTION_ID]";

// request MQI
$checkoutQueryResponseVo = (new SkrillProcess())->getCheckoutDetailsByMerchantTransactionId(
  $merchantAccountEmail,
  $merchantApiMqiPassword,
  $merchantTransactionId
);

// $checkoutQueryResponseVo has access to the following methods:
$checkoutQueryResponseVo->getSkrillSha2Signature();
$checkoutQueryResponseVo->getSkrillMd5Signature();
$checkoutQueryResponseVo->getSkrillStatus();
$checkoutQueryResponseVo->getSkrillTransactionId();
$checkoutQueryResponseVo->getSkrillAmount();
$checkoutQueryResponseVo->getSkrillCurrency();
$checkoutQueryResponseVo->getSkrillMerchantId();
$checkoutQueryResponseVo->getPostedTransactionId();
$checkoutQueryResponseVo->getSkrillCustomerId();
$checkoutQueryResponseVo->getPostedAmount();
$checkoutQueryResponseVo->getPostedCurrency();
$checkoutQueryResponseVo->getSkrillPaymentType();
$checkoutQueryResponseVo->getPostedMerchantAccountEmail();
$checkoutQueryResponseVo->getSkrillPayFromEmail();

// fetch custom fields in case you added some to the checkout
$checkoutQueryResponseVo->getPostedCustomCallbackData();

通过这个示例，我们完成了Skrill支付的结账周期。

变更日志

0.5.5

准备Skrill响应状态码

0.5.4

添加了isPaymentCompleted方法（DoExpressCheckoutVo）
修复了DoExpressCheckout的过时PayPal响应字段
为 DoExpressCheckout 响应字段 PaymentStatus、PendingReason 和 ReasonCode 添加了描述（参见 DoExpressCheckoutVo）

simplon / payment

维护者

详细信息

README

Simplon Payment

简介

安装

注意

PayPal

要求

请求结账令牌

请求结账详情

请求结账支付

沙盒模式

Skrill

要求

请求结账令牌

请求结账支付数据

变更日志

0.5.5

0.5.4