README

MultiSafepay PHP SDK

关于 MultiSafepay

MultiSafepay 是一家荷兰支付服务提供商，负责处理各种本地和国际支付方式的合同、交易处理和收款。今天开始在线销售，并将所有交易集中管理！

安装

运行以下 composer 命令

composer require multisafepay/php-sdk

警告！ 此 SDK 不直接依赖于 Guzzle 或 cURL。相反，它使用 PSR-18 客户端抽象和 PSR-17 工厂抽象。这允许您选择要使用的 PSR-7 实现 和 HTTP 客户端。您可以替换所有客户端而没有任何副作用。

如果您尚未安装客户端实现，请运行

composer require guzzlehttp/guzzle

如果您尚未安装工厂实现，请运行

composer require http-interop/http-factory-guzzle

现在您应该已经安装了以下内容

• PSR-18 客户端实现
• PSR-17 工厂实现
• PSR-7 消息实现

入门

使用 Composer 自动加载器自动加载类依赖项

require 'vendor/autoload.php';

接下来，使用您的 站点 API 密钥 和一个标志来识别这是生产环境还是测试环境来实例化 SDK。

$yourApiKey = 'your-api-key';
$isProduction = false;
$multiSafepaySdk = new \MultiSafepay\Sdk($yourApiKey, $isProduction);

从 SDK 中，您可以获取各种管理器

$multiSafepaySdk->getTransactionManager();
$multiSafepaySdk->getGatewayManager();
$multiSafepaySdk->getPaymentMethodManager();
$multiSafepaySdk->getIssuerManager();
$multiSafepaySdk->getCategoryManager();
$multiSafepaySdk->getTokenManager();
$multiSafepaySdk->getApiTokenManager();

交易管理器是最重要的，因为它允许您创建订单和退款。

use MultiSafepay\ValueObject\Customer\Country;
use MultiSafepay\ValueObject\Customer\Address;
use MultiSafepay\ValueObject\Customer\PhoneNumber;
use MultiSafepay\ValueObject\Customer\EmailAddress;
use MultiSafepay\ValueObject\Money;
use MultiSafepay\Api\Transactions\OrderRequest\Arguments\CustomerDetails;
use MultiSafepay\Api\Transactions\OrderRequest\Arguments\PluginDetails;
use MultiSafepay\Api\Transactions\OrderRequest\Arguments\PaymentOptions;
use MultiSafepay\Api\Transactions\OrderRequest;

$yourApiKey = 'your-api-key';
$isProduction = false;
$multiSafepaySdk = new \MultiSafepay\Sdk($yourApiKey, $isProduction);

$orderId = (string) time();
$description = 'Order #' . $orderId;
$amount = new Money(2000, 'EUR'); // Amount must be in cents!!

$address = (new Address())
    ->addStreetName('Kraanspoor')
    ->addStreetNameAdditional('(blue door)')
    ->addHouseNumber('39')
    ->addZipCode('1033SC')
    ->addCity('Amsterdam')
    ->addState('Noord Holland')
    ->addCountry(new Country('NL'));

$customer = (new CustomerDetails())
    ->addFirstName('John')
    ->addLastName('Doe')
    ->addAddress($address)
    ->addEmailAddress(new EmailAddress('[email protected]'))
    ->addPhoneNumber(new PhoneNumber('0208500500'))
    ->addLocale('nl_NL');

$pluginDetails = (new PluginDetails())
    ->addApplicationName('My e-commerce application')
    ->addApplicationVersion('0.0.1')
    ->addPluginVersion('1.1.0');

$paymentOptions = (new PaymentOptions())
    ->addNotificationUrl('http://www.example.com/client/notification?type=notification')
    ->addRedirectUrl('http://www.example.com/client/notification?type=redirect')
    ->addCancelUrl('http://www.example.com/client/notification?type=cancel')
    ->addCloseWindow(true);

$orderRequest = (new OrderRequest())
    ->addType('redirect')
    ->addOrderId($orderId)
    ->addDescriptionText($description)
    ->addMoney($amount)
    ->addGatewayCode('IDEAL')
    ->addCustomer($customer)
    ->addDelivery($customer)
    ->addPluginDetails($pluginDetails)
    ->addPaymentOptions( $paymentOptions);

$transactionManager = $multiSafepaySdk->getTransactionManager()->create($orderRequest);
$transactionManager->getPaymentUrl();

示例退款

// Refund example.
use MultiSafepay\Api\Transactions\RefundRequest;
use MultiSafepay\ValueObject\Money;

$yourApiKey = 'your-api-key';
$isProduction = false;
$multiSafepaySdk = new \MultiSafepay\Sdk($yourApiKey, $isProduction);

$orderId = XXXXX;  // The order ID of a previously completed transaction
$refundAmount = new Money(2000, 'EUR');
$transactionManager = $multiSafepaySdk->getTransactionManager();
$transaction = $transactionManager->get($orderId);
$transactionManager->refund($transaction, (new RefundRequest())->addMoney( $refundAmount ) );

有关构建完整请求的示例，请参阅 USAGE.md 和 tests/Functional/Api/Transactions 中的功能测试。

高级使用：严格模式

严格模式

• 在各个 API 请求和响应之上添加额外的验证。
• 验证错误会抛出异常，您需要处理它。
• 它在测试中启用。

非严格模式（默认）会跳过一些验证错误。

示例： 如果 ShoppingCart 对象中商品的总金额的小数位数与您的电商平台不匹配，则严格模式会抛出 \MultiSafepay\Exception\InvalidTotalAmountException 异常。

代码质量检查

以下检查被放置以维护代码质量

• PHP CodeSniffer（通过 ./vendor/bin/phpcs --standard=phpcs.ruleset.xml .）
  • PSR-2
  • 对象练习
• PHPUnit 测试（通过 ./vendor/bin/phpunit）
  • 单元测试
  • 集成测试
  • 功能测试

测试

• 单元测试可以在没有 API 或任何依赖项的情况下工作（tests/Unit）
• 集成测试可以在没有 API 但有依赖项的情况下工作（tests/Integration）
• 功能测试需要与实时 API 一起工作（tests/Functional）- 需要API密钥

单元测试

要运行此包的单元测试

1. 克隆此仓库。
2. 要安装所有依赖项，请运行 composer install
3. 使用以下命令运行 PHPUnit：./vendor/bin/phpunit tests/Unit

功能测试

要运行此包的功能测试

1. 克隆此仓库。
2. 要安装所有依赖项，请运行 composer install。
3. 将 .env.php.example 复制到 .env.php 并添加您的站点 API 密钥。
4. 使用以下命令运行PHPUnit: ./vendor/bin/phpunit tests/Functional

模拟API进行单元和集成测试

单元和集成测试在无API的情况下运行，这意味着客户端正在模拟所有数据调用。为此，tests/fixture-data文件夹中包含用于欺骗调用的JSON文件。要填充此文件夹中的真实数据，请确保您有一个有效的.env.php文件，然后使用以下命令

php tests/generateApiMocks.php

此命令将所有生成的JSON文件提交到git中，以便它们作为固定值使用。未在测试中使用的文件不需要生成。

支持

在此存储库中创建问题或发送电子邮件至[email protected]

贡献者

如果您创建pull请求以建议改进，我们将向您发送一些MultiSafepay的纪念品以示感谢！

许可

开放软件许可（OSL 3.0）

想要成为团队的一员吗？

您是一位希望在MultiSafepay工作的开发者吗？请查看我们的职位空缺，并随时与我们联系！