multisafepay / php-sdk
MultiSafepay PHP SDK
Installs: 530 599
Dependents: 7
Suggesters: 0
Security: 0
Stars: 11
Watchers: 7
Forks: 9
Open Issues: 3
Requires
- php: ^7.2|^8.0
- ext-json: *
- php-http/discovery: ^1.0
- psr/http-client-implementation: ^1.0
- psr/http-factory-implementation: ^1.0
- psr/http-message-implementation: ^1.0
Requires (Dev)
- fakerphp/faker: ^1.13
- guzzlehttp/guzzle: ^7.0
- http-interop/http-factory-guzzle: ^1.0
- multisafepay/coding-standards: dev-master
- php-http/message: ^1.14
- php-http/message-factory: ^1.1
- php-http/mock-client: ^1.3
- phpstan/phpstan: ^1.8
- phpunit/phpunit: ^9.0 || ^7.5
Suggests
- jschaedl/iban-validation: Adds additional IBAN validation for \MultiSafepay\ValueObject\IbanNumber
README
MultiSafepay PHP SDK
About MultiSafepay
MultiSafepay is a Dutch payment services provider, which takes care of contracts, processing transactions, and collecting payment for a range of local and international payment methods. Start selling online today and manage all your transactions in one place!
Installation
Run the following composer command:
composer require multisafepay/php-sdk
WARNING! This SDK does not have a direct dependency on Guzzle or cURL. Instead, it uses the PSR-18 client abstraction and PSR-17 factory abstraction. This lets you choose which PSR-7 implementation and HTTP client to use. You can replace all clients without any side effects.
If you don't have a client implementation installed, run:
composer require guzzlehttp/guzzle
If you don't have a factory implementation installed, run:
composer require http-interop/http-factory-guzzle
You should now have installed:
Getting started
Use Composer autoloader to automatically load class dependencies:
require 'vendor/autoload.php';
Next, instantiate the SDK with your site API key and a flag to identify whether this is the live environment or testing environment.
$yourApiKey = 'your-api-key'; $isProduction = false; $multiSafepaySdk = new \MultiSafepay\Sdk($yourApiKey, $isProduction);
From the SDK, you can get various managers:
$multiSafepaySdk->getTransactionManager(); $multiSafepaySdk->getGatewayManager(); $multiSafepaySdk->getPaymentMethodManager(); $multiSafepaySdk->getIssuerManager(); $multiSafepaySdk->getCategoryManager(); $multiSafepaySdk->getTokenManager(); $multiSafepaySdk->getApiTokenManager();
The transaction manager is the most important, because it lets you create orders and refunds.
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('noreply@example.org')) ->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();
Example refund:
// 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 ) );
For examples of building full requests, see USAGE.md and the functional tests in tests/Functional/Api/Transactions
.
Advanced usage: Strict mode
Strict mode:
- Adds additional validations on top of various API requests and responses.
- Validation errors throw an exception, which you need to handle.
- It is enabled in tests.
Non-strict mode (default) skips some validation errors.
Example:
If there is a mismatch between the number of decimal places of the total amount of the items in the ShoppingCart
object and your ecommerce platform, strict mode throws an \MultiSafepay\Exception\InvalidTotalAmountException
exception.
Code quality checks
The following checks are in place to maintain code quality:
- PHP CodeSniffer (via
./vendor/bin/phpcs --standard=phpcs.ruleset.xml .
)- PSR-2
- Object Calisthenics
- PHPUnit tests (via
./vendor/bin/phpunit
)- Unit tests
- Integration tests
- Functional tests
Testing
- Unit tests work without the API or any dependencies (
tests/Unit
) - Integration tests work without the API but have dependencies (
tests/Integration
) - Functional tests work with the live API (
tests/Functional
) – API key required
Unit tests
To run unit tests from this package:
- Clone this repository.
- To install all dependencies, run
composer install
- Run PHPUnit with the following command:
./vendor/bin/phpunit tests/Unit
Functional tests
To run functional tests from this package:
- Clone this repository.
- To install all dependencies, run
composer install
. - Copy
.env.php.example
to.env.php
and add your site API key. - Run PHPUnit with the following command:
./vendor/bin/phpunit tests/Functional
Mocking the API for unit and integration tests
Unit and integration tests run without the API, which means that the client is mocking all data calls.
To do this, the tests/fixture-data
folder contains JSON files to spoof calls. To fill this folder with real data, make sure you have a valid .env.php
file, and then use the following command:
php tests/generateApiMocks.php
This commits all generated JSON files into git, so that they serve as fixtures. Files that are not used in tests don't need to be generated.
Support
Create an issue on this repository or email integration@multisafepay.com
Contributors
If you create a pull request to suggest an improvement, we'll send you some MultiSafepay swag as a thank you!
License
Open Software License (OSL 3.0)
Want to be part of the team?
Are you a developer interested in working at MultiSafepay? Check out our job openings and feel free to get in touch!