Welcome to Django Oscar Adyen’s documentation!

Contents:

Usage

Basics

The main entry point into the plugin is the adyen.scaffold.Scaffold class:

>>> from adyen.scaffold import Scaffold
>>> scaffold = Scaffold()

Of course, one can use Oscar’s get_class function instead:

>>> from oscar.core.loading import get_class
>>> Scaffold = get_class('adyen.scaffold', 'Scaffold')
>>> sclaffold = Scaffold()

Scaffold should be the only class used in your application, and you can consider it as the public interface of the plugin.

Payment form

The first step in the Adyen HPP workflow is to generate the form that will be submitted from your e-commerce site to the Adyen HPP. This form must contain several fields as described in the Adyen HPP Documentation.

You can get both from the scaffold:

>>> sclaffold = Scaffold()
>>> form_action_url = scaffold.get_form_action(request)
>>> form_fields = scaffold.get_form_fields(request, payment_data)

This should be used in the last view of your checkout before the payment return view - for example, in get_context_data to add the form URL and form fields.

See also

You can check the docstring of adyen.scaffold.Scaffold.get_form_action() and adyen.scaffold.Scaffold.get_form_fields() for more information.

Handle payment return

When customers authorise a payment through the Adyen HPP, they are redirected back to your e-commerce site with a payment status that can be used to record the transaction (successful or not).

As usual, everything is handled with the scaffold:

>>> sclaffold = Scaffold()
>>> result = sclaffold.handle_payment_return(request)
>>> success, status, details = result

This can be done in the payment return view, to determine what to display to the customer: a thank-you or sorry page, depending on the value of success for example.

If you didn’t place the order yet, it should be the right place to do it - if not the last possible one.

In any case, it’s up to you to decide if you want to handle the payment here or if you want to wait for the payment notification.

See also

You can check the docstring of adyen.scaffold.Scaffold.handle_payment_return() for more information.

Register payment notification

Eventually Adyen will send to your Payment Notification URL a POST request to notify your application of a transaction. Since you may already have recorded the transaction, you need to assess the relevance of the notification, and then handle it.

The same way you handled payment return, you can handle payment notification:

>>> sclaffold = Scaffold()
>>> result = sclaffold.handle_payment_notification(request)
>>> success, status, details = result

With Adyen Payment Notification, your application must expose an URL accessible through a POST request. This view is the right place to call this method, but it is up to you to decide if you want to handle the payment here, modify the order, or ignore it if already done in the payment return view.

See also

You can check the docstring of adyen.scaffold.Scaffold.handle_payment_notification() for more information.

Configure

You have two approaches to configure django-oscar-adyen.

Settings-based configuration

For simple deployments, setting the required values in the settings will suffice.

Edit your settings.py to set the following settings:

ADYEN_IDENTIFIER

Your Adyen Account’s identifier.

ADYEN_SKIN_CODE

Your Adyen Skin’s code.

ADYEN_SECRET_KEY

Your Adyen Skin’s secret key.

ADYEN_ACTION_URL

