Download the PHP package academe/omnipay-adyen without Composer
On this page you can find all versions of the php package academe/omnipay-adyen. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package omnipay-adyen
Omnipay: Adyen
Adyen driver (HPP, CSE, Online Payments and API integration) for the Omnipay PHP payment processing library
Omnipay 3.x is a framework agnostic, multi-gateway payment processing library for PHP 5.6+.
Table of Contents
- Omnipay: Adyen
- Table of Contents
- Installation
- General
- Hosted Payment Pages (HPP)
- Server Fetches Payment Methods
- Client Fetches Payment Methods
- HPP Authorises a Payment
- Prepare for Redirect
- Complete Transaction on Return
- Capture the Authorisation
- Client Side Encryption (CSE)
- Building a Form for Encrypting
- An Encrypted Card Authorises a Payment
- 3D Secure Response
- Online Payments (Checkout)
- Drop-In
- Building the drop-in
- Payment Methods Request
- Tokenize a card
- Create a Card
- Authorize a Payment
- Prepare for authorize redirect
- Complete on Return
- Drop-In
- Notifications
- Notification Server Request (from gateway)
- Notification Response (to gateway)
- Support
Installation
Omnipay is installed via Composer.
General
This omnipay integration for adyen provides multiple APIs.
Adyen provides the newest API implementations as "Online Payments"
"Online Payments" supports:
- Pay by Link
- Drop-in
- Components
- API-Only
- iOS
- Android
Deprecated by adyen but still implemented:
- Hosted Payment Pages (HPP)
- Client Side Encryption (CSE)
Hosted Payment Pages (HPP)
!!! deprecated !!!
This method hosts the payment pages on the gateway, and the user is sent to those pages on the gateway to make a payment.
A number of payment methods are supported, and they will vary depending on the location of the merchant site (known here as local payment methods). The list may change also depending on the amount being paid and the currency being used, as well as the country of the merchant site and the end user.
Options for choosing the payment method include:
- Merchant site gets list of what is available and presents them to the end user to choose from. This may be filtered if required.
- The merchant site server chooses one payment method and the end user is taken directory to that one choice.
- The front end fetches the options and offers the user a choice.
Server Fetches Payment Methods
This gives you an array of PaymentMethod
objects:
The raw payment methods, as associatively indexed arrays, can be fetched too. These include logos in a variety of sizes.
Some payment methods will also have a list of issuers
that may also be
used to refine the options offered to the end user.
At this time, there are no further parsing of this data into objects
by this driver.
Client Fetches Payment Methods
Use the same method as the previous section (Server Fetches Payment Methods)
but do not send()
the request.
Instead, get its data and endpoint for use by the client:
POST
the $data
to the $endpoint
to get the JSON response.
Remember this data is signed, so parameters cannot be changed at
the client side.
Some client-side JavaScipt will likely be needed to send an AJAX
POST request to $endpoint
with $data
as the Form payload.
HPP Authorises a Payment
Prepare for Redirect
The gateway object is instantiated first, as before.
The CreditCard
class is used to supply any billing details.
Shipping detais are not supported at this time, but may be later.
The request sets up the redirect:
Now there are a few additional parameters that need some explanation.
The paymentMethod
can be used to redirect the user to a specific payment method,
without asking the user to choose from the available payment methods:
$request->setPaymentMethod('visa');
$request->setIssuer('optional issuer ID for the brandCode');
Specifying the paymentMethod
will skip any pages asking the user how they
want to pay, and take the user direct to that payment method.
An alternative way to limit the payment methods that are offered to the user,
is to use the allowedMethods
and blockedMethods
lists.
$request->setAllowedMethod(['visa', 'diner']); // Only Visa and Diner cards.
$request->setBlockesMethod(['visa']); // All types except Visa.
Setting addressHidden
to true
will hide the address being submitted to
the payment gateway.
The user will not see their address, but what you submit will be stored at
the gateway.
By defauit, the address is shown to the user.
$request->setAddressHidden(true);
Setting addressLocked
will prevent the user from changing their address
details on the gateway.
Although all these details are sent to the gateway in the redirect, they are
signed, so any attempt by the user to change them will result in a rejection.
$request->setAddressLocked(true);
Additional parameters will be supported in the future.
Now "send" the request to get the redirection response.
$response = $request->send();
The redirect will be a POST
.
The details to include are in $response->getRedirectData()
and $response->getRedirectUrl()
,
so you can build a form to post or auto-post, either to the top page
or to an iframe. Or you can just issue echo $response->redirect()
as a rough-and-ready
redirection.
The user will be redirected to the Adyen hosted page,
will enter their authorisation details on that page,
then will be returned to the returnUrl
.
This is where the transaction is completed (see next section).
Complete Transaction on Return
The user will be returned with the result of the authorisation as query parameters. These are read and parsed like this:
$response = $gateway->completeAuthorize()->send();
From the $response
you can get the result, the transactionReference
(if the result is successful) and the raw data.
The data is signed, and if the signature is invalid then an exception will
be thrown during the send()
operation.
To get further details about the authorisation, the transaction will need to
be fetched from the gateway using the API.
This result just gives you the overall result, and returns your transactionId
so you can confirm it is the result of the transaction you are expecting
(it is vital to check the transactionId
) so URLs from pevious authorisations
cannot be injected by an end user.
Capture the Authorisation
The HPP reqeust will only authorise a payment. It still needs to be captured. Auto-capture can be turned on in the account control panel, but it will be off by default. It can also be turned on with a delay, so can auto-capture after a set number of days.
Programatically requesting a capture of the payment is done like this:
The response you get back will return isSuccessful() === true
if the request to capture was accepted.
Note however that this is just a request to the gateway.
The result of the capture will be returned via the notificaton
channel, so at this point you do not know whether the capture will
be successful.
Once it is captured, it can be refunded in total or in part using
the $gateway->refund([...])
message, taking the same paramers as
capture
.
Before the authorisation is captured, the authorisation can be
cancelled completely using $gateway->void([...])
.
The void
message does not need an amount
, as it aims to void
the entire authorisation.
Like for capture
, both void
and refund
are just pending results,
with the final result being supplied by a notification
.
Client Side Encryption (CSE)
!!! deprecated !!!
The Adyen gateway allows a credit card form to be used directly in your application page. The credit card details are not directly submitted to your merchant site, but are encrypted at the client (browser), and the encrypted string is then submitted to your site, along with any additional details.
The encrpyted details are then used in place of credit card details when making an authorisation request to the API, server-to-server.
Building a Form for Encrypting
The client-side fuctionality can be completely built by hand, but the following minimal example shows how this library can help build it. The laravel blade view syntax is used in the example.
Other application-specific fields can be added to the form as needed. You may also operate this form using AJAX to prevent a full page refresh. The Adyen CSE documentation provides more details on this.
The Pay
button will not be enabled until the credit card fields are completed and valid.
The JavaScript library included in the header will then encrypt the card details and
add the result to the hidden POST
field adyen-encrypted-data
by default.
You can specify an alternative field name through the options.
This field must be accepted by the https://example.com/payment-handler
page
(defined as the returnUrl
) for the next step.
An Encrypted Card Authorises a Payment
This is the server-side handling. Once the CSE form has been POSTed to your client site, the encrypted card details will be available. It can be used to submit an authorisation like this:
If isSuccessful()
is true, then the transaction is complete and ends here.
If isSuccessful()
is not true, and isRedirect()
is true, then the user
has to be redirected to the bank for 3D Secure authorisation.
The redirectData()
you are given will generally include PaReq
, MD
and
TermUrl
.
3D Secure Response
On return from the 3D Secure authorisation, you will need to fetch the
results from the gateway, as that is where they will be held.
The completeAuthorize()
method does this, by sending the data it finds
in the POST
data of the current request.
The $response
will be the final response, as you would get without
the additional 3D Secure step if it was not enabled or available.
Online Payments (Checkout)
The recommended adyen method is the Checkout API. It supports a Drop-in which dynamically offers payment methods based on the transaction details. Also you can use "Pay by Link", single "Components", "API only".
Drop-in
The most powerful and recommended solutions is using the Drop-in. It dynamically shows all available payment methods to the user and returns a javascript state array onSubmit() with the paymentMethod details to use for later payments. 3D Secure 2 required information are also provided by the drop-in. Please refer to the Adyen Documentation for more information.
Building the drop-in
Payment Methods Request
To get all necessary data to pass to the Drop-in, you can use the paymentMethods()-function of the Checkout gateway.
The shopperReference
is required, if you want to show stored payment details to your customer.
Tokenize a card
You can tokenize card credentials for later use. Card encryption is used by default, if using the drop-in or components. As of today, only card creation is possible in this implementation. Feel free to add a PR.
Create a Card
Authorize a Payment
Authorize is Omnipay default behavior. Please take a look at the documentation for required fields for 3DS.
Prepare for authorize redirect
In some cases you have to redirect the user to another website. Those websites will redirect the user back to your returnUrl. The Authorize Request won't be successful in such cases. But isRedirect() would be true.
Be careful with self-made redirects. Some providers are redirected with a POST-Request with additional Data. Better use getRedirectResponse() then.
Complete on Return
Cause we don't know all information we need to parse the response of the payment type, we have to provide some things.
Notifications
The Adyen APIs are by nature asynchronous. Just about every event can generate a notification to your application. By default, no notifications are sent, but they can be set up in the administration pages.
Notification Server Request (from gateway)
For security, the notifications can use Basic Auth to access your pages, and a signature based on some key fields provides confirmation that those fields have not been changed en-route.
Notifications can be sent as SOAP, JSON or Form POST messages. This driver supports both JSON and Form POST.
The notification request is captured at the notifications endpoint like this:
Note that the notifications HMAC key is not the same as the HPP HMAC key. The HMAC check is optional, but if you supply the key here, then the driver will throw an exception if none is supplied by the API.
You may wish to implement Basic Auth through your framework, perhaps in routing middleware, rather than in this package. It just depends on how far through your application pipeline you would like a failing Basic Auth request to go. That will determine where the details can be logged.
The $request
will supply a wealth of information regarding the notification,
examples of which include:
Notification Response (to gateway)
The gateway will follow an algorithm to retry sending notifications
at increasing intervals, until it gets an acceptance response.
The expected response will vary, depending on what content type the original
notification used.
The http response code must be 200, unless either the signature check or
Basic Auth checks fail.
The Content-Type
header is assumed to be set appropriately.
The response body payload for a Form
notification must be the text:
[accepted]
This is shown in the documenation
as follows, which is wrong (&5B
vs %5D
? What content type is this?)
but worth noting in case this documentation needs tweaking:
&5Baccepted%5D
The response body payload for a JSON
notification must be the JSON data:
{"notificationResponse":"[accepted]"}
This driver does not handle the response at this time, so will need to be coded into the merchant site. The merchant site must accept the notification, so it is recommended the message is queued for offline processing so that the notification endpoint can respond as quickly as possible.
- TODO: programatically implement the response to the gateway.
- TODO: test whether the response must match the request content type,
or whether it just needs to be consistent with the response
Content-Type
header.
Support
If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.
If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.