search

academe / omnipay-datatrans

Omnipay Datatrans
MIT License
4 stars 4 forks source link

readme

Omnipay: Datatrans

Datatrans Gateway for the Omnipay PHP payment processing library.

Build Status Latest Stable Version Latest Unstable Version License

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP 7.1+.

This is for Omnipay 3.x with a minimum PHP version of 5.6.

Table of Contents

This Gateway implements offsite payments via Datatrans. Purchase and Authorization are available, capturing an authorized payment has to be performed via Datatrans XML backend.

Installation

Omnipay can be installed using Composer. Installation instructions.

Run the following command to install omnipay and the datatrans gateway:

composer require academe/omnipay-datatrans:~3.0

While this is in development - before it is released on packagist - you will need this entry in your composer.json:

    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/academe/omnipay-datatrans"
        }
    ],

Basic (Minimal) Usage

Payment requests to the Datatrans Gateway must at least supply the following parameters:

Note: this minimal example does not actually sign or encrypt your request. See below for details of settings for a more secure approach.

$gateway = Omnipay::create('Datatrans');
$gateway->setMerchantId('{merchantId}');
$gateway->setSign('{sign}');

// Send purchase request. authorize() is also supported.

$response = $gateway->purchase([
    'transactionId' => '{merchant-site-id}',
    'amount' => '10.00',
    'currency' => 'CHF',
])->send();

// This is a redirect gateway, so redirect right away.
// By default, this will be a POST redirect.

$response->redirect();

All data should be in UTF-8 encoding. The gateway API supports ISO extended-ASCII encoding, but that is not enabled for this Omnipay driver.

Optional Gateway and Authorize Parameters

Signing Requests

It is recommended the requests are signed with a pre-shared key. The SHA256 key is set in the gateway account and is set in the gateway:

$gateway->setHmacKey1('3e6c83...{long-key}...6e502a');

The same key will be used for checking the signing of response messages, if set on the gateway when handling responses. The response can optionally be signed by a different key, which is set using $gateway->setHmacKey2(), and that is documented later.

Getting A Card Reference

If enabled on the gateway account, a reusable card reference can be created. To trigger this behaviour, set the createCard parameter to true while making a purchase or authorization:

$request = $gateway->purchase([
   'createCard' => true,
   ...
]);

The card reference will be available in the notification server request or the complete response:

// Will return null if this feature is not enabled in the gateway account.
$reusableCardReference = $response->getCardReference();

If you just want the card reference without making a purchase, then set a zero amount. Alternatively use $gateway->createCard() to create a card reference.

$response = $gateway->createCard([
    'transactionId' => '{merchant-site-id}',
    'currency' => 'GBP',
])->send();

Optional Parameters

Additional parameters change the behaviour of the gateway. They can be set in the purchase() parameter array, or via setters setParamName().

Complete Response

The results can be read on the user returning to the merchant site:

$request = $gateway->completeAuthorize();
$response = $request->send();

$success = $response->isSuccessful();
$transactionReference = $response->getTransactionReference();

Note: If the returnUrl ends with ".htm", then no data will not be returned with the user to the merchant site. The site must then use the notification handler to get the result.

Notification

The notification handler provides all the same data and methods as completeResponse.

$notify = $gateway->acceptNotification();

$success = $notify->isSuccessful();
$transactionReference = $notify->getTransactionReference();

To check the notification is correction signed, the send() method is used.

The notification handler supports all the data delivery modes: GET, POST, XML in header or XML in body. The signing check supports key1 and the extended key2 (a different key used for responses as for the original request).

$notify->send();

This will return $notify, but will throw an exception if the signing checks fail.

Void

$voidRequest = $gateway->void([
    'transactionReference' => $authorizedTransactionReference,
    'transactionId' => $uniqueTtransactionId,
    'currency' => 'GBP',
    'amount' => $originalTransactionAmount,
]);
$voidResponse = $voidRequest->send();

Capture

Up to the original authotization amount can be captured.

$captureRequest = $gateway->capture([
    'transactionReference' => $authorizedTransactionReference,
    'transactionId' => $uniqueTtransactionId,
    'currency' => 'GBP',
    'amount' => $originalTransactionAmount,
]);
$captureResponse = $voidRequest->send();

Get Transaction

A previous transaction can be fetched given either its transactionId or transactionReference. The transactionReference is preferred. This includes transactions that were cancelled by the user.

