Home

Awesome

Omnipay: GiroCheckout

GiroCheckout driver for the Omnipay PHP payment processing library

Build Status Latest Stable Version Latest Unstable Version Total Downloads License

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

This package implements Girocheckout support, and supports PHP 7.1+.

This package is currently built for the Omnipay v3.0-beta.1 on the master branch. The major version number of this driver is intended to track the major version number of the omnipay-common package.

If you are using the Omnipay 2.x, please use the 2.x branch.

Table of Contents

Installation

Using composer, the 3.0 branch can be installed like this:

composer require league/omnipay academe/omnipay-girocheckout:~3.0

Authentication

A GiroCheckout merchant account is first set up. Within that account, one of more projects are set up. Each project is configured to run just one payment type (e.g. credit card, direct debit).

Each project contains a pre-shared secret. That secret is used to sign all messages, in both directions (requests to the gateway, responses to those requests, and server request notification messages from the gateway to your merchant site).

So for each payment type, you will have the following matched authentication details, required for all interaction:

A gateway could be set up like this:

use Omnipay\GiroCheckout\Gateway;
use Omnipay\Omnipay;

// The backward slashes are needed to make the driver base class absolute.
// An issue will be raised against Omnipay Common to fix this.
$gateway = Omnipay::create('\\' . Gateway::class);
// or
$gateway = Omnipay::create('GiroCheckout/Gateway';

// The IDs can be given as integers in strings.
$gateway->setMerchantID('3610000');
$gateway->setProjectID('37000');
$gateway->setProjectPassphrase('ZFXDMpXDMpVV9Z');
// Other payment types are supported.
$gateway->setPaymentType(Gateway::PAYMENT_TYPE_CREDIT_CARD);

// or

$gateway->initialize([
    'merchantId' => 3610000,
    'projectId' => 37000,
    'projectPassphrase' => 'ZFXDMpXDMpVV9Z',
    'paymentType' => Gateway::PAYMENT_TYPE_CREDIT_PAYPAL,
]);

Credit Card Payment Type

This payment type supports authorize and purchase. A card can be tokenised during a transaction and used again for future payments with the user present, or for offline repeat payments.

The capture/refund/void methods are also available.

Credit Card Authorize

Basic Authorize

A simple authorize will look like this:

use Money\Money;
use Money\Currency;

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_CREDIT_CARD);

$authRequest = $gateway->authorize([
    'transactionId' => $yourMerchantTransactionId,
    //
    // Several ways to supply the amount:
    'amount' => '4.56',
    'amount' => new Money(456, new Currency('EUR')),
    'amount' => Money::EUR(456),
    //
    'currency' => 'EUR',
    'description' => 'Mandatory reason for the transaction',
    'language' => 'en',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'mobile' => false,
]);

The response will be a redirect to the gateway, where the user will enter their credit card details. The language setting will define the language used in the user interface and in error messages returned in the response.

On completion, the result of the transaction will sent to the merchant site in two ways (both will be used):

The notifyUrl and the returnUrl can both take custom query parameters. The gateway will merge in its own parameters when using the URLs.

Credit Card Complete Authorize

When the user returns to the returnUrl, the transaction result can be extracted like this:

$completeRequest = $gateway->completeAuthorize();
$completeResponse = $completeRequest->send();

// Available standard Omnipay details:

$completeResponse->getCode();
$completeResponse->getMessage();
$completeResponse->isSuccessful();
$completeResponse->isCancelled();
$completeResponse->getTransactionStatus();
$completeResponse->getTransactionReference();

If the response fails its hash check against the shared secret, then an exception will be raised on send(). The raw response data can still be read for logging as $completeRequest->getData(), which returns an array.

The notification handler, on the notifyUrl, is set up like this:

$notifyRequest = $gateway->acceptNotification();
$notifyResponse = $notifyRequest->send();

Once the authorisation is complete, the amount still needs to be captured.

Credit Card Authorize Notify

Exactly the same rules apply as to the completeAuthorize request - an exception will be raised if the hash does not validate; the same standard Omnipay result details are available.

Create a Reusable Card Reference

When authorizing, the gateway can be asked to create a reusable card reference. This flag in the authorize request will trigger that:

$authRequest = $gateway->authorize([
    ...
    'createCard' => true,
]);

After the authorize completes, the card reference is fetched using this request:

$getCardRequest = $gateway->getCard([
    'transactionReference' => 'otiginal transaction reference',
]);
$getCardResponse = $getCardRequest->send();

// The reusable `cardReference` is available here:
$cardReference = $getCardResponse->getTransactionReference();

// Other details about the card that may be useful:
$getCardResponse->getNumberMasked();
$getCardResponse->getExpiryYear();
$getCardResponse->getExpiryMonth();

The $cardReference is then used for authorizing:

$authRequest = $gateway->authorize([
    ...
    'cardReference' => $cardReference,
]);

