Integrating the CMPayments solutions for online payments with your application is easy using the Payment SDK for PHP.
To install the SDK, simply use Composer:
composer require cmpayments/payments-sdk-php
- PHP 5.5+
- PHP cURL extension
- Up to date SSL, capable of TLS 1.0 or higher
- MoneyPHP is used to encapsulate sums of money and their currency
- Guzzle is used to make HTTP requests
These are automatically installed by composer.
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'));
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.
}
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'));
.
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')
);
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.
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);