README

GiroCheckout driver for the Omnipay PHP payment processing library

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.

Omnipay: GiroCheckout
Table of Contents
Installation
Authentication
Credit Card Payment Type
Direct Debit Payment Type
- Basic Authorize
  - Create a Reusable Direct Debit Card Reference
  - Offline Direct Debit Payment
- Direct Debit Capture/Refund/Void
PayPal Payment Type
- PayPal Purchase
Giropay Payment Type
Paydirekt Payment Type
Payment Page Payment Type
- Payment Page Projects List
- Cancel Url
Bluecode Payment Type
- Bludcode Purchase
- Bluecode Refund

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:

Merchant ID
Project ID
Pre-shared secret (passphrase)
Payment type

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):

Via the notification URL.
Through query parameters given to the return URL.

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:

The bank account is identified by an IBAN or a sort code/bank code/BMZ and account number (SCAN).
When fetching the saved "cardReference", details you get back include ibanMasked.
Running an authorize or payment without a paymentform, you can supply IBAN, SCAN or cardReference.

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:

cardReference
IBAN
SCAN

$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):

Money\Money::EUR(123)
String '1.23'
String '123'
Integer 123
Float 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:

Project Id
Project Name
Paymethod Number (see Payment methods)
Mode (TEST or LIVE)

$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'
]);

academe / omnipay-girocheckout

Maintainers

Details

README

Table of Contents

Installation

Authentication

Credit Card Payment Type

Credit Card Authorize

Basic Authorize

Credit Card Complete Authorize

Credit Card Authorize Notify

Create a Reusable Card Reference

Offline Repeat Authorize

Credit Card Purchase Transactions

Credit Card Capture

Credit Card Refund

Credit Card Void

Direct Debit Payment Type

Basic Authorize

Create a Reusable Direct Debit Card Reference

Offline Direct Debit Payment

Direct Debit Capture/Refund/Void

PayPal Payment Type

PayPal Purchase

Giropay Payment Type

Giropay Issuers List

Giropay Bank Capabilities

Giropay Purchase

Giropay Sender Details

Giropay ID (age verification)

Paydirekt Payment Type

Payment Page Payment Type

Payment Page Projects List

Cancel Url

Bluecode Payment Type

Bluecode Purchase

Bluecode Refund