$request = $gateway->getTransaction([
    'transactionReference' => $originalTransactionReference,
    // or
    'transactionId' => $originalTransactionId,
]);
$response = $request->send();

Please note that (for now) the isSuccessful() method on the response refers to the success of getting the transaction, and not the success of the authorization. This is likely to change.

The transactino status is given by the numeric value of $response->getResponseCode() and the values can be found in the Datatrans documentation. Some work is needed to map these ~20 codes to a simple success/failed/pending/cancelled status.

The response will, by default, contain the extended transaction details, which include any cardReference that was requested, and masked card numbers and expiry dates.

Offline Authorization

Some payment methods support offline authorization using a cardReference.

First a cardReference must be obtained using authorize, purchase or createCard. If this is done for a PayPal (PAP) payment method, then PayPal will create an order which can have a series of amounts authorized up to the maximum of the original order. The PayPal order ID is returned as the cardReference and is used just like the cardReference in other opayment methods.

A separate gateway is used to do offline payments, initialized using the same parameters as the redirect gateway, but like this:

$xmlGateway = Omnipay::create('Datatrans\Xml');

If the cardReference was for a credit card, then the expiry date must be supplied with that reference. This is done using the Omnipsy CreditCard class:

// Minimum data for the card is the expiry month and year.
$card = new \Omnipay\Common\CreditCard([
    'expiryMonth' => $expiryMonth,
    'expiryYear' => $expiryYear,
    // The saved cardReference can be supplied here or later.
    'number' => $cardReference,
]);

//$response = $xmlGateway->purchase([
$response = $xmlGateway->authorize([
    'card' => $card,
    // Supply the card reference here if not in the $card object:
    'cardReference' => $cardReference,
    'amount' => '20.00',
    'currency' => 'EUR',
    'transactionId' => $transactionId,
    // The original payment method
    'paymentMethod' => \Omnipay\Datatrans\Gateway::PAYMENT_PAYMENT_METHOD_VIS,
])->send();

For non-credit card payment methods, the CreditCard object is not needed since there will be no expiry date. Just the previously saved cardReference is passed in. The cardReference is a generic term used for a number of card and non-card payment methods.

Redirect Mode

This is the standard mode for authorizing a payment, where the user will be taken to a remote payment form and returned when they have finished.

The redirect can be either a POST or a GET redirect, defaulting to POST. The setRedirectmethod() parameter takes either "GET" or "POST" to set the redirection mode.

iframe Mode/Inline Mode

By putting the redirect mode into GET mode, the URL for the iframe becomes the redirect URL: $response->getRedirectUrl()

The iframe content is put into a simplified theme by setting $request->setInline(true)

$response = $gateway->purchase(['inline' => true, 'redirectMethod' => 'GET', ...]);

echo '<iframe width="600" height="500" frameborder="0" border="0" src="https://github.com/academe/omnipay-datatrans/raw/master/'.$response->getRedirectUrl().'" />';

The iframe mode appears to require exactly one payment method, making the payment method mandatory.

Lightbox Mode

Lightbox mode uses JavaScript to display the payment form in an iframe in the merchant site, with the merchant site behind a darkened mask. It appears to the user that they are remaining on the merchant site, but the form is remotely supplied by the gateway.

This is supported by getting the redirect data in a lightbox-mode format. To use lightbox mode, please see the DataTrans documentation for the genral HTML needed. The form attributes are then supplied by this driver through the getLightboxHtmlAttributes() method of the redirect response:

// Simple echo example. Use whatever templates you like.
echo '<form id="paymentForm" ' . $response->getLightboxHtmlAttributes() . '>';
echo '<button id="paymentButton">Pay</button>';
echo '</form>';

Set up the gateway as you would for a redirect payment.

If you prefer to build your own HTML attributes, the data for the attributes is available using $resquest->getLightboxData(). It is similar to redirectData() but uses different keys.

One thing lightbox mode offers that other modes do not, is the ability to select multiple payment methods. These are set as a comma-separated list of values. For example, to offer both Visa and PayPal as options in the lightbox, set the paymentMethod to "VIS,PAP". Or you can leave the paymentMethod blank and the lightbox will offer all available payment methods available to the account.

Hidden Mode

This mode requires credit card details to be passed through your merchant application. It is not supported by this release of the driver drue to the PCI requirements involved.

ItemBag/Basket

The standard Omnipay Itembag is supported for the PayPal (PAP) mayment method. Some notes, since the ItemBag can be inflexible and a little ambiguous:

TODO

Additional Parameters (for various payment methods)

Functionality