The user will be redirected to the payment gateway like the basic authorize, but the credit card details will be already completed (and cannot be changed by the user). The user will need to enter their CVV to authorise use of the card.

By setting the recurring parameter flag, even the need for the CVV to be entered can be avoided. This feature is only available on application. Even through the user will be redirected to the gateway, they will be redirected back again immediately with no need to enter any card or CVV details. However, the redirect does give the gateway the option to insert some additional validation if it needs to.

Offline Repeat Authorize

When a reusable cardReference is used, the need to redirect the user to the gateway can be avoided by resetting the paymentPage parameter.

$authRequest = $gateway->authorize([
    ...
    'paymentPage' => false,
]);

This can be used without the user being present, so is useful for subscriptions and other repeated payments.

Credit Card Purchase Transactions

Replace purchase in place of authorize.

Credit Card Capture

The required amount can be captured using this request:

$captureRequest = $gateway->capture([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(123),
    'currency' => 'EUR',
    'description' => 'Capture reason is required',
    'transactionReference' => 'original authorize transaction reference',
]);

$captureRersponse = $captureRequest->send();

// Check if successful:
$captureRersponse->isSuccessful();

// Some other details:
$captureRersponse->getCode();
$captureRersponse->getMessage();
$captureRersponse->getTransactionReference();

Credit Card Refund

A refund of the full or a partial amount can be done using the refund message. It is used in exactly the same way as the capture message.

Credit Card Void

A transaction can be completely voided like this:

$voidRequest = $gateway->capture([
    'transactionReference' => 'original authorize transaction reference',
]);

$voidResponse = $voidRequest->send();

// Check if successful:
$captureRersponse->isSuccessful();

Direct Debit Payment Type

The Direct Debit payment type works in a very similar way to the Credit Card payment type. The main differences are:

Basic Authorize

A simple authorize will look like this:

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_DIRECTDEBIT);

$authRequest = $gateway->authorize([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(456),
    'currency' => 'EUR', // Optional if the amount is Money
    'description' => 'Mandatory reason for the transaction',
    'language' => 'en',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'mobile' => false,
    // Parameters specific to Direct Debit, all optional:
    'mandateReference' => '...',
    'mandateSignedOn' => '...',
    'mandateReceiverName' => '...',
    'mandateSequence' => '...',
]);

The mandateSignedOn is a date in the forma YYYY-MM-DD. A DateTime or derived object can ve supplied instead, which includes Carbon\Carbon objects.

Create a Reusable Direct Debit Card Reference

The Direct Debit payment type supports saving the details of the collected bank details as a cardReference. Triggering the saving is done by turning on creatCard like this:

$authRequest = $gateway->authorize([
    ...
    'createCard' => true,
]);

The cardReference can be fetched in the same way as the Credit Card payment type.

Offline Direct Debit Payment

The payment page redirect can be turned off to support offline payment, without the user being present:

$authRequest = $gateway->authorize([
    ...
    'paymentPage' => false,
]);

When making an offline payment, one of the following must be supplied:

$authRequest = $gateway->authorize([
    ...
    'cardReference' => '13b5ca34a8389774690154bcc0da0a8e',
    // or
    'iban' => 'DE87123456781234567890',
    // or
    'accountHolder' => 'Name',
    'bankCode' => '12345678',
    'bankAccount' => '1234567890',
]);

Direct Debit Capture/Refund/Void

These operate in exactly the same way as for Credit Card payments.

PayPal Payment Type

The PayPal payment type supports only one request type, purchase.

PayPal Purchase

A simple purchase will look like this:

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_PAYPAL);

$authRequest = $gateway->purchase([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => Money::EUR(789),
    'currency' => 'EUR',
    'description' => 'Mandatory reason for the transaction',
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
]);

The response should be a redirect to the remote gateway.

On return from the gateway, the result can be accessed using the $response -> $gateway->complete()->send() message like for previous payment types.

The back-channel notification handler will be sent the usual details too.

Giropay Payment Type

This payment type only works for payments in Euros, and only for issuing banks that have registered with the service (over 1400 to date).

As well as making payments, there are a number of supporting API methods.

Giropay Issuers List

This method returns a list of issuing banks that are regisered for this service. The list would normally be used to present to the end user so they can choose their personal bank.

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_GIROPAY);

$request = $gateway->getIssuers();

$response = $request->send();

// The list of named banks is indexed by their BIC.

if ($response->isSuccessful()) {
    $bankList = $response->getIssuerArray();

    var_dump($bankList);
}

// array(1407) {
//  ["BELADEBEXXX"]=>
//  string(38) "Landesbank Berlin - Berliner Sparkasse"
//  ["BEVODEBBXXX"]=>
//  string(18) "Berliner Volksbank"
//  ["GENODEF1P01"]=>
//  string(27) "PSD Bank Berlin-Brandenburg"
//  ["WELADED1WBB"]=>
//  string(9) "Weberbank"
//  ...
// }

