Download the PHP package academe/omnipay-girocheckout without Composer

Omnipay: GiroCheckout

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.

Table of Contents

• Omnipay: GiroCheckout
• 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
  • 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:

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:

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:

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:

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:

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

The $cardReference is then used for authorizing:

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.

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:

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:

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:

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:

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:

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

• cardReference
• IBAN
• SCAN

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:

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.

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.

Giropay Purchase

There is no authorize capability, just purchase.

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:

Giropay Sender Details

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

Details include:

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.

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)

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:

Bluecode Refund

Issue a refund