CMPayments Payment SDK for PHP
![Scrutinizer][badge-quality]
![Software License][badge-license]
, (*1)
Integrating the CMPayments solutions for online payments with your application is easy using the Payment SDK for PHP., (*2)
Installation
To install the SDK, simply use Composer:
composer require cmpayments/payments-sdk-php, (*3)
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., (*4)
Bootstrapping
To do anything with the SDK, the first step is to create an instance of the payment Gateway:, (*5)
<?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:, (*6)
<?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:, (*7)
<?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'));., (*8)
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., (*9)
<?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., (*10)
In case of a ServerException, the CMPayments platform is having issues. Try the request again later., (*11)
For a ClientException, check $exception->getResponse()->getBody()->getContents() to see what is wrong., (*12)
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)., (*13)
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., (*14)
<?php
use \CMPayments\PaymentSdk\MoneyConverter;
$converter = new MoneyConverter();
$money = $converter->fromAmountAndCurrency(5.00, 'EUR');
$amount = $converter->toFloat($money);
Wallogit.com