Giropay Bank Capabilities

Once an issuing bank is chosen, its capabilities can be checked. This tests whether it supports Giropay, or Giropay+ID, or both.

This list can also be retrieved on the front end only using the Bank Selection Widget. There is no direct support for the widget in this driver.

$request = $gateway->getBankStatus([
    'bic' => 'TESTDETT421',
]);

$response = $request->send();

// Both return boolean.

$supportsGiropay = $response->hasGiropay();
$supportsGiropayId = $response->hasGiropayId();

Giropay Purchase

There is no authorize capability, just purchase.

$request = $gateway->purchase([
    'transactionId' => $transactionId,
    'amount' => Money::EUR(123),
    'currency' => 'EUR',
    'description' => 'Transaction ' . $transactionId,
    'returnUrl' => 'url to bring the user back to the merchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
    'bic' => 'TESTDETT421', // mandatory
    'info1Label' => 'My Label 1',
    'info1Text' => 'My Text 1',
]);

The result will be a redirect to the gateway or bank.

On return, the usual completePurchase and acceptNotification messages will provide the result of the transaction attempt.

The final result includes the following methods to inspect additional details:

$notifyResponse->getResultAvs();
$notifyResponse->getObvName();
$notifyResponse->isAgeVerificartionSuccessful();

Giropay Sender Details

Details of the sender can be fetched given a successful transaction.

$request = $gateway->getSender([
    'transactionReference' => '6b65a235-e7c1-464f-b238-ea4ea0bc647f',
]);

$response = $request->send();

Details include:

$response->getAccountHolder();
// string(17) "Stefan Adlerhorst"

$response->getIban();
// string(22) "DE46940594210000012345"

$response->getBic();
// string(11) "TESTDETT421"

Giropay ID (age verification)

Use the Giropay-ID payment type to just perform age verification without making a payment. You can leave out the amount, currency and description, as none of those are sent to the gateway.

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_GIROPAY_ID);

Paydirekt Payment Type

This is the only payment type that accepts a shopping cart details and a CreditCard object for shipping details.

Capabilities of this payment type include authorize and purchase. An authorization transaction can be further processed though capture and void. A purchase transaction can accept a refund.

The gateway requires cart item prices to be in minor units. Since Omnipay 2.x (or 3.x at this time) does not define the units cart items use, some assumptions will be made and conversions performed as follows (all these formats are treated as the same amount, namely 123 minor units, such as €1.23):

If no currency is set explicitly with setCurrency() then it will be taken from the amount if using a Money\Money object. To avoid ambiguity, we recommend you use Money\Money for all ItemBag price amounts.

Payment Page Payment Type

This payment type offers the customer all payment methods available from the merchant rather than displaying them separately. The payment page allows the customer to select the payment method they wish to use and then the selected payment is initialized accordingly.

Payment Page Projects List

This method returns a list of possible GiroCockpit projects. The list contains the following elements:

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_PAYMENTPAGE);

$request = $gateway->getProjects();

$response = $request->send();

if ($response->isSuccessful()) {
    $projects = $response->getProjects();

    var_dump($projects);
}

// array(5) {
//     [0]=>
//     array(4) {
//       ["id"]=>
//       string(5) "37570"
//      ["name"]=>
//       string(11) "Giropay One"
//       ["paymethod"]=>
//      string(1) "1"
//       ["mode"]=>
//       string(4) "TEST"
//     }
//    ...
// }

Cancel Url

The Payment Page's cancelUrl differs to the rest of the payment types as it does not return the transaction cancelled details. If the user follows the cacnel URL from this payment method, it seems the transaction is not actually cancelled, but is left to time out instead, at which point your merchant site will be sent a cancellation notification. In summary, you must not call completeAuthorise when returning to the merchant site from the Payment Page payment type.

Bluecode Payment Type

This payment type works currently only with bank accounts in Germany and Austria.

Bluecode only supports purchase (sale) and refund operations. There is not authorize and/or void, like with credit cards.

Bluecode Purchase

Issue a purchase transaction:

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_BLUECODE);

$purchaseRequest = $gateway->purchase([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => 4.56,
    'currency' => 'EUR', // or any other valid currency code
    'description' => 'Reason for the transaction',
    'returnUrl' => 'url to bring the user back to the marchant site',
    'notifyUrl' => 'url for the gateway to send direct notifications',
]);

Bluecode Refund

Issue a refund

$gateway->setPaymentType(Gateway::PAYMENT_TYPE_BLUECODE);

$refundRequest = $gateway->refund([
    'transactionId' => $yourMerchantTransactionId,
    'amount' => 4.56,
    'currency' => 'EUR', // or any other valid currency code
    'description' => 'Reason for the transaction',
    'transactionReference' => 'original purchase transaction reference'
]);