Omnipay: Datatrans
Datatrans Gateway for the Omnipay PHP payment processing library., (*1)
, (*2)
Omnipay is a framework agnostic, multi-gateway payment
processing library for PHP 7.1+., (*3)
This is for Omnipay 3.x with a minimum PHP version of 5.6., (*4)
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., (*5)
Installation
Omnipay can be installed using Composer.
Installation instructions., (*6)
Run the following command to install omnipay and the datatrans gateway:, (*7)
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:, (*8)
"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:, (*9)
-
merchantId Your merchant ID
-
transactionId unique merchant site transaction ID
-
amount monetary amount (major units fro Omnipay 2.x)
-
currency ISO 4217 three-letter code
-
sign Your sign identifier. Can be found in datatrans backend.
Note: this minimal example does not actually sign or encrypt your request.
See below for details of settings for a more secure approach., (*10)
$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., (*11)
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:, (*12)
$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., (*13)
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:, (*14)
$request = $gateway->purchase([
'createCard' => true,
...
]);
The card reference will be available in the notification server request or the
complete response:, (*15)
// 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., (*16)
$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()., (*17)
-
language - The language to be used by the UI. e.g. 'en', 'de', 'fr'.
-
returnMethod - The HTTP method used in returning the user to your merchant site.
Defaults to POST, which requires an SSL connection (which is recommended anyway).
Can be set to GET if necessary. Will default to the Datatrans account setting..
-
returnUrl/cancelUrl/errorUrl - All must be set either in the back-end Datatrans
account or when the payment request is made.
-
paymentMethod - The three-letter payment method, e.g. VIS, ECA.
If left unset, multiple payment methods will be offered to the visitor to choose.
The documentation implies a comma-separated list of payment methods can be provided,
but this results in an error indicating the payment method is not valid.
Supporrted values can be found in constans \Omnipay\Datatrans\Gateway::PAYMENT_METHOD_xxx
-
hmacKey1 - HMAC key 'sign' for signing outbound messages.
If signing is configured in the account, then the shared key must be provided here.
-
hmacKey2 - alternative HMAC key used to sign inbound messages.
If not set, will default to the value of hmacKey1.
- A
cardReference and optional expiry dates (in the CreditCard object, if the
cardReference is for a credit card) can be supplied. This will pre-populate the
card details for the user, so that they need only enter their CVV to authorize
a payment.
- Many other optional parameters are supported, generally all those in the official
documentaion except where listed in the TODO section here. These will be added as
time permits.
Complete Response
The results can be read on the user returning to the merchant site:, (*18)
$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., (*19)
Notification
The notification handler provides all the same data and methods as completeResponse., (*20)
$notify = $gateway->acceptNotification();
$success = $notify->isSuccessful();
$transactionReference = $notify->getTransactionReference();
To check the notification is correction signed, the send() method is used., (*21)
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)., (*22)
$notify->send();
This will return $notify, but will throw an exception if the signing checks fail., (*23)
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., (*24)
$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., (*25)
$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., (*26)
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., (*27)
The response will, by default, contain the extended transaction details, which include
any cardReference that was requested, and masked card numbers and expiry dates., (*28)
Offline Authorization
Some payment methods support offline authorization using a cardReference., (*29)
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., (*30)
A separate gateway is used to do offline payments, initialized using the
same parameters as the redirect gateway, but like this:, (*31)
$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:, (*32)
// 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., (*33)
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., (*34)
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., (*35)
iframe Mode/Inline Mode
By putting the redirect mode into GET mode, the URL for the iframe becomes the
redirect URL: $response->getRedirectUrl(), (*36)
The iframe content is put into a simplified theme by setting $request->setInline(true), (*37)
$response = $gateway->purchase(['inline' => true, 'redirectMethod' => 'GET', ...]);
echo '
';
The iframe mode appears to require exactly one payment method, making the
payment method mandatory., (*38)
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., (*39)
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:, (*40)
// 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., (*41)
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., (*42)
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., (*43)
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., (*44)
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:, (*45)
- The
price of each item is assumed to be the gross unit price.
- The
price units are considered minor units if an integer (e.g. 123 or "123")
or major units if a floating point number (e.g. 4.56 or "4.56").
- Shipping is set to zero.
- Tax is set to zero.
- The total
ItemBag amount must equal the total order amount.
TODO
Additional Parameters (for various payment methods)
- Payolution mandatory parameters validation
- Aduno surprize specific parameters
- Migros Bank Payment mdpUserId and mdpAlias parameter + txnMbRefNo return param
- Swisscom Easypay parameters
- SwissBilling most customer details mandatory + optional shipping details + basket
- MasterPass Wallet basket + confirmationUrl parameter + shipping and billing address
return details + lots more funky wallet pairing stuff with long-access tokens
+ multilevel XML files come into this
- uppCustomerLanguage is mandatory for a few gateways, e.g. Accarda Kauf-auf Rechnung
- Accarda Kauf-auf Rechnung mandatory customer details + tonnes of new specific parameters
+ lots more return parameters
- Byjuno customer details mandatory + optional shipping details
- LoyLogic Pointspay very simple basket (only supports purchase)
- Girosolution Giropay simply basket + bank details return params
Functionality
- AVS (address verification) by web interface and XML back-end
- Tests needed especially around the multiple notification methods and formats.
Wallogit.com
