Instant Payment Notification (IPN) provides you with immediate updates about changes to the status of payments. You can then take your chosen action on a purchase such as activating service or providing the account holder with the order status.
Adyen
Supported Features
- Instant Payment Notification (IPN)
- Level 2 customer data (affluence indicator) and Level 3 data (invoice line item data)
- Account Updater
- Apple Pay Method Support
- Support for Adyen Fraud Tools, RevenueProtect+
- Payment Methods (Please note that Qiwi and Yandex are unavailable until further notice.)
- 3D Secure authentication (manual or dynamic)
- Refund Responses
- Cardholder Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT) for Visa, Mastercard, and Discover credit cards
- Soft Descriptors
- Transaction Reference IDs (Failed Transactions)
- Card Verification Value (CVV)/ Address Verification Service (AVS) Configuration
- Authorization Reversals ($0/ $1)
- Direct Debit Recurring Payments (Phase 2)
Instant Payment Notification
Level 2 and 3 Data
When applicable, Aria will send Level 2 and 3 data to Adyen, resulting in savings on transaction fees. "Level 2" data refers to customer-specific affluence indicators, and "Level 3" data is specific to invoice line items. We will pass level 2 and 3 data for the following payment methods:
- Credit Card (pay_method=1)
- Visa (cc_id= 1)
- MasterCard (cc_id=2)
- Tokenized credit card (pay_method=13)
Once received, Adyen will filter and or reformat the data as necessary to confirm eligibility. Adyen does not allow more than 9 line items of Level 3 data to pass at one time. Aria has limited the maximum line item to 9 to avoid collection errors from Adyen.
Account Updater
The Adyen account updater proactively sends information to Aria from Visa and Mastercard which will automatically update card information and decrease the possibility of card declines. Currently Adyen only supports this feature for Visa and MasterCard.
The updater has been enhanced to support both credit card (pay method = 1) and tokenized credit card (pay method = 13) transactions.
This includes the following status enhancements:
| Record Status | Pay Method = 1 | Pay Method = 13 |
|---|---|---|
| CardExpiryChanged | To update new expiration month and year | To update new expiration month and year |
|
PANChanged (Primary Account Number) |
No change – Customer needs to provide the new card info in Aria |
|
Email Template Updates
A new Email template class has been introduced (message class C3) called "Credit Card Update Required." This notifies the account holder that their account number has changed and no longer matches the credit card on file.
For more information on Email template classes, please click here.
Four replacement strings have been added under the Billing category to be used with the Credit Card Update Required Email template. They are as follows:
- insertPaymentMethodNo – This is used to print the sequence number of the account’s payment method.
- insertClientPaymentMethodId – This is used to print the Client Defined Payment Method ID for the sequence number of the account’s payment method.
- insertPaymentMethodName – This is the means of making the payment (Credit Card, Tokenized Credit Card, Direct Debit, Net Terms, etc.).
- insertPaymentMethodDescription – This is the description of the payment method name that provides further detail on the terms of payment (Payments to be processed with NETS, Accounts have 15 days to pay balance before entering dunning, etc.).
For more information on creating Email templates, please click here.
Event Notification Updates
Two events have been added in support of the Adyen Account Updater (under the Account and Master Plan Instance Notifications class). They are:
| Event Name | Description |
|---|---|
| Account Message Type “Credit Card Update Required” Requires Sending | System determination that account message type “Credit Card Update Required” requires sending. |
| Message Type “Credit Card Update Required” Sent to Account Holder | Account message type “Credit Card Update Required” was sent to account holder. |
To view events in the Account and Master Plan Instance Notifications class, please click here.
Note: The Credit Card Update Required Email template (message class C3) and two events noted above will only be used for the Adyen account updater.
Generating the Refresh Token
The refresh_token_from_pmt_processor_m API call is used to get the updated suffix, expiry_mm and expiry_yyyy (using existing token) from Adyen when the PAN changes for the Tokenized Credit Card (for Pay Method = 13 at the <payment_method_no> or <client_payment_method_id> input fields).
Apple Pay Method Support
Adyen now supports Apple payment methods for recurring payments, including the Apple Pay payment method (38) and the new Tokenized Apple Pay payment method (47). When an Apple Pay indirect payment takes place outside of Aria, the payment is recorded using the record_alternative_payment_m API. Once the external payment is recorded, Aria performs a capture request and receives the respective notification (a more detailed process flow appears below).
You must enter the following input values using the record_alternative_payment_m API to enable this feature:
| Input | Description |
|---|---|
| <acct_no> | The Aria account number. |
| <reference_code> (proc_payment_id) | Adyen's pspReference of the external Apple Pay authorization response. |
| <payment_amount> | The amount authorized in the Apple Pay authorization. |
| <processor_id> | 34 (Adyen processor ID). |
| <pay_method> |
|
| <statement_no> | The Aria account statement number. |
| <payment_auth_received> | 1 (indicates that the Apple Pay payment is authorized). |
| <proc_payment_method_id> | The shopperReference input used in the Apple Pay authorization created outside of Aria (it is recommended that you use the Aria account number in the shopperReferece to Adyen). |
To utilize the Apple Pay and Tokenized Apple Pay payment methods within your Aria integration, you must follow these steps:
- Perform an Apple Pay authorization only outside of Aria (using a unique shopperReference that should be communicated to Aria using the <proc_payment_method_id> noted above) and record this payment against your Aria account number using the record_alternative_payment_m API. Aria will then perform a payment capture against the provided pspReference (from Adyen’s authorization response).
- When Aria receives the capture Webhook notification, the payment transaction is moved from the authorization stage to the payment approved stage; it is created in Aria and applied against the <statement_no> provided in the record_alternative_payment_m API.
- Once the Apple Pay payment is recorded, Aria queries the token details from Adyen using the shopperReference provided in the <proc_payment_method> input field, which is associated with the initial Apple Pay payment. A new billing info sequence for the Tokenized Apple Pay payment method will be created in Aria using the token details. For subsequent/recurring transactions, use the Tokenized Apple Pay payment method.
Note: You must configure Webhook notification in your Adyen payment portal for Aria to receive Adyen’s asynchronous notification, update the proper/final status capture request, and create an Aria payment transaction.
Support for Adyen Fraud Tools, Revenue Protect+
Aria supports Adyen's RevenueProtect+, a fraud protection mechanism. The API validate_acct_fraud_scoring_m now sends fraud-related customer data to Adyen's customizable rules engine to return more granular fraud scoring for payment transactions.
After you have configured the Adyen Payment Gateway in Aria, a “FraudScoring Options” section appears on the Processing Options Tab (see image below).
Details on the fraud options are as follows:
- Send Fraud Scoring Request: When set to true, Aria sends a request to Adyen to return fraud scoring information. If the fraud score returned is below the Fraud Scoring Threshold or the Fraud Score response is "Not Successful," Aria modifies the status based on "Change Status on Fraud Scoring Failure" setting. "Send Fraud Scoring Request" must be set to "True" to enable the "Change Status on Fraud Scoring Review" menu.
- Change Status on Fraud Scoring Review: When set to true, Aria changes the status of the Master Plan Instance(s) to the value selected on the "Status on Fraud Scoring Review" drop-down menu, and the Fraud Score response is "Review." "Change Status on Fraud Scoring Review" must be set to "True" to enable the "Status on Fraud Scoring Review" drop-down menu.
- Status on Fraud Scoring Review: This parameter governs the behavior for changing the status when Fraud Scoring is enabled and Change Status on Fraud Scoring Review is set to "True."
Payment Methods
The following payment methods are accepted with the Adyen/Aria integration:
| Traditional Payment Methods | Cards | Alternate Payment Methods |
|---|---|---|
| Credit/Debit Card | Visa | Giropay |
| Tokenized Card | MasterCard | Tokenized Direct Debit |
| ACH (Electronic Check) | American Express | Klarna |
| Direct Debit | Discover | Tokenized Klarna |
| SEPA (Single Euro Payments Area) | Diner Club/Carte Blanche | Qiwi |
| JCB (Japan Credit Bureau) | Tokenized Qiwi | |
| UnionPay Express Pay | Yandex | |
| iDeal (Netherlands) | ||
| Boleto Bancario (Brazil) | ||
| SOFORT |
Notes:
- Recurring payments are supported for all of the above APMs (alternate payment methods) except for Yandex.
- Refund transactions are supported for all APMs.
Methods
When using SOFORT, Aria will convert it to SEPA Direct Debit since it cannot be used for recurring payments. After the payment is processed in Aria, SOFORT will be listed as the “Source” for the payment on the Payments tab. (Accounts > search for the account > Payments & Credits > Payments). Within record_alternative_payment_m the <pay_method_type> should be 36 for SOFORT.
Alternate Payment Methods
All alternate payment methods above offer both refund and recurring support with the exception of Yandex which does not allow recurring support. The <allow_recurring> API needs to be “true” within the record_alternative_payment_m call to set recurring payments. The flow the alternate payments is listed below:
Step 1: Client will perform a Giropay/Klarna/Qiwi payment outside of Aria (using a unique shopper Reference that should be communicated to Aria via <proc_payment_method_id> input) and record this payment against an Aria account within the record_alternative_payment_m API.
Step 2: Once the Giropay/Klarna/Qiwi payment is recorded, Aria will query the bank/token details from Adyen using the unique shopper reference (<proc_payment_method_id>) and new billing information sequence for Tokenized Direct Debit/Tokenized Klarna/Tokenized Qiwi payment method will be created along with the bank/token details.
Step 3: Aria will capture the relation between the Giropay/Klarna/Qiwi billing information record and the Tokenized Direct Debit/Tokenized Klarna/Tokenized record.
Step 4: For subsequent payments, the new billing information sequence should be used (created in step 2)
3D Secure Authentication Support for Adyen Payment Gateway
Aria supports 3D Secure authentication for payment transactions processed through the Adyen Payment Gateway. When calling APIs authorize_electronic_payment_m, validate_acct_fraud_scoring_m, or update_payment_method_m Aria parses the results to support either Manual or Dynamic 3D Secure authentication.
Note: If you enable Adyen’s Dynamic 3DS service, you must configure it in Adyen’s configuration portal. 3DS configuration is not possible in the Aria UI.
For Manual 3D Secure you will need to manually initiate the 3D Secure using the parameter <attempt_3d_secure>. The possible values for this parameter are:
- True – 3D Secure is initiated.
- False – 3D Secure is skipped.
- Null or Empty – It will check the configured rule, if any (Dynamic 3D Secure).
3D Secure via APIs (should be PCI Level 1 compliant)
Step 1: For credit card payments call the existing API authorize_electronic_payment_m , or validate_acct_fraud_scoring_m, with parameters listed below along with attempt_3d_secure as true:
- alt_pay_method (enter “1” to use an alternate card than what is stored)
- cc_number
- cc_expire_mm
- cc_expire_yyyy
- end_user_browser_accept_header
- end_user_browser_agent
The update_payment_method_m call will allow you to change the payment method within the <pay_method_type> parameter. The flow for tokenized credit cards is listed below:
- pay_method_type = 13
- bill_agreement_id (this is where the token should be placed)
- end_user_browser_accept_header
- end_user_browser_agent
The output of this API will return <proc_payer_auth_request>, <proc_redirect_issuer_url> and <proc_md>.
Step 2: Using the API response details, create a redirect HTML form to direct the user to issuer’s 3D Secure authentication site URL to enter authentication information (username and password). See image below:
Step 3: Aria will receive the authentication response from the issuer once they submit the form. We parse the response to extract the value that is needed to create and send a second request to Adyen. In this step API authorize_3dsecure_m is used to pass <proc_payer_auth_request>, <proc_md> and <end_user_ip_address> This API call will return the status of 3D Secure Authentication.
3D Secure via Direct Post
Since Adyen provides the payment session identifier that is used by the card issuer, Aria made use of that session ID instead of Aria’s USS session ID. To accommodate this, the <set_session_m> API accepts an input of <client_session_id> which will be stored against the Aria session that the API creates.
The <get_reg_uss_params_m> will use the <client_session_id> to lookup the session parameters. When allowing credit cards via direct post, ensure the credit card check box is selected under the direct post configuration (Configuration > client settings > USS Reg configuration) and the option for “save card as token” is set to true for tokenized cards.
The direct post 3D Secure flow is listed below:
Step 1: Make a direct post call with an input of “true” in the <attempt_3d_secure> parameter. The highlighted fields below along with the card details (card number, expiration date, and security code) need data prior to submitting the request.
*Please note that this is a raw sample (demonstration) file but you would be expected to develop something similar to this page (with your own look and feel / branding).
The user will need to enter their username and password and then click Submit.
Refund Responses
Aria supports the following Adyen Notifications for eligible payment methods:
- Authorization
- Capture
- Cancellation
- Capture Failed
- Refund
- Refund Failed
Cardholder Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT) Support for Visa, MasterCard, and Discover
This feature sends flags distinguishing cardholder initiated transactions (CIT) and merchant initiated transactions (MIT) within the <recurring_processing_model_ind> parameter of the following API calls:
- assign_acct_plan_m
- authorize_electronic_payment_m
- cancel_acct_plan_m
- collect_from_account_m
- create_acct_billing_group_m
- create_acct_complete_m
- create_order_m
- create_order_with_plan_m
- manage_pending_invoice_m
- replace_acct_plan_m
- settle_account_balance_m
- update_acct_billing_group_m
- update_acct_complete_m
- update_acct_plan_m
- update_acct_plan_multi_m
- update_payment_method_m
- validate_acct_fraud_scoring_m
This feature is applicable for both credit cards (Visa, MasterCard and Discover) and tokenized credit cards.
The input values for the <recurring_processing_model_ind> are the following:
- 0: Cardholder-Initiated Transaction—Credentials on File: a credit card transaction initiated by the cardholder for a new order or a plan upgrade that uses a credit card that is currently stored in Aria. (Default)
- 1: Cardholder-Initiated Transaction—a credit card transaction initiated by the cardholder for a new account or creating an order that uses an alternate credit card that is not currently stored in Aria.
- 2: Merchant-Initiated Transaction—Standing Instruction – Recurring: a credit card transaction initiated by Aria’s clients for a recurring charge that uses a credit card that is currently stored in Aria.
- 3: Merchant-Initiated Transaction—Unscheduled Credentials on File: a credit card transaction initiated by Aria’s clients for a non-recurring charge (one-time order or plan upgrade) that uses a credit card that is currently stored in Aria.
The output field of this call is <proc_initial_auth_txn_id>. For Visa and Mastercard, Adyen is passing the networkTxReference that Aria will capture and pass for subsequent MIT transactions. At this time, Adyen is not passing this value for Discover cards.
Soft Descriptors
Aria will pass the <soft_descriptor> parameter (item description) to Adyen in applicable API calls. The following API calls will include this parameter:
- authorize_electronic_payment_m
- collect_from_account_m
- create_order_m
- create_order_with_plan_m
- issue_refund_to_acct_m
- settle_account_balance_m
Aria will truncate soft descriptor values that exceed the following character limits:
- Visa Cards – 25 characters
- MasterCard – 22 characters
- Other cards – 135 characters
Transaction Reference IDs (Failed Transactions)
Aria will parse unique transaction reference IDs returned from Adyen in the <proc_payment_id> parameter for declined transactions. Transactions include but are not limited to the following:
- Payments
- Authorizations
- Captures
- Voids
- Reverses
- Refunds
- Balance Inquires
If no reference ID is returned from Adyen, Aria returns a NULL value for <proc_payment_id>. The following API calls include the <proc_payment_id> output parameter:
- create_acct_complete_m
- update_acct_complete_m
- create_order_with_plan_m
- create_order_m
- assign_acct_plan_m
- replace_acct_plan_m
- update_acct_plan_m
- update_acct_plan_multi_m
- settle_account_balance_m
- collect_from_account_m
- authorize_electronic_payment_m
- validate_payment_information_m
- validate_acct_fraud_scoring_m
- gen_rb_m
- manage_pending_invoice_m
Card Verification Value (CVV)/ Address Verification Service (AVS) Configuration
With the Adyen integration, error codes can be returned by Aria for a specific Card Verification Value (CVV) response. This configuration lies within the collection groups and payment gateways tab in the UI (Configuration > Payments > Collection Groups):
The integration with Adyen also offers Address Verification Service responses. This configuration is also within the collection groups and payment gateways tab of the UI. See image below for possible configuration options:
Authorization Reversals ($0/ $1)
When authorizing a card, Aria provides the option to authorize a $0 or $1 transaction on the card to ensure the card is in good standing prior to offering a service to the account. The system override settings listed in the image below are to reverse the authorizations on the card after the verifications. The settings can be enabled for all or specific card types. This configuration in the UI is at the collection group level.
Direct Debit Recurring Payments (Phase 2)
With Phase 2 of Aria’s Adyen integration, ACH (US), BACS (UK), and SEPA Direct Debit payments are now supported. You can use the Adyen shopper reference to make recurring tokenized payments (pay method 37 for BACS/SEPA and pay method 48 for ACH). The iDEAL payment method is now also supported with Adyen smart payments as an alternative payment method when an initial iDEAL payment takes place outside of Aria.
Additional information appears in the following table:
| Payment Type | Details | Recurring Payment Method |
|---|---|---|
| ACH Direct Debit Recurring Payments (US) |
|
37 |
| BACS Direct Debit Recurring Payments (UK) |
|
48 |
| SEPA Direct Debit Recurring Payments (EU) |
|
37 |
| Note: Only SALE flow is supported where Direct Debit payments happen automatically for ACH, BACS, and SEPA. | ||
| iDEAL (Netherlands) |
|
*32 (Initial payment outside Aria) |
| Note: Refund flow is supported for both iDEAL payments and tokenized SEPA payments. | ||
Soft descriptors have also been introduced as part of the Adyen Phase 2 integration. These are used by merchants to provide more detailed transaction information. The soft descriptor can be set and passed through various levels, prioritized as follows:
- API
- Collection Group
- Payment Gateway
This is included with the Phase 2 Adyen integration for the following supported card types:
- American Express
- China Union Pay (CUP)
- Diners
- Discover
- Japan Credit Bureau (JCB)
- Mastercard
- VISA
Note: The soft descriptor field character count maximum is 22 for all supported card types. If both the Collection Group and Payment Gateway settings are populated, the Collection Group setting takes precedence.
Also, the IBAN and BBAN number displays at the Payment Methods screen for these payments through Adyen (Account > [search for an account] > Account Overview > Payment Methods > Payment Details)
Learn more about Adyen's Smart Payments integration with Aria from here.Aria Configuration Fields
- Adyen Merchant Account: Name that identifies the client to the Adyen server. This name/value is provided by your Adyen support representative.
- Adyen User ID: User name for authenticating requests sent to the Adyen server or to log in to the Adyen Customer Area.
- Adyen Password: Password for authenticating requests sent to the Adyen server or to log in to the Adyen Customer Area.
- API URL: The client URL where API calls are directed. If you want to use 3D Secure (3DS) authentication 2.0, set this field to v49. Please contact your payment gateway representative for more information.
- Notification URL: The client URL where notifications are directed.
- Notification User ID: User name for HTTP authentications that the client receives.
- Notification Password: Password for HTTP authentications that the client receives.
- Notification HMAC: Hash-based Message Authentication Codes (HMAC) can be used as an extra layer of security for data verification and message authentication for notifications. To enable HMAC signing of the Adyen notifications for additional security, use the following steps:
- Log in to the Adyen Customer Area (CA) and navigate to Settings > Server Communication.
- For standard notification, click Edit & Test.
- Expand Additional Settings.
- Click Generate New HMAC Key, and copy the key into the Notification HMAC field in Aria to use it for your server configuration.
- Payer Authentication Settings: If you want to use 3DS 2.0, complete any fields under Payer Authentication Settings. Please contact your payment gateway representative for more information.
Configuration Notes
- The capture delay in the Adyen environment should be set to “Manual.”
- Use the Adyen Customer Area for chargeback dispute management.
- For reconciliation, we recommend building notifications capability to accept Adyen settlement reports.
Links
- Adyen Customer Area: Log in to your Adyen merchant account.
- Developer Resources: Documentation of test cards, payment modifications, notifications, live endpoints, libraries, API idempotency, currency codes, refusal reasons, payments with pending status, and response handling.