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.

List of payment data items¶

Key	Adyen Form Field	Description	Required
`order_number`	`merchantReference`	Order Number	Yes
`client_id`	`shopperReference`	Customer’s identifier	Yes
`client_email`	`shopperEmail`	Customer’s email	Yes
`currency_code`	`currencyCode`	Currency code	Yes
`amount`	`paymentAmount`	Payment amount (in cent)	Yes
`shopper_locale`	`shopperLocale`	Customer’s locale	Yes
`country_code`	`countryCode`	Merchant’s Country	Yes
`source_type`	`allowedMethods`	Selected `SourceType` object	No
`return_url`	`resURL`	Custom Payment Return URL	No
`shipping_address`	`deliveryAddress.*`	Customer shipping address	No
`shipping_visibility`	`deliveryAddressType`	Visibility of the address	No
`billing_address`	`billingAddress.*`	Customer billing address	No
`billing_visibility`	`billingAddressType`	Visibility of the address	No

Both shipping_address and billing_address are expected to be standard shipping and billing Django-Oscar address objects.

The shipping_visibility and billing_visibility take the values defined in the Adyen documentation: 1 for visible but not editable and 2 for not visible. By default, 2 is used by the plugin.

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_SIGNER_BACKEND¶

The Signer backend class as a python path. The signer will be responsible for computing hash for signatures used in the payment request form, and to verify the payment return URL’s result.

By default adyen.signers.HMACSha1 is used, which implement the SHA-1 legacy signature for Adyen.

New in version 0.7.0.

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_signer_backend(request)¶

Get the signer backend class as a python path.

Parameters:	request – Django HTTP request object.
Returns:	The python path to the signer backend class to use.
Return type:	str

The signer object will be used to sign payment request form and to verify Adyen payment result fields and/or notifications.

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:

handle_payment_return() to handle payment return data,
handle_payment_notification() to handle payment standard notifications.

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

OPTIONAL_FIELDS = ()¶

REQUIRED_FIELDS = ()¶

check_fields()¶: Validate required and optional fields for both requests and responses.

validate()¶

class adyen.gateway.BaseResponse(client, params)¶

Bases: adyen.gateway.BaseInteraction

process()¶

class adyen.gateway.Gateway(settings=None)¶

Bases: object

MANDATORY_SETTINGS = ('identifier', 'secret_key', 'action_url', 'signer')¶

build_payment_form_fields(params)¶

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

Bases: adyen.gateway.BaseInteraction

OPTIONAL_FIELDS = ('merchantSig', 'skinCode', 'recurringContract', 'allowedMethods', 'blockedMethods', 'shopperStatement', 'shopperLocale', 'countryCode', 'resURL', 'merchantReturnData', 'offset', 'deliveryAddressSig', 'deliveryAddressType', 'deliveryAddress.street', 'deliveryAddress.houseNumberOrName', 'deliveryAddress.city', 'deliveryAddress.postalCode', 'deliveryAddress.stateOrProvince', 'deliveryAddress.country', 'billingAddressSig', 'billingAddressType', 'billingAddress.street', 'billingAddress.houseNumberOrName', 'billingAddress.city', 'billingAddress.postalCode', 'billingAddress.stateOrProvince', 'billingAddress.country', 'shopperEmail', 'shopperLocale', 'shopperReference', 'shopperStatement', 'shopperSig', 'shopperType', 'shopper.firstName', 'shopper.infix', 'shopper.lastName', 'shopper.gender', 'shopper.dateOfBirthDayOfMonth', 'shopper.dateOfBirthMonth', 'shopper.dateOfBirthYear', 'shopper.telephoneNumber')¶

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.

OPTIONAL_FIELDS = ('merchantReturnData', 'paymentMethod', 'pspReference')¶

REQUIRED_FIELDS = ('authResult', 'merchantReference', 'merchantSig', 'shopperLocale', 'skinCode')¶

process()¶

validate()¶

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:

get_form_action() and get_form_fields to build the Adyen HPP request submission form,
handle_payment_return() to handle customer coming back from the Adyen HPP after a payment (successful or not)
assess_notification_relevance(), handle_payment_notification() and build_notification_response() to handle Adyen Payment Notification.

ADYEN_TO_COMMON_PAYMENT_STATUSES = {'REFUSED': 'REFUSED', 'CANCELLED': 'CANCELLED', 'PENDING': 'PENDING', 'ERROR': 'ERROR', 'AUTHORISED': 'ACCEPTED'}¶: 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:

Be processed, ie. is a call to handle_payment() is relevant,
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_fields_billing(request, order_data)¶

Extract and return billing related fields from order_data.

Parameters:	request – Django HTTP request object. order_data (dict) – Order’s data.
Returns:	A dict of payment’s billing fields.

get_fields_delivery(request, order_data)¶

Extract and return delivery related fields from order_data.

Parameters:	request – Django HTTP request object. order_data (dict) – Order’s data.
Returns:	A dict of payment’s delivery fields.

get_fields_shopper(request, order_data)¶

Extract and return shopper related fields from order_data.

Parameters:	request – Django HTTP request object. order_data (dict) – Order’s data.
Returns:	The Adyen specific shopper’s fields.

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.scaffold.sanitize_field(value)¶

Clean field used in the payment request form

Parameters:	value (string) –
Returns:	A sanitized value

Adyen suggest to remove all new-line, so we do.

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_signer_backend(request)¶: Return ADYEN_SIGNER_BACKEND or adyen.signers.HMACSha1

get_skin_code(request)¶: Return ADYEN_SKIN_CODE.

get_skin_secret(request)¶: Return ADYEN_SECRET_KEY.

adyen.signers module¶

Signers are helpers to sign and verify Adyen requests & responses.

There are currently 2 type of signatures:

SHA-1, deprecated by Adyen but still used,
SHA-2 (256), preferred by Adyen.

Each signer follows different rules to sign payment request form, and to verify Adyen return response and Adyen notification.

Note

About the signature:

The data passed, in the form fields, is concatenated into a string, referred to as the “signing string”. The HMAC signature is then computed over using a key that is specified in the Adyen Skin settings (stored into the AbstractSigner.secret key).

The signature is passed along with the form data and once Adyen receives it they use the key to verify that the data has not been tampered with in transit.

The signing string should be packed into a binary format containing hex characters, and then base64-encoded for transmission.

class adyen.signers.AbstractSigner(secret_key)¶

Bases: object

Abstract base class that define the common interface.

A signer must expose three methods:

sign(): take form fields and return a dict of signature fields.
verify(): take a dict of fields and make sure there have an

appropriate signature field.
compute_hash(): take a signature string and compute its hash value.

These methods are not implementd by the AbstractSigner, therefore subclasses must implement them.

compute_hash(signature)¶

Return a hash for the given signature string.

Parameters:	signature (str) – A `signature` used to compute hash.
Returns:	A hashed version of the `signature` using the `secret_key` and the defined hash algorithm.

Each implementation should simply use a different hash algorithm to sign the signature string. This method is not supposed to know how the signature string is built.

secret_key = None¶

Adyen Skin secret key

This secret key is used to sign payment request, and verify payment return response and payment notification.

sign(fields)¶

Sign the given form fields and return the signature fields.

Parameters:	fields (dict) – The form fields used to perform a payment request
Returns:	A dict of signature fields
Return type:	`dict`

A payment request form must contains specific signature fields, depending on the selected sign method.

verify(fields)¶

Verify fields contains the appropriate signatures.

Parameters:	fields (dict) – A dict of fields, given by a payment return response or by a payment notification.
Returns:	`True` the `fields` contain valid signatures
Return type:	`boolean`

Adyen can secure communication with merchant site using signatures:

merchantSig for the return URL,
additionalData.hmacSignature for notification,

And this method can be used for both, provided with all the fields as a flat dict.

The following example is taken from the Adyen documentation:

{
   "live":"false",
   "notificationItems": [
      {
         "notificationRequestItem": {
            "additionalData": {
               "hmacSignature":"SIGN_KEY"
            },
            "amount": {
               "value":1130,
               "currency":"EUR"
            },
            "pspReference":"7914073381342284",
            # ... other fields
         }
      }
   ]
}

The expected fields will be:

{
    'additionalData.hmacSignature': 'SIGN_KEY',
    'amount.value': 1130,
    'amount.currency': 'EUR',
    'pspReference: "7914073381342284"
    # ... other fields
}

This format correspond to the POST notification format.

class adyen.signers.HMACSha1(secret_key)¶

Bases: adyen.signers.AbstractSigner

Implement a HMAC signature with SHA-1 algorithm.

See also

The Adyen documentation about SHA-1 deprecated method for a general explanation. The delivery, billing and shopper signatures are explained in the Open Invoice documentation.

PAYMENT_BILLING_HASH_KEYS = ('billingAddress.street', 'billingAddress.houseNumberOrName', 'billingAddress.city', 'billingAddress.postalCode', 'billingAddress.stateOrProvince', 'billingAddress.country')¶: List of fields to sign billing address in payment request form.

PAYMENT_DELIVERY_HASH_KEYS = ('deliveryAddress.street', 'deliveryAddress.houseNumberOrName', 'deliveryAddress.city', 'deliveryAddress.postalCode', 'deliveryAddress.stateOrProvince', 'deliveryAddress.country')¶: List of fields to sign delivery address in payment request form.

PAYMENT_FORM_HASH_KEYS = ('paymentAmount', 'currencyCode', 'shipBeforeDate', 'merchantReference', 'skinCode', 'merchantAccount', 'sessionValidity', 'shopperEmail', 'shopperReference', 'recurringContract', 'allowedMethods', 'blockedMethods', 'shopperStatement', 'merchantReturnData', 'billingAddressType', 'deliveryAddressType', 'shopperType', 'offset')¶

List of fields to sign payment request form.

This is used to build the merchantSig signature. Note that the order of the fields matter to compute the hash with the SHA-1 algorithm.

PAYMENT_RETURN_HASH_KEYS = ('authResult', 'pspReference', 'merchantReference', 'skinCode', 'merchantReturnData')¶

List of fields used verify payment result on return URL.

These fields are given to tye payment return URL by Adyen. It is used to validate that the payment return URL has a valid merchantSig field.

PAYMENT_SHOPPER_HASH_KEYS = ('shopper.firstName', 'shopper.infix', 'shopper.lastName', 'shopper.gender', 'shopper.dateOfBirthDayOfMonth', 'shopper.dateOfBirthMonth', 'shopper.dateOfBirthYear', 'shopper.telephoneNumber')¶: List of fields to sign shopper data in payment request form.

compute_hash(signature)¶: Compute hash using the hashlib.sha1 algorithm.

See also

The AbstractSigner.compute_hash() method for usage.

sign(fields)¶: Sign the given form fields and return the signature fields.

See also

The AbstractSigner.sign() method for usage.

verify(fields)¶: Verify fields contains the appropriate signatures.

Warning

This version validate only the merchantSig signature, given to the payment return URL. Other signature fields are ignored (in particular for notification signature).

See also

The AbstractSigner.verify() method for usage.

class adyen.signers.HMACSha256(secret_key)¶

Bases: adyen.signers.AbstractSigner

Implement a HMAC signature with SHA-256 algorithm.

See also

The Adyen documentation about SHA-256 deprecated method for more information about the signature.

build_signature(fields)¶

Build the signature string used to generate a signed key.

The signature format is a specific concatenation of keys and values takenf from fields:

We sort by key the valid keys (see is_valid_key()),
Both keys and values are escaped (see signature_escape()),
Then keys are joined by :; same for the values,
And these two strings are joined by anoter :.

There is no such thing as a hard-coded defined order of keys: if a key is present, then it is used to sign the fields. This is much more simple than the signing mechanism using the SHA-1 algorithm.

compute_hash(signature)¶: Compute hash using the hashlib.sha256 algorithm.

See also

The AbstractSigner.compute_hash() method for usage.

sign(fields)¶: Sign the given form fields and return the signature fields.

See also

The AbstractSigner.sign() method for usage.

verify(fields)¶: Verify fields contains the appropriate signatures.

Warning

This version validate only the merchantSig signature, given to the payment return URL. Other signature fields are ignored (in particular for notification signature).

See also

The AbstractSigner.verify() method for usage.

adyen.signers.is_valid_key(key)¶: Return if a key can be used in the SHA-256 signature.

adyen.signers.signature_escape(value)¶

Escape field as required by Adyen.

See the Adyen documentation about using SHA-256 signature.

Welcome to Django Oscar Adyen’s documentation!¶

Usage¶

Basics¶

Payment form¶

List of payment data items¶

Handle payment return¶

Register payment notification¶

Configure¶

Settings-based configuration¶

Class-based configuration¶

Extend¶

adyen package¶

Submodules¶

adyen.admin module¶

adyen.config module¶

adyen.facade module¶

adyen.gateway module¶

adyen.models module¶

adyen.scaffold module¶

adyen.settings_config module¶

adyen.signers module¶

Module contents¶

Indices and tables¶