README

MLocati的Nexi XPay Web客户端库（PHP）

本项目包含一个PHP库，使得使用Nexi XPay Web API（用于Intesa Sanpaolo银行）变得简单。

这需要一个API密钥。如果您有终端别名和MAC密钥，可能需要使用这个其他库。

它是从官方文档（见/build目录）自动构建的（几乎），该目录仅在您克隆此存储库时才可用。

安装

使用composer安装

只需运行以下命令

composer require mlocati/nexi-xpay-web

手动安装

下载此库的代码，将其放置在您的项目中的某个位置，然后在使用此库的任何内容之前添加此PHP指令

require '/path/to/nexi.php';

使用

配置

首先，您需要一个API密钥（由您的XPay后台生成）。对于测试环境，您可以使用MLocati\Nexi\XPayWeb\Configuration::DEFAULT_APIKEY_TEST常量的值。

您还需要Nexi XPay Web API的基本URL。您可以在MLocati\Nexi\XPayWeb\Configuration中再次找到它们。

• 对于测试环境：您可以使用MLocati\Nexi\XPayWeb\Configuration::DEFAULT_BASEURL_TEST
• 对于生产环境：您可以使用MLocati\Nexi\XPayWeb\Configuration::DEFAULT_BASEURL_PRODUCTION

此库通过使用MLocati\Nexi\XPayWeb\Configuration\FromArray类，提供了一种简单的方式来表示配置。

use MLocati\Nexi\XPayWeb\Configuration;

// For test environment
$configuration = new Configuration\FromArray(['environment' => 'test']);
// For production environment
$configuration = new Configuration\FromArray(['apiKey' => 'your API key']);

当然，您可以覆盖默认的基本URL（使用baseUrl数组键）。

您还可以使用自定义类，只要它实现了MLocati\Nexi\XPayWeb\Configuration接口即可。

Nexi客户端

此库的主要类是MLocati\Nexi\XPayWeb\Client：它允许您调用Nexi API。

您可以通过以下方式创建其实例

use MLocati\Nexi\XPayWeb\Client;

$client = new Client($configuration);

HTTP通信

Nexi客户端需要执行HTTP请求。为了做到这一点，它自动检测执行此操作的最佳可用方式

• 如果cURL PHP扩展可用，则使用它（见MLocati\Nexi\XPayWeb\HttpClient\Curl类）
• 否则，如果PHP HTTP流包装器已启用，则使用它（它需要OpenSSL PHP扩展 - 见MLocati\Nexi\XPayWeb\HttpClient\StreamWrapper类）

您还可以提供自己的实现，只要它实现了MLocati\Nexi\XPayWeb\HttpClient接口即可。这样，您可以轻松记录与Nexi服务器的通信，以及自定义HTTP客户端（例如，因为您位于代理后面）。

例如，如果您想使用自定义的HTTP客户端实现，您可以简单地编写

use MLocati\Nexi\XPayWeb\Client;

$myHttpClient = new My\Custom\HttpClient();
$client = new Client($configuration, $myHttpClient);

Correlation-Id 头部

对Nexi服务器的每个请求都与一个唯一的标识符相关联，通过名为Correlation-Id的HTTP头部发送。默认情况下，Next客户端随机生成它，并且不存储它。如果您想自己生成Correlation-Id头部的值，或者您想记录生成的Correlation-Id值，您可以创建一个自定义类，该类实现了MLocati\Nexi\XPayWeb\CorrelationProvider接口。然后，当您创建Nexi客户端时，您可以编写如下代码

use MLocati\Nexi\XPayWeb\Client;

$correlationProvider = new My\Custom\CorrelationProvider();
$client = new Client($configuration, null, $correlationProvider);

示例用法

Nexi客户端提供的方法有良好的文档说明（请参阅PHPDoc注释）。此库提供的Nexi客户端允许您使用在Nexi文档网站上找到的所有方法。

以下是一个示例代码，允许您接受支付

1. 您的客户在您的网站上点击“支付”按钮，该按钮在您的项目中执行此代码

   <?php
   use MLocati\Nexi\XPayWeb\Dictionary\Currency;
   use MLocati\Nexi\XPayWeb\Dictionary\Language;
   use MLocati\Nexi\XPayWeb\Entity\CreateOrderForHostedPayment\Request;
   
   $currency = Currency::ID_EUR;
   $amount = 123.45;
   $internalOrderID = 'internal-order-id';
   
   $currencyService = new Currency();
   
   $request = new Request();
   $request->getOrCreatePaymentSession()
       ->setActionType('PAY')
       ->setAmount($currencyService->formatDecimals($amount, $currency))
       ->setLanguage(Language::ID_ITA)
       ->setResultUrl('http://your.website/callback')
       ->setCancelUrl('http://your.website/payment-canceled')
   ;
   
   $order = $request->getOrCreateOrder();
   $order
       ->setOrderId($internalOrderID)
       ->setAmount($currencyService->formatDecimals($amount, $currency))
       ->setCurrency($currency)
       ->setDescription('The description of your order')
   ;
   $order->getOrCreateCustomerInfo()
       ->setCardHolderEmail('your.customer@email.address')
   ;
   
   $response = $client->createOrderForHostedPayment($request);
   
   // Store somewhere your $internalOrderID, for example with $_SESSION['order-id'] = $internalOrderID

2. 然后，您将客户重定向到$response->getHostedPage()提供的URL
3. 当客户在Nexi网站上支付时，他将被重定向到上面使用的setResultUrl()中指定的URL。当该URL被调用时，您可以编写如下代码

   // retrieve your internal order ID, for example with $internalOrderID = $_SESSION['order-id']
   $order = $client->findOrderById($internalOrderID);
   foreach ($order->getOperations() as $operation) {
       if ($operation->getOperationType() === 'AUTHORIZATION') {
           switch ($operation->getOperationResult()) {
               case 'AUTHORIZED':
               case 'EXECUTED':
                   // the customer has paid the order (or at least has authorized it)
                   break;
               case 'CANCELED': // Operation canceled by the cardholder
               case 'THREEDS_FAILED': // Operation canceled by the cardholder during 3DS
                   // the user refused to pay
                   break;
               default:
                   // some other error occurred
                   break
           }
       }
   }