cmpayments/payments-sdk-php

SDK that makes it easy to connect to the CMPayments payment API

v1.2.0 2021-10-21 14:04 UTC

Requires

• php: >=5.5.0
• cmpayments/guzzle-psp-authentication-middleware: ^1.0
• moneyphp/money: ^3.0

Requires (Dev)

• jakub-onderka/php-parallel-lint: ^0.9.0
• phpunit/phpunit: ^4.7|>=5.0 <5.4
• squizlabs/php_codesniffer: ^2.3

MIT

• Jory Geerts
• Michel Westerink

README

Integrating the CMPayments solutions for online payments with your application is easy using the Payment SDK for PHP.

Installation

To install the SDK, simply use Composer: composer require cmpayments/payments-sdk-php

Requirements

• PHP 5.5+
• PHP cURL extension
• Up to date SSL, capable of TLS 1.0 or higher

Dependencies

• MoneyPHP is used to encapsulate sums of money and their currency
• Guzzle is used to make HTTP requests

These are automatically installed by composer.

Bootstrapping

To do anything with the SDK, the first step is to create an instance of the payment Gateway:

<?php
use CMPayments\PaymentSdk\Credentials;
use CMPayments\PaymentSdk\Gateway;

$gateway = new Gateway(new Credentials('your-api-key', 'your-api-secret'));

List iDEAL issuers

To get a list of iDEAL issuers, simply tell the Gateway to execute the IdealIssuerListRequest:

<?php
use CMPayments\PaymentSdk\Requests\IdealIssuerListRequest;

$issuers = $gateway->execute(new IdealIssuerListRequest());

foreach ($issuers as $name => $id) {
    // $name is now 'ABN AMRO Bank', 'Rabobank', 'ING', etc.
    // $id is now 'ABNANL2A', 'RABONL2U', 'INGBNL2A', etc.
}

Start a payment

The CMPayments API supports the concept of a Charge that contains 0..n Payment items underneath it. To start a payment, both a Charge and a Payment must be created. This can be done in one request:

<?php
use CMPayments\PaymentSdk\Entities\Charge;
use CMPayments\PaymentSdk\Entities\IdealPayment;
use CMPayments\PaymentSdk\Requests\CreateChargeRequest;
use Money\Money;

//  Create both a charge and a payment object
$payment = new IdealPayment(Money::EUR(500), 'RABONL2U', 'your-unique-purchase-id', 'A description of the transaction');
$charge = new Charge(Money::EUR(500), [$payment]);

$response = $gateway->execute(new CreateChargeRequest($charge));

//  The id of the charge is available as $response->charge_id, the id of the payment in $response->payments[0]->payment_id
//  These ids are in the form of ch- (or charge) or pt- (for payment), followed by a uuid v4.
//  To have the user complete the payment, redirect them to $response->payments[0]->payment_details->authentication_url

Note: Each payment method has its own {METHOD}Payment class. Each of these classes enforces all required properties trough their constructors. For instance, to create a new CreditCard payment, replace the new IdealPayment(...) line with new CreditCardPayment(Money::EUR(500), ['VISA', 'MasterCard'], 'your-purchase-id', new \DateTime('+1 day'));.

Retreive charge or a payment

Simple tell the Gateway to execute a ViewChargeRequest of ViewPaymentRequest with the correct id, and the details will be retrieved.

<?php
use CMPayments\PaymentSdk\Requests\ViewChargeRequest;
use CMPayments\PaymentSdk\Requests\ViewPaymentRequest;

$response = $gateway->execute(
    new ViewChargeRequest('ch-fd0e1e2d-f994-4afc-a0b6-f7e76550fc31')
);
$response = $gateway->execute(
    new ViewPaymentRequest('pt-297bba0f-5fae-4ec2-8c0f-dfbc0f62f6b0')
);

Handling errors

Internally, Guzzle is used to make HTTP requests. When the API responds with a 4xx or 5xx HTTP status, either a ClientException or a ServerException is thrown.

In case of a ServerException, the CMPayments platform is having issues. Try the request again later.

For a ClientException, check $exception->getResponse()->getBody()->getContents() to see what is wrong.

Working with Money

The Money library in use requires that any amount is represented in the smallest unig (eg. cents), so EUR 5,- is written as new Money(500, new Currency('EUR')) or shorter as Money::EUR(500).

Because this can be a bit of a hassle, the MoneyConverter class is provided. It can convert a float + currency into a Money object and back.

<?php
use \CMPayments\PaymentSdk\MoneyConverter;
$converter = new MoneyConverter();

$money = $converter->fromAmountAndCurrency(5.00, 'EUR');

$amount = $converter->toFloat($money);