boywijnmaalen / ideal

iDEAL implementation for PHP 5.4+

iDEAL library

This library implements the iDEAL protocol and can be used to perform iDEAL transactions with all major iDEAL acquiring banks. The following acquiring banks are supported:

• ABN AMRO Bank
• BNP Paribas Fortis
• Rabobank
• Deutsche Bank
• ING
• PPRO Financial Limited

This library is compatible with PHP 5.4+ and PHP 7.0

Installation

To install cmpayments/ideal just require it with composer:

# composer require cmpayments/ideal

Usage examples

Initialize the library and provide configuration options for the connection:

<?php
require __DIR__ . '/../vendor/autoload.php';

$ideal = new CMPayments\IDeal\IDeal('https://ideal.acquirer.nl/ideal/iDEALv3');

$ideal->setOptions([
    'acquirerCertificate' => 'acq_cert.pem',
    'merchantCertificate' => 'mer_cert.pem',
    'merchantPrivateKey'  => 'mer_cert.key',
    'password'            => 'private_key_password',
    'merchantId'          => '002099999',
    'merchantSubId'       => 1
]);

Retrieve a list of all issuing banks:

<?php

$request = $ideal->createDirectoryRequest();
$response = $request->send();
$issuers = $response->getAllIssuers();

Start an iDEAL transaction:

<?php

$transactionRequest = $ideal->createTransactionRequest('INGBNL2A', 'http://yourwebsite.nl/returnpath', 'purchaseId', 123456, 'Description');

try {
	$transactionResponse = $transactionRequest->send();
} catch (CMPayments\IDeal\Exception\ResponseException $e) {
	// Handle an error response here
	var_dump($e->getSuggestedAction());
	exit();
}

// Store these values in your local database:
$entranceCode = $transactionRequest->getEntranceCode();
$transactionId = $transactionResponse->getTransactionId();

// redirect the user to the bank environment
header('Location: ' . $transactionResponse->getAuthenticationUrl());

Validate the iDEAL transaction status on return:

<?php

// retrieve and sanitize transaction id from the querystring
$transactionId = preg_replace('/[^0-9]/','',$_GET['trxid']);

// at this point the entrance code ($_GET['ec']) should be checked against
// the value that was returned upon creation of the transaction

// Request the transaction status.
$statusRequest = $ideal->createStatusRequest($transactionId);
$statusResponse = $statusRequest->send();

// Get the transaction status.
switch ($statusResponse->getStatus()) {
    case \CMPayments\IDeal\IDeal::SUCCESS:
        // consumerIBAN and consumerName are available on 'Success'.
        $consumerIban = $statusResponse->getConsumerIBAN();
        $consumerName = $statusResponse->getConsumerName();
        break;
    case \CMPayments\IDeal\IDeal::OPEN:
        // When the transaction status is still 'Open' it should be retried later.
        // According to the iDEAL implementation guidelines the next attempt should only be performed after 5 minutes.
        // In total, 5 attempts are allowed and only if a non final status is returned.
        break;
    case \CMPayments\IDeal\IDeal::FAILURE:
    case \CMPayments\IDeal\IDeal::CANCELLED:
    case \CMPayments\IDeal\IDeal::EXPIRED:
        // The transaction has failed with either a Failure, Cancelled or Expired status
        // This is the moment where the user needs to be informed and the transaction should possibly be retried.
        break;    
}

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Copyright and license

The cmpayment/ideal library is copyright © CM Payments, interexperts and bravesheep and licensed for use under the MIT License (MIT). Please see LICENSE for more information.