academe / omnipay-payone
PAYONE gateway driver for the Omnipay PHP payment processing library
Installs: 157 766
Dependents: 0
Suggesters: 0
Security: 0
Stars: 15
Watchers: 4
Forks: 16
Open Issues: 9
Requires
- moneyphp/money: ^3.1|^4.0.3
- omnipay/common: ~3.0
Requires (Dev)
- omnipay/tests: ~3.0|~4.0
- squizlabs/php_codesniffer: ^3
This package is auto-updated.
Last update: 2024-12-21 03:48:16 UTC
README
Table of Contents
- Table of Contents
- Omnipay: PAYONE
- References
Omnipay: PAYONE
PAYONE driver for the Omnipay PHP payment processing library
Written to specication:
- TECHNICAL REFERENCE PAYONE Platform Channel Client API 1.28 (2016-05-09)
- TECHNICAL REFERENCE PAYONE Platform Channel Server API 2.84 (2016-05-09)
- TECHNICAL REFERENCE PAYONE Platform Frontend 2.40 (2016-05-09)
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:
{ "require": { "academe/omnipay-payone": "~3.0" } }
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:
- Payone_ShopServer
- Payone_ShopFrontend
- Payone_ShopClient
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:
- Server API - for interacting directly with server without user intervention.
- Frontend API - for delivering hosted credit card (CC) forms to the user (iframe or redirect).
- Client API - for interacting with a JavaScript front end.
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:
- Shop
- Access
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:
$lines[] = new \Omnipay\Payone\Extend\Item([ 'id' => '{merchant-site-stock-ID}', 'name' => '{product-name}', 'quantity' => 2, 'price' => 123, 'vat' => 20, // Optional // Used but optional for clearingType = \Omnipay\Payone\AbstractShopGateway::CLEARING_TYPE_WLT // and walletType = \Omnipay\Payone\AbstractShopGateway::WALLET_TYPE_PPE 'itemType' => \Omnipay\Payone\Extend\ItemInterface::ITEM_TYPE_GOODS, ]);
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):
- 123
- 1.23
- "123"
- "1.23"
The vat
value is the VAT rate, expressed as a percentage (%)
or as a basis point (‱).
The rules are as follows:
- Any integer up to 99 will be interpreted as a percentage.
- Any integer 100 to 9999 will be interpreted as a basis point.
The items are then added to the ItemBag
in the normal way as an array of objects:
$items = new \Omnipay\Common\ItemBag($lines);
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:
$gateway = Omnipay\Omnipay::create('Payone_ShopServer'); // Merchant Account ID $gateway->setMerchantId(12345); // Merchant Portal ID $gateway->setPortalId(1234567); // Sub-Account ID $gateway->setSubAccountId(56789); // True to use test mode. $gateway->setTestMode(true); // Default language is "en" and determines the language of forms and error messages. $gateway->setLanguage("de"); // Currency as ISO 4217 three-character code $gateway->setCurrency('EUR');
Server API Authorize Payment
PAYONE calls this "pre-authorization". It authorizes a payment to be captured later.
To create an authorization request:
$request = $gateway->authorize([ // Unique merchant site transaction ID 'transactionId' => 'ABC123', // Amount as decimal. 'amount' => 0.00, // Pre-shared secret key used for hashing and authentication. 'portalKey' => 'Ab12Cd34Ef56Gh78', // Card and personal details. 'card' => $card, // Optional card type override. //'cardType' => 'V', // The ItemBag/Cart 'items' => $items, // Optional ecommerce mode declares risk 'ecommerceMode' => '3dsecure', ]);
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:
[ ... 'number' => '4111111111111111', 'expiryYear' => '2020', 'expiryMonth' => '12', 'cvv' => '123', ];
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:
[ ... // A pseudo-card number. 'number' => '4111111111111111', // Other card details left as null. 'expiryYear' => null, 'expiryMonth' => null, 'cvv' => null, ];
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:
'billingCountry' => 'US',
and states must be supplied as ISO 3166-2 sub-division codes (various formats, depending on the country):
'billingCountry' => 'US', 'billingState' => 'AL',
The return URL and cancel URL (when using 3D Secure) are normally set in the account settings, but can be overridden here:
// Return URL on successful authorisation. 'returnUrl' => '...', // Return URL on failure to authorise the payment. 'errorUrl' => '...', // Return URL if the user choses to cancel the authorisation. 'cancelUrl' => '...',
Send this request to PAYONE to get the response:
$response = $request->send();
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:
if (!$response->isSuccessful()) { echo $response->getMessage(); // e.g. "Expiry date invalid, incorrect or in the past" echo $response->getCustomerMessage(); // e.g. "Invalid card expiry date. Please verify your card data." }
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:
$request = $gateway->purchase([...]);
Server API Capture
Once a payment has been authorised, it may be captured. This is done using this minimal message:
$request = $gateway->capture([ // The reference for the original authorize transaction. 'transactionReference' => '123456789', // Amount as decimal. 'amount' => 1.23, // Pre-shared secret key used for authentication, if not already set on $gateway. 'portalKey' => 'Ab12Cd34Ef56Gh78', ]);
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:
'sequenceNumber' => $sequence, 'settleAccount' => false,
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:
$lines[] = new \Omnipay\Payone\Extend\Item([ 'id' => '{merchant-site-stock-ID}', 'name' => '{product-name}', 'itemType' => 'goods', // Available types: goods, shipping etc. 'quantity' => 2, 'price' => 123, 'vat' => 20, // Optional ]); $items = new ItemBag($lines);
And in capture request:
'items' => $items, 'sequenceNumber' => 1, 'settleAccount' => false, 'invoiceid' => 1, 'invoiceDeliveryMode' => 'P', // PDF, for others look into documentation 'invoiceDeliveryDate' => date('Ymd'), 'invoiceAppendix' => 'This is your invoice appendix'
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:
$request = $gateway->void([ // The reference for the original authorize transaction. 'transactionReference' => '123456789', // Amount as decimal. 'amount' => 1.23, // Pre-shared secret key used for authentication, if not already set on $gateway. 'portalKey' => 'Ab12Cd34Ef56Gh78', ]); $response = $request->send();
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:
$gateway = Omnipay\Omnipay::create('Payone_ShopServer'); $gateway->setSubAccountId(12345); $gateway->setTestMode(true); // Or false for production. $gateway->setMerchantId(67890); $gateway->setPortalId(3456789); $gateway->setPortalKey('Ab12Cd34Ef56Gh78'); $request = $gateway->creditCardCheck([ 'card' => [ 'number' => '4012001037141112', 'expiryYear' => '2020', 'expiryMonth' => '12', 'cvv' => '123', ], 'storeCard' => true, ]); $response = $request->send();
If the credit card details are plausible, then the response will be successful:
$response->isSuccessful(); // true
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:
// The tokenised card: $token = $response->getToken(); // e.g. 4100000227987220 // The truncated card number: $response->getCardNumber() // e.g. 401200XXXXXX1112
In any API that requires credit card details, you can substitute the details with the token, for example:
$request = $gateway->authorize([ 'card' => [ 'number' => $token ], ...
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.
// Set up the Front End gateway. $gateway = Omnipay\Omnipay::create('Payone_ShopFrontend');
Front End Authorize
The Front End API methods are encapsulated into a separate gateway class:
$gateway = Omnipay\Omnipay::create('Payone_ShopFrontend'); // Merchant Portal ID $gateway->setPortalId(1234567); // Sub-Account ID $gateway->setSubAccountId(56789); // True to use test mode. $gateway->setTestMode(true); // Default language is "en" and determines the language of forms and error messages. $gateway->setLanguage("de"); // Currency as ISO 4217 three-character code $gateway->setCurrency('EUR'); // The pre-shared secret, used for hashing. $gateway->setPortalKey('Ab12Cd34Ef56Gh78'); // The default for this gateway is HASH_MD5 for legacy applications, but the hash // method recommended by PAYONE is HASH_SHA2_384, $gateway->setHashMethod($gateway::HASH_SHA2_384);
Sending an authorization involves setting up the request message:
$transactionId = {merchant-site-transaction-ID} $request = $gateway->authorize([ 'transactionId' => $transactionId, 'amount' => 3.99, 'accessMethod' => 'iframe', 'redirectMethod' => 'POST', 'items' => $items, 'card' => [ 'firstName' => 'Firstname', 'billingAddress1' => 'Street Name', ... ], // Any of these optional URLs can override those set in the account settings: 'returnUrl' => '...', 'errorUrl' => '...', 'cancelUrl' => '...', ]);
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:
$response = $request->send();
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:
// Get the URL. $url = $response->getRedirectUrl(); // Just do the redirect using the methods in OmniPay core. $response->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.
// This form needs JavaScript to auto-submit on page load. echo '<form action="' . $response->getRedirectUrl() . '" method="POST" target="target-iframe">'; foreach($response->getRedirectData() as $name => $value) { echo '<input type="hidden" name="'.$name.'" value="'.htmlspecialchars($value).'" />'; } echo '</form>'; // The autp-submitted form, tagetting at this iframe, will generate the // remote credit card payment form within this iframe. echo '<iframe name="target-iframe" width="400" height="650"></iframe>';
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.
// Set up the Client gateway. $gateway = Omnipay\Omnipay::create('Payone_ShopClient');
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.
$gateway = Omnipay\Omnipay::create('Payone_ShopClient'); $gateway->setSubAccountId(12345); $gateway->setTestMode(true); // Or false for production. $gateway->setMerchantId(67890); $gateway->setPortalId(3456789); $gateway->setPortalKey('Ab12Cd34Ef56Gh78'); $gateway->setHashMethod($gateway::HASH_SHA2_384); $request = $gateway->creditCardCheck(); $response = $request->send();
This provides the following data to feed into your client:
// The endpoint used to check the card details - GET or POST can be used. $endpoint = $response->getRedirectUrl(); // The additional data that must be included with the card data. // This will be an array that can be JSON encoded for the client JavaScript to use: $data = $response->getRedirectData();
Then on the client you need to provide the credit card fields in a non-submitting
form (form items with no name
attributes):
- cardpan - credit card number
- cardexpiredate - YYMM
- cardtype - e.g. V for Visa
- cardcvc2
- cardissuenumber - for UK Maestro only
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:
{ "status" : "VALID", "pseudocardpan" : "4100000228091881", "truncatedcardpan" : "401200XXXXXX1112", "cardtype" : "V", "cardexpiredate" : "2012" }
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:
- REDIRECT - The user POSTs directly to the PAYONE gateway, enters 3D Secure details there if necessary, then is sent back to your site.
- JSON - The user stays on your site initially while the authorisation is requested via AJAX. The client may then send the user to PAYONE to enter their 3D Secure password if required, but if not, then results can be posted directly back to the merchant site without the user leaving.
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:
$gateway = Omnipay\Omnipay::create('Payone_ShopClient'); $gateway->setSubAccountId(12345); $gateway->setTestMode(true); // Or false for production. $gateway->setMerchantId(67890); $gateway->setPortalId(3456789); $gateway->setPortalKey('Ab12Cd34Ef56Gh78'); // The default for this gateway is HASH_MD5 for legacy applications, but the hash // method recommended gby PAYONE is HASH_SHA2_384, $gateway->setHashMethod($gateway::HASH_SHA2_384); // Set up the response type - redirect the user or do an AJAX call. $gateway->setResponseType($gateway::RETURN_TYPE_REDIRECT); //$gateway->setResponseType($gateway::RETURN_TYPE_JSON); $request = $gateway->authorize([ 'transactionId' => $transactionId, // Merchant site ID (or a nonce for it) 'amount' => 9.99, // Major units 'currency' => 'EUR', '3dSecure' => false, // or true 'items' => $items, // Array or ItemBag of Items or Exten\Items // Where to send the user in authorisation suucess or falure. 'returnUrl' => $returnUrl, 'errorUrl' => $errorUrl, // Where to send the user on cancellation in 3D Secure form. 'cancelUrl' => $cancelUrl, ]); $response = $request->send();
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:
// Array of name/value pairs $params = $response->getRedirectData(); // The destination endpoint. $endpoint = $response->getRedirectUrl();
In addition to $params
you need to include the following data provided by
the end user:
- lastname - mandatory
- country - ISO3166 e.g. GB
- cardpan
- cardexpiredate YYMM
- cardtype - e.g. V
- cardcvc2
- cardissuenumber - UK Maestro only
- cardholder - optional
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 3D Secure is available, PAYONE will present the end user with a 3D Secure password form.
The user will then be returned to the site with no results. The results will be send to
the
Notification
handler where the merchant site must fetch them using the merchant sitetransactionId
. - If 3D Secure is NOT available, then the card will be validated and the user returned to the
merchant site with the results as GET parameters. The result cannot be trusted as it is
not signed, but can be useful in the flow. The result can be captured using the
completeAuthorize
message (see below).
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):
$gateway = Omnipay\Omnipay::create('Payone_ShopClient'); $server_request = $gateway->completeAuthorize(); $server_response = $server_request->send();
The $server_response
can give you a number of standardised items:
// The raw data $server_response->getData(); // The authorisation success state: $server_response->isSuccessful(); // The redirect status and URL (we would not expect to see this for a REDIRECT response // type as the redirect has already been processed on the client side: $server_response->isRedirect(); $server_response->getRedirectUrl() // If there are errors, then there will be a system message and a user-safe message: $server_response->getMessage(); $server_response->getCustomerMessage();
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.
$gateway = Omnipay\Omnipay::create('Payone_ShopServer'); // The portal key must be provided. // This will be used to verify the hash sent with the transaction status notification. // PAYONE will send an MD5 hash at all times. This is subject to change and will support // the option to use a SHA2-384 hash eventually. $gateway->setPortalKey('Ab12Cd34Ef56Gh78'); $server_request = $gateway->acceptNotification(); // The raw data sent is available: $data = $server_request->getData(); // Provides the result of the hash verification. // If the hash is not verified then the data cannot be trusted. $server_request->isValid();
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"):
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:
$server_response = $server_request->send(); // Your application will exit on the next command by default. // You can prevent that by passiong in `false` as a single parameter, but // do make sure no further stdout is issued. $server_response->acknowledge(); // or $server_response->send()
List of $server_request data methods:
- getPaymentPortalKey() - MD5 or SHA2 384, depending on portal account configuration
- getPaymentPortalId()
- getSubAccountId()
- getEvent() - the name of the reason the notification was sent. Includes "appointed", "capture", "paid", "underpaid", "cancelation", "refund", "debit", "reminder", "vauthorization", "vsettlement", "transfer", "invoice", "failed"
- getAccessName()
- getAccessCode()
- getTxStatus() - the raw status code
- getTransactionStatus() - OmniPay transaction status codes
- getTransactionId()
- getTransactionReference()
- getNotifyVersion()
- getParam()
- getMode() - test or live
- getSequenceNumber()
- getClearingType() - 'cc' for credit card; 'wlt' and walletType = 'PPE' for PayPal Express
- getWalletType() - 'PPE' for PayPal Express
- getTxTimestamp() - raw unix timestamp
- getTxTime() - timestamp as a \DateTime object
- getCompany()
- getCurrency() - ISO three-letter code
- getCurrencyObject() - as an OmniPay
Currency
object - getDebtorId()
- getCustomerId()
- getNumber() - the CC number with hidden middle digits e.g. 411111xxxxxx1111"
- getNumberLastFour() - e.g. "1111"
- getCardType() - PAYONE single-letter code, e.g. "V", "M", "D".
- getBrand() - OmniPay name for the card type, e.g. "visa", "mastercard", "diners".
- getExpireDate() - YYMM format, as supplied
- getExpireDateObject() - expiry date returned as a \DateTime object
- getCardholder() - documented, but seems to be blank most of the time
- getFirstName()
- getLastName()
- getName()
- getStreet()
- getAddress1() - alias of getStreet()
- getCity()
- getPostcode()
- getCountry() - ISO code
- getShippingFirstName()
- getShippingLastName()
- getShippingName()
- getShippingStreet()
- getShippingAddress1() - alias of getShippingStreet()
- getShippingCity()
- getShippingPostcode()
- getShippingCountry() - ISO code
- getEmail()
- getPrice() - decimal in major currency units
- getPriceInteger() - integer in minor currency units
- getBalance() - decimal in major currency units
- getBalanceInteger() - integer in minor currency units
- getReceivable() - decimal in major currency units
- getReceivableInteger() - integer in minor currency units
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
- https://github.com/fjbender/simple-php-integration
A write-up showing how the PAYONE integration works. Some great background information. - https://github.com/ekalinin/github-markdown-toc
Tool to generate the Table of Contents in this README.