The URL towards which the Adyen form should be POSTed to initiate the payment process. (e.g. https://test.adyen.com/hpp/select.shtml).

ADYEN_IP_ADDRESS_HTTP_HEADER

Optional. The header in META to inspect to determine the IP address of the request. Defaults to REMOTE_ADDR.

ADYEN_ALLOWED_METHODS

Optional. If provided, it must be a tuple of available payment methods as defined in the Adyen interface. If not defined, customers will select a payment method on the HPP without restriction.

New in version 0.6.0.

You will likely need to specify different settings in your test environment as opposed to your production environment.

Class-based configuration

In more complex deployments, you will want to e.g. alter the Adyen identifier based on the request (country, language, users, etc.). That is not easily implemented with Django settings, so you can alternatively set ADYEN_CONFIG_CLASS to a config class of your own:

ADYEN_CONFIG_CLASS

Optional. Define the class used to instantiate the Adyen config. If defined this settings must be the import path of the class as a string, for example adyen.settings_config.FromSettingsConfig.

Internaly, this plugin uses FromSettingsConfig to handle the configuration. Plugin users can extends this class for their needs and set the ADYEN_CONFIG_CLASS settings to use it.

Extend

Extending Django Oscar Adyen is not documented yet.

If you want to contribute to the project, please feel free to open an issue on our Github project.

adyen package

Submodules

adyen.admin module

adyen.config module

class adyen.config.AbstractAdyenConfig

Bases: object

Abstract class for an Adyen config class.

Plugin users that want to create their own Adyen config class must comply with this interface.

get_action_url(request)

Get Adyen HPP URL to post payment request form to.

Parameters:request – Django HTTP request object.
Returns:Adyen HPP URL.
get_allowed_methods(request, source_type=None)

Get customers’s list of allowed Adyen payment methods.

Parameters:request – Django HTTP request object.
Returns:List (or tuple) of allowed payment methods.

New in version 0.6.0: Make sure to implement this method when using this new version.

get_identifier(request)

Get Adyen merchant identifier.

Parameters:request – Django HTTP request object.
Returns:Adyen merchant identifier as string.
get_ip_address_header()

Get the request HTTP header used to get customer’s IP.

Returns:appropriate request HTTP header.
get_skin_code(request)

Get Adyen merchant skin code.

Parameters:request – Django HTTP request object.
Returns:Adyen merchant skin code.
get_skin_secret(request)

Get Adyen merchant skin secret key.

Parameters:request – Django HTTP request object.
Returns:Adyen merchant skin secret key.
adyen.config.get_config()

Returns an instance of the configured config class.

Returns:Project’s defined Adyen configuration.
Return type:AbstractAdyenConfig

By default, this function will return an instance of adyen.settings_config.FromSettingsConfig. If ADYEN_CONFIG_CLASS is defined, it will try to load this class and return an instance of this class instead.

Note

This function expects ADYEN_CONFIG_CLASS to be a string that represent the python import path of the Adyen config class, such as adyen.settings_config.FromSettingsConfig.

adyen.facade module

class adyen.facade.Facade

Bases: object

Facade used to expose the public behavior of the Adyen gateway.

The Facade class exposes a set of public methods to be used by the plugin internally and by plugin users without having to deal with Adyen internal mecanism (such as how to sign a request form or how to read a payment response).

The first entry point is the payment form:

  • build_payment_form_fields() to handle payment data and generate the payment request form used to submit a payment request to Adyen HPP.

Then payment processing entry points of the Facade are:

These methods will build an appropriate Adyen Payment Response object and call the process_payment_feedback() method to handle the payment feedback.

assess_notification_relevance(request)

Return a (must_process, must_acknowledge) tuple to decide what should be done with this request.

build_notification_response(request)

Return the appropriate response to send to the Adyen servers to acknowledge a transaction notification.

Quoting the Adyen Integration Manual (page 26):

“The Adyen notification system requires a response within 30 seconds of receipt of the notification, the server is expecting a response of [accepted], including the brackets. When our systems receive this response all notifications contained in the message are marked as successfully sent.”

build_payment_form_fields(request, params)

Return a dict containing the name and value of all the hidden fields necessary to build the form that will be POSTed to Adyen.

build_payment_notification(request)

Build a Payment Notification response object from raw request.

Parameters:request – Django HTTP request object
Returns:A PaymentNotification object

This method get the gateway for the request and config and instantiate a PaymentNotification with this gateway and the request.POST parameters.

Plugin users may want to override this method to build any user-made object to handle their own specific cases.

build_payment_return(request)

Build a Payment Return response object from raw request.

Parameters:request – Django HTTP request object
Returns:A PaymentRedirection object

This method get the gateway for the request and config and instantiate a PaymentRedirection with this gateway and the request.GET parameters.

Plugin users may want to override this method to build any user-made object to handle their own specific cases.

handle_payment_feedback(request)

Handle payment feedback (payment return or payment notification).

Deprecated since version 0.6.0: This method is not used internally anymore by the plugin. If you rely on that please switch to handle_payment_return(), handle_payment_notification(), and process_payment_feedback().

handle_payment_notification(request)

Handle payment notification.

Parameters:request – Django HTTP request (POST)

This method should be called when Adyen send its Payment Notification (through a POST request). It instantiate the gateway and the appropriate response object and pass it to process_payment_feedback() to return a result.

handle_payment_return(request)

Handle payment return.

Parameters:request – Django HTTP request (GET)

This method should be called when customers come back from the Adyen HPP (through a GET request). It instantiate the gateway and the appropriate response object and pass it to process_payment_feedback() to return a result.

process_payment_feedback(request, response)

Process payment feedback response.

Parameters:
  • request – Django HTTP request object
  • response – Adyen payment response

Validate, process, optionally record audit trail and provide feedback about the current payment response.

unpack_details(details)

Unpack detailed information from response.process()

Parameters:details (dict) – Dict that contains data from an Adyen notification or when customer come back through the return URL.
Returns:A dict with transaction details.

See also

unpack_details_amount() can be overridden to extract the transaction amount. Note that this plugin decided to use a field for this purpose.

unpack_merchant_return_data() can be overridden to extract specific data from merchantReturnData. This method is called after any others and can be used to override the initial unpacked details.

unpack_details_amount(details)

Unpack amount from the Adyen response details.

Parameters:details (dict) – Dict that contains data from an Adyen notification or when customer come back through the return URL.
Returns:None if amount is not available or an integer.

The payment amount is transmitted by the notification in the value field. However, in the case of a payment return URL, we do not have this parameter.

We decided in Scaffold.get_field_merchant_return_data to provide the order’s amount into this field, but this is not standard. As developers may want to override this behavior, they can extend both part in order to modify only the behavior of the field merchantReturnData, and they can override this method to fetch amount in their own way.

unpack_merchant_return_data(details)

Unpack merchant return data fields from the details.

Parameters:details (dict) – Dict that contains data from an Adyen notification or when customer come back through the return URL.
Returns:A dict of extra details to unpack that handle custom fields.

The return dict is supposed to contain the merchant_return_data, which is by default the raw content of the field merchantReturnData.

Developers may want to override the meaning of this field and extract various other information.

Note

The result of this method will override any existing key extracted in unpack_details(). It is powerful yet it could be dangerous if not handled with care.

adyen.facade.get_gateway(request, config)

Instantiate a adyen.gateway.Gateway from config.

Parameters:
  • request – Django HTTP request object.
  • config (AbstractAdyenConfig) – Adyen Config object.
Returns:

An instance of Gateway configured properly.

The Gateway is built using the given config and request to get specific values for identifier, secret_key and action_url.

The configuration object requires the request in order to allow plugin user to define a per-request configuration, such as a different secret key based on the country or the language (or even the type of customer, its IP address, or other request specific parameter).

adyen.gateway module

class adyen.gateway.BaseInteraction

Bases: object

HASH_FIELD = None
HASH_KEYS = ()
OPTIONAL_FIELDS = ()
REQUIRED_FIELDS = ()
check_fields()

Validate required and optional fields for both requests and responses.

hash()
validate()
class adyen.gateway.BaseResponse(client, params)

Bases: adyen.gateway.BaseInteraction

process()
class adyen.gateway.Constants

Bases: object

ACCEPTED_NOTIFICATION = '[accepted]'
ACTION_URL = 'action_url'
ADDITIONAL_DATA_PREFIX = 'additionalData.'
ADYEN = 'adyen'
ALLOWED_METHODS = 'allowedMethods'
AUTH_RESULT = 'authResult'
BILLING_ADDRESS_TYPE = 'billingAddressType'
BLOCKED_METHODS = 'blockedMethods'
COUNTRY_CODE = 'countryCode'
CURRENCY = 'currency'
CURRENCY_CODE = 'currencyCode'
DELIVERY_ADDRESS_TYPE = 'deliveryAddressType'
EVENT_CODE = 'eventCode'
EVENT_CODE_AUTHORISATION = 'AUTHORISATION'
EVENT_DATE = 'eventDate'
FALSE = 'false'
IDENTIFIER = 'identifier'
LIVE = 'live'
MERCHANT_ACCOUNT = 'merchantAccount'
MERCHANT_ACCOUNT_CODE = 'merchantAccountCode'
MERCHANT_REFERENCE = 'merchantReference'
MERCHANT_RETURN_DATA = 'merchantReturnData'
MERCHANT_RETURN_URL = 'resURL'
MERCHANT_SIG = 'merchantSig'
OFFSET = 'offset'
OPERATIONS = 'operations'
ORIGINAL_REFERENCE = 'originalReference'
PAYMENT_AMOUNT = 'paymentAmount'
PAYMENT_METHOD = 'paymentMethod'
PAYMENT_RESULT_AUTHORISED = 'AUTHORISED'
PAYMENT_RESULT_CANCELLED = 'CANCELLED'
PAYMENT_RESULT_ERROR = 'ERROR'
PAYMENT_RESULT_PENDING = 'PENDING'
PAYMENT_RESULT_REFUSED = 'REFUSED'
PSP_REFERENCE = 'pspReference'
REASON = 'reason'
RECURRING_CONTRACT = 'recurringContract'
SECRET_KEY = 'secret_key'
SEPARATOR = ':'
SESSION_VALIDITY = 'sessionValidity'
SHIP_BEFORE_DATE = 'shipBeforeDate'
SHOPPER_EMAIL = 'shopperEmail'
SHOPPER_LOCALE = 'shopperLocale'
SHOPPER_REFERENCE = 'shopperReference'
SHOPPER_STATEMENT = 'shopperStatement'
SHOPPER_TYPE = 'shopperType'
SKIN_CODE = 'skinCode'
SUCCESS = 'success'
TEST = 'test'
TEST_REFERENCE_PREFIX = 'test_AUTHORISATION'
TRUE = 'true'
VALUE = 'value'
class adyen.gateway.Gateway(settings=None)

Bases: object

MANDATORY_SETTINGS = ('identifier', 'secret_key', 'action_url')
build_payment_form_fields(params)
exception adyen.gateway.InvalidTransactionException

Bases: ValueError

exception adyen.gateway.MissingFieldException

Bases: ValueError

exception adyen.gateway.MissingParameterException

Bases: ValueError

class adyen.gateway.PaymentFormRequest(client, params=None)

Bases: adyen.gateway.BaseInteraction

HASH_FIELD = 'merchantSig'
HASH_KEYS = ('paymentAmount', 'currencyCode', 'shipBeforeDate', 'merchantReference', 'skinCode', 'merchantAccount', 'sessionValidity', 'shopperEmail', 'shopperReference', 'recurringContract', 'allowedMethods', 'blockedMethods', 'shopperStatement', 'merchantReturnData', 'billingAddressType', 'deliveryAddressType', 'shopperType', 'offset')
OPTIONAL_FIELDS = ('merchantSig', 'skinCode', 'recurringContract', 'allowedMethods', 'blockedMethods', 'shopperStatement', 'shopperLocale', 'countryCode', 'resURL', 'merchantReturnData', 'billingAddressType', 'deliveryAddressType', 'shopperType', 'offset')
REQUIRED_FIELDS = ('merchantAccount', 'merchantReference', 'shopperReference', 'shopperEmail', 'currencyCode', 'paymentAmount', 'sessionValidity', 'shipBeforeDate')
build_form_fields()
class adyen.gateway.PaymentNotification(client, params)

Bases: adyen.gateway.BaseResponse

Process payment notifications (HTTPS POST from Adyen to our servers).

Payment notifications can have multiple fields. They fall into four categories:

  • required: Must be included.
  • optional: Can be included.
  • additional data: Can be included. Format is ‘additionalData.VALUE’ and we don’t need the data at the moment, so it’s ignored.
  • unexpected: We loudly complain.
OPTIONAL_FIELDS = ('operations', 'originalReference')
REQUIRED_FIELDS = ('currency', 'eventCode', 'eventDate', 'live', 'merchantAccountCode', 'merchantReference', 'paymentMethod', 'pspReference', 'reason', 'success', 'value')
check_fields()

Delete unneeded additional data before validating.

Adyen’s payment notification can come with additional data. It can mostly be turned on and off in the notifications settings, but some bits always seem to be delivered with the new “System communication” setup (instead of the old “notifications” tab in the settings). We currently don’t need any of that data, so we just drop it before validating the notification. :return:

process()
class adyen.gateway.PaymentRedirection(client, params)

Bases: adyen.gateway.BaseResponse

Process payment feedback from the user

When they paid on Adyen and get redirected back to our site. HTTP GET from user’s browser.

HASH_FIELD = 'merchantSig'
HASH_KEYS = ('authResult', 'pspReference', 'merchantReference', 'skinCode', 'merchantReturnData')
OPTIONAL_FIELDS = ('merchantReturnData', 'paymentMethod', 'pspReference')
REQUIRED_FIELDS = ('authResult', 'merchantReference', 'merchantSig', 'shopperLocale', 'skinCode')
process()
validate()
exception adyen.gateway.UnexpectedFieldException

Bases: ValueError

adyen.models module

class adyen.models.AdyenTransaction(id, order_number, reference, method, status, amount, currency, ip_address, date_created)

Bases: django.db.models.base.Model

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception AdyenTransaction.MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

AdyenTransaction.accepted
AdyenTransaction.cancelled
AdyenTransaction.declined
AdyenTransaction.get_next_by_date_created(*moreargs, **morekwargs)
AdyenTransaction.get_previous_by_date_created(*moreargs, **morekwargs)
AdyenTransaction.objects = <django.db.models.manager.Manager object>

adyen.scaffold module

class adyen.scaffold.Scaffold

Bases: object

Entry point to handle Adyen HPP.

The Scaffold exposes an interface that can be used in any Django Oscar application. It aims to hide the inner complexity of payment form management and payment notification processing.

The key methods are:

ADYEN_TO_COMMON_PAYMENT_STATUSES = {'REFUSED': 'REFUSED', 'AUTHORISED': 'ACCEPTED', 'ERROR': 'ERROR', 'CANCELLED': 'CANCELLED', 'PENDING': 'PENDING'}

This is the mapping between Adyen-specific and these standard statuses

PAYMENT_STATUS_ACCEPTED = 'ACCEPTED'
PAYMENT_STATUS_CANCELLED = 'CANCELLED'
PAYMENT_STATUS_ERROR = 'ERROR'
PAYMENT_STATUS_PENDING = 'PENDING'
PAYMENT_STATUS_REFUSED = 'REFUSED'
assess_notification_relevance(request)

Assess if a notification request is relevant.

Parameters:request – Django HTTP request object.
Returns:A 2-value tuple as must_process and must_acknowledge

One should call this method when receiving a notification request and they want to know if the notification must:

  1. Be processed, ie. is a call to handle_payment() is relevant,
  2. Be acknowledged with a response to Adyen, using build_notification_response()

New in version 0.6.0: This method has been added to replace the generic handle_payment_feedback().

build_notification_response(request)

Build a notification response for an Adyen Payment Notification

Parameters:request – Django HTTP request object.
Returns:A Django HTTP Response object.

From the Adyen Integration Manual:

The Adyen notification system requires a response within 30 seconds of receipt of the notification, the server is expecting a response of [accepted], including the brackets. When our systems receive this response all notifications contained in the message are marked as successfully sent.”

This method simply call the adyen.facade.Facade.build_notification_response() method and returns its result.

get_field_allowed_methods(request, order_data)

Get a string of comma separated allowed payment methods.

Parameters:
  • request – Django HTTP request object.
  • order_data (dict) – Order’s data.
Returns:

If defined by the configuration, a string composed of a list of comma separated payment methods (ex. card,bankTransfert). Otherwise None.

This methods is used to populate the allowedMethods field of the payment request form. See Adyen HPP manual for more information.

If a source_type is available into the provided order_data, then it is used as a parameter to adyen.config.AbstractAdyenConfig.get_allowed_methods().

New in version 0.6.0: Added to handle allowedMethods field. May require extra work on the configuration object to work properly.

get_field_merchant_return_data(request, order_data)
get_field_return_url(request, order_data)
get_field_specs(request, order_data)
get_form_action(request)

Return the URL where the payment form should be submitted.

get_form_fields(request, order_data)

Return the payment form fields as a list of dicts. Expects a large-ish order_data dictionary with details of the order.

handle_payment_feedback(request)

Handle payment feedback from return URL or POST notification.

Parameters:request – Django HTTP request object.
Returns:A normalized payment feedback.

If the request.method is POST, this method consider we handle an Adyen Payment Notification. Otherwise it considers it is a simple Payment Return case.

See also

handle_payment_notification() and handle_payment_return() to see how to handle both cases.

Deprecated since version 0.6.0: This method is deprecated in favor of more specific methods and should not be used in plugin user’s code anymore.

handle_payment_notification(request)

Handle payment notification.

Parameters:request – Django HTTP request object
Returns:A 3-values tuple with success, status and details.

One should call this method when handling the POST request that come as an Adyen Payment Notification.

New in version 0.6.0: This method has been added to replace the generic handle_payment_feedback().

handle_payment_return(request)

Handle payment return.

Parameters:request – Django HTTP request object
Returns:A 3-values tuple with success, status and details.

One should call this method when handling the GET request that come after a redirection from Adyen.

New in version 0.6.0: This method has been added to replace the generic handle_payment_feedback().

adyen.settings_config module

class adyen.settings_config.FromSettingsConfig

Bases: adyen.config.AbstractAdyenConfig

Manage Plugin’s configuration from the project’s settings.

It gets all information required by the plugin from the project’s settings, and can be used as a base class for specific cases.

The expected settings are:

get_action_url(request)

Return ADYEN_ACTION_URL.

get_allowed_methods(request, source_type=None)

Return ADYEN_ALLOWED_METHODS or None.

Parameters:
  • request – Django HTTP request object.
  • source_type – A SourceType object or None.

If the setting is not configured, the default value None is returned instead. It means the application does not specify any allowed methods so customers can select a payment methods on the Adyen HPP itself.

Note that both request and source_type parameters are ignored and only the setting matters.

get_identifier(request)

Return ADYEN_IDENTIFIER.

get_ip_address_header()

Return ADYEN_IP_ADDRESS_HTTP_HEADER or REMOTE_ADDR.

If the setting is not configured, the default value REMOTE_ADDR is returned instead.

get_skin_code(request)

Return ADYEN_SKIN_CODE.

get_skin_secret(request)

Return ADYEN_SECRET_KEY.

Module contents

Indices and tables