Download the PHP package academe/omnipay-payone without Composer

On this page you can find all versions of the php package academe/omnipay-payone. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of academe/omnipay-payone

Informations about the package omnipay-payone

GitHub license Packagist GitHub issues Build Status

Table of Contents

Omnipay: PAYONE

PAYONE driver for the Omnipay PHP payment processing library

Written to specication:

Omnipay 3.x is a framework agnostic, multi-gateway payment processing library for PHP 7.1+. This package implements PAYONE support for OmniPay.

Installation

This is the master branch for the current Omnipay 3.x branch (tested against 3.0-beta.1). The older 2.x branch can be found here

Omnipay is installed via Composer. To install, add it to your composer.json file:

or direct from packagist

composer require "academe/omnipay-payone: ~3.0"

And run composer to update your dependencies:

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update

Basic Usage

The following gateways are provided by this package:

For general usage instructions, please see the main Omnipay repository. You will find more specific details can be found below.

Gateway Background

The PAYONE API has three main access points of interest to e-commerce:

The Server API is mainly for capturing authorized payments and the Front end is for setting up CC forms. The Client side is for supporting AJAX in the browser. You can also do authorisations and make payments using the Server API, so long as you are fully aware of the PCI implications.

The Server API also has a notification handler for receiving the payment results and captured user information from the PAYONE servers.

You will most likely be using a mix of Server, Frontend and Client functions as they complement each other.

Shop and Access API Versions

A payment portal is set up on PAYONE as one of two versions:

The Shop portal version is used for one-off payments. The Access portal version is used for subscriptions, invoicing, continuous renewals and services. Some of the payment methods are available just to the Shop version and some are available just to the Access version. Some methods are available to both versions, but accept slightly different sets of parameters.

For now, this package will deal with the Shop version only. However, the naming of classes and services will allow for Access version methods to be added later if required.

Extended Items (Order Lines)

The PAYONE API supports two additional cart item properties that must be completed (id and vat). Since the core OmniPay v2 Item object cannot accept custom property values, this has been extended. The extended Item class can be found here:

\Omnipay\Payone\Extend\Item

Creating an Item uses these fields:

The price can be supplied in minor currency units or major currency units. The following Item prices are equivalent in dollars or Euros (currencies with two decimal places):

The vat value is the VAT rate, expressed as a percentage (%) or as a basis point (‱). The rules are as follows:

The items are then added to the ItemBag in the normal way as an array of objects:

The total price of the ItemBag does not appear to need to add up to the order total for the Shop Server API methods when clearing by credit card. It MUST however sum to the order total for the Shop Frontend methods, and it must sum correctly when using the CLEARING_TYPE_WLT clearing type.

If you do not use the extended Item then default values will be substituted ("000000" for the id and null for the vat figure). If you do not supply any items at all for the Shop Frontend methods, then a default item for the full price will be created automatically. The Shop Frontend must have a basket of at least one item, which is why this driver will create a default item if you do not supply a basket.

The Shop Server API Gateway

Create a gateway object to access the Server API Shop version methods:

Server API Authorize Payment

PAYONE calls this "pre-authorization". It authorizes a payment to be captured later.

To create an authorization request:

The driver will attempt to work out the card type from the card number, but if it fails or you are using a card type not yet supported by the driver or by OmniPay, then you can supply your own card type letter.

The $card details are populated like any other standard OmniPay card, with one exception detailed below. You can supply the details as an array or as a \Omnipay\Common\CreditCard object.

The ecommerceMode overrides the 3D Secure configuration set in the portal. Values include internet to turn off 3D Secure, 3dsecure to turn on 3D Secure and moto for telephone and email payments. Note: when capturing an authorized payment, the same ecommerceMode must be used or the capture will be rejected. However, PAYONE will wrap the bank's 3D Secure form on its own site, because it provides no additional POST data to send.

These four fields normally define the details for a credit card:

PAYONE will also accept a "pseudo-card" number. This is a temporary token supplied by another process (e.g. a "creditcardcheck") and used in place of a card. If supplying a pseudo-card number, leave the remaining card fields blank or null. The gateway driver will then treat the card number as a pseudo-card:

It is strongly recommended to only work with pseudo card numbers through the Server API channel, to reduce potential PCI DSS issues. A pseudo card number should be obtained through the Client API channel using the "hosted iFrame" functionality.

Also to note about the card data is that countries must be supplied as ISO 3166 two-letter codes:

and states must be supplied as ISO 3166-2 sub-division codes (various formats, depending on the country):

The return URL and cancel URL (when using 3D Secure) are normally set in the account settings, but can be overridden here:

Send this request to PAYONE to get the response:

The standard OmniPay documentation shows how to handle the response. In addition, in the event of an error, there will be the normal loggable error message, and a separate error message that is safe to put in front of an end user:

Server API Purchase

PAYONE calls this "authorization". It authorizes and captures a payment immediately.

It is used and responds in the same way as authorize. The request message is created like this:

Server API Capture

Once a payment has been authorised, it may be captured. This is done using this minimal message:

That will capture the amount specified and settle the account. If you want to leave the account open for capturing the total in multiple stages, then specify for the account to be left unsettled:

The sequence number starts at 1 for the first capture, and must be incremented for each subsequent capture. It should be taken from the Notification Callback, see below.

For invoicing module some additional parameters have to be provided:

And in capture request:

Note that the email field in card details has to be passed to authorize method in pre-authorization step since it's the email that will be used by Payone to send invoice to customer.

Server API Void

To void an authorized payment:

The void method will response with a ShopCaptureResponse response when sent to PAYONE.

Server API Credit Card Check

This method will check that the details of a credit card are plausible and optionally tokenize the card details for use in other methods. The Credit Card Check method is available both for Server direct requests, and for AJAX calls on the Client side.

The request is set up like this:

If the credit card details are plausible, then the response will be successful:

If the response is not successful, then details will be available in getCode(), getMessage() and getCustomerMessage().

If the response is successful and storeCard is TRUE then two additional items of data will be available:

In any API that requires credit card details, you can substitute the details with the token, for example:

Normally the token will come from the web client (AJAX in the browser) but this Server API can be used during development and testing with test cards.

The Shop Front End API Gateway

The Front End gateway supports hosted payment forms, taking either just credit card or bank details, or full personal details too. The forms are hosted on the PAYONE site, can be customised, and can be either presented to the end user in an iframe, or the end user can be fully redirected to the remote form.

Front End Authorize

The Front End API methods are encapsulated into a separate gateway class:

Sending an authorization involves setting up the request message:

The accessMethod will be "classic" or "iframe"; default is ShopFrontendAuthorizeRequest::ACCESS_METHOD_CLASSIC The redirectMethod will be "GET" or "POST"; default is ShopFrontendAuthorizeRequest::REDIRECT_METHOD_GET

The items are optional, but if you do not supply at least one item, then a default item will be created for you; the cart is mandatory for the Frontend API, unlike the Server API.

The card billing details can be used to pre-populate the payment form. If the personal details have been checked and known to be valid (another API is able to do that) then the name and address fields can be hidden on the payment form using 'showName' => false and 'showAddress' => false.

Note that it may not be possible to override the URLs as shown above. It may be possible to set these URLs only if not defined in the account settings. The documentation is not entirely clear on this.

The response message (from OmniPay) for performing the next action is:

The response will be a redirect response, either GET or POST, according to the redirectMethod parameter.

You can retrieve the GET URL and redirect in your application, or leave OmniPay to do the redirect:

For the POST redirectMethod, again, you can just let OmniPay do the redirect, but you will probably want to build your own form and target it at an iframe in the page. The two things you need to build the form is the target URL, and the form items. The form items are supplied as name/value pairs.

On return from the remote gateway, if using the iframe, you will need to break out of the iframe to get to the final page in your merchant site. The PAYONE API does have iframe-busting functionality built in. Set the setTargetWindow() on your authorize request to tell the gateway where to take the user. Accepted values are given in ShopFrontendAuthorizeRequest::TARGET_WINDOW_*.

Note that this driver does not attempt to generate HTML forms. It will instead give you the data for creating your own HTML forms.

After the user has completed their details on the PAYONE site, a notification of the result will be sent back to your merchant site, and then the user will be returned to either the "success" page or the "failure" page. No data will be carried with that redirect, so the transaction details must be retained in the session to match up with the results in the notification back-channel.

Front End Purchase

Works the same as Front End Authorize, but will require a separate Server API Capture.

Front End Credit Card Check

Set this up the same way as the Client API Credit Card Check. The response is then used to generate the data you will need for the JSON to configure the form you will use to tokenise the card:

$jsonForJavaScript = json_encode($request->send()->getData());

Setting up the card tokenisation form and JavaScript to process it, is out of scope for this guide. The official documentation provides good examples. Just replace the sample request config data with the contents of $jsonForJavaScript.

The Shop Client API Gateway

The Shop Client gateway handles payments using client AJAX calls or forms on the merchant site that are POSTed direct to the PAYONE gateway.

Client API Credit Card Check

This is similar to the Server API Credit Card Check, and is set up in a similar way. No credit card details are passed to it however, as that is handled on the client.

This provides the following data to feed into your client:

Then on the client you need to provide the credit card fields in a non-submitting form (form items with no name attributes):

These values will be constructed by your client code, then submitted to the end point. The cardexpiredate for example, could be two drop-down lists concatenated. The cardtype could be a drop-down list, or a client library could set it automatically by matching card number patterns.

The result will be a JSON response something like this:

Handling that data is out of scope for OmniPay, but the most important value here is the pseudocardpan which can be used in any server API call in place of the real credit card number (e.g. the Shop Server Authorize method).

The official PAYONE documentation explains further how this works, and provides sample client code fragments.

It is recommended to use the "hosted iFrame" mode of capturing credit card data. It is out of the scope of OmniPay and described in more detail here.

Client API Authorize

There are two main modes the client authorize operates in:

The REDIRECT mode supports the building of a complete payment form on the merchant site that POSTs direct to the PAYONE gateway. The result of the authorisation will be POSTed by PAYONE to the Notification handler. The gateway will also return the success status to the merchant site with the user when they are directed back so long as 3D Secure is not being used. It is important to note that if 3D Secure is used and the end user is redirected to enter their 3D Secure password, then they will be returned to your site's success/failure/cancel URL with no data, so the merchant site must save enough details in the session to pick up the authorisation results sent via the Notification back-channel handler.

The AJAX mode is set up the same way, but all the details are POSTed via AJAX rather then as a standard browser form. The result comes back as a JSON response, which may include a 3D Secure redirect, or may just contain the authorisation result.

Setting up the message is much the same as other methods. It is the same for both the REDIRECT and the JSON response types:

The $response now contains the details needed for either hidden fields in the client-side direct POST form, or for the AJAX call. These details are:

In addition to $params you need to include the following data provided by the end user:

If your redirectMethod was REDIRECT, then all this information will be put into a form that the user submits. The form will POST directly to PAYONE. What happens next will depend on whether 3D Secure has been turned on and is availa to the card used.

If your responseType was JSON (ShopClientGateway::RETURN_TYPE_REDIRECT), then the merchant site client page is expected to POST the data using AJAX. The return will be a JSON message detailing the result, which can be a success, failure, or a redirect for 3D Secure. Handling that response is out of scope for OmniPay, but the PAYONE documentation provides some examples and some handy scripts.

Client completeAuthorize

This can be used to parse the resturn data from the server request (i.e. the data the user brings back with them):

The $server_response can give you a number of standardised items:

Client API Purchase

This works the same way as Client API Authorize but uses the purchase method instead.

You would still use completeAuthorize with the purchase API.

Notification Callback

For most - if not all - transactions, PAYONE will send details of that transaction to your notification URL. This URL is specified in the PAYONE account configuration. For most of the Server API methods it is a convenience. For the Frontend methods it is essential, being the only way of getting a notification that a transaction has completed.

The notification comes from IP address 185.60.20.0/24 (185.60.20.1 to 185.60.20.254). This driver does not make any attempt to validate that.

Your application must respond to the notification within ten seconds, because when a Frontend hosted form is used, the user will be waiting on the PAYONE site for the acknowledgement - just save the data to storage and end.

The notification Server Request (i.e. incoming request to your server) is captured/handled by the completeStatus class created using the standard OmniPay acceptNotification() gateway method.

So long as the notification is valid, you can also get the status of the transaction. The following table lists the way this driver maps the status and and the event (the txaction) to Omnipay's overall status values ("-" neans "anything"):

transaction_status txaction Overall transaction status Notes
completed - STATUS_COMPLETED
- appointed STATUS_COMPLETED
- paid STATUS_COMPLETED
- invoice STATUS_COMPLETED
- capture STATUS_PENDING
- underpaid STATUS_PENDING
- refund STATUS_PENDING
- debit STATUS_PENDING
- reminder STATUS_PENDING
- vauthorization STATUS_PENDING
- vsettlement STATUS_PENDING
- transfer STATUS_PENDING
- cancelation STATUS_FAILED
- failed STATUS_FAILED
- - STATUS_FAILED

Individual data items can also be extracted from the server request (see list below).

Once the data is saved to the local application, respond to the remote gateway to indicate that you have received the notification:

List of $server_request data methods:

completeAuthorize and completePurchase Methods

Although the Frontend purchase and authorize take the user offsite (either in full screen mode or in an iframe), no data is returned with the user coming back to the site. as a consequence, the completeAuthorize and completePurchase methods are not needed.

3D Secure involves a visit to the authorising bank. However, PAYONE will wrap that visit up into a page that it hosts (the page will contain an iframe). This means the result, if a 3D Secure password is needed, will still be sent to the merchant site through the same notification URL as any non-3D Secure transaction. One advantage is that your merchant site does not need to mess around with PAReq/PARes parameters and suchlike from the end banks.

References

All versions of omnipay-payone with dependencies

PHP Build Version
Package Version
Requires omnipay/common Version ~3.0
moneyphp/money Version ^3.1|^4.0.3
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package academe/omnipay-payone contains the following files

Loading the files please wait ....