Skip to main content
Aria Knowledge Central

Worldline (formerly Ingenico)

Worldline_0802.png

Supported Features

ACH via Direct Debit

Worldline now supports the ACH (Automated Clearing House-Electronic Check) payment type and refund transactions through the Direct Debit payment method. Adding ACH as a payment option via Direct Debit provides another method to manage subscriptions and recurring payments in a timely and secure manner. It allows customers to pay for transactions by debiting directly from their bank account, as opposed to processing through a card brand.

To add Direct Debit with ACH as a payment method on an account, select Direct Debit as the payment type and enter the bank account details along with these two new fields:

  • Bank Name
  • Bank City

The Bank Name and Bank City fields added have been added at the following locations in the Aria UI:

Account > select an account > Account Overview > Payment Methods (New and Edit)

Fields appear when adding a new payment method (for Direct Debit).

Accounts > select an account > Plans > Add New Plan > Plans tab

Fields appear when adding a Primary or Backup/Secondary Pay Method Type (for Direct Debit).

Accounts > select an account > Plans > Billing Groups (New and Edit option)

Fields appear when adding a Payment Method or Secondary Payment Method (Create New Payment Method, for Direct Debit Payment Type).

Accounts > select an account > Payments and Credits > Apply a Payment

Select Alternate One-Time at the Account Level Payment Method drop-down list and select Direct Debit at the Alternate Billing Type drop-down list.

For this enhancement, two fields have been added as API inputs:

Field Description
<bank_name> Bank name for the account payment method
<bank_city> Bank city for the account payment method

To process an ACH payment via Direct Debit, call any of the APIs below and pass the following information:

Field Value
<pay_method_type> 26 for Direct Debit
<bank_name> Bank name for the account payment method
<bank_city> Bank city for the account payment method
<bank_country_cd> Must be US

The Bank Name and Bank City input fields added in support of ACH payments via Direct Debit have been added to the following APIs:

These input fields have been added to the following APIs:

Also, the "Used in Europe" Text has been removed for the <bank_branch_cd> and <bank_id_cd> input fields for these APIs.

The <bank_name> and <bank_city> fields have been also been added as outputs to the get_acct_payment_method_and_terms_m API.

The Bank Identifier Code (<bank_id_cd>) will pass the routing number value and use the Basic Bank Account Number (BBAN) (<bank_acct_num>) to pass the account number to do the ACH payment via Direct Debit. The Bank Identifier Code field is also now validated for length and character format for the Direct Debit payment method only when the Bank Country (the two-character <bank_country_cd>) is passed as US (ACH payments via Direct Debit are only supported for US banks at this time).

The Bank Swift Code (<bank_swift_cd>) input field (with validation on the length and character format) is now used in support of the Direct Debit payment method. It is required for the International Bank Account Number (IBAN).

API Endpoints

Worldline has updated its API end point for both pre-production and production environments, as shown: Pre-Production: api.preprod.connect.worldline-solutions.com/Production: api.connect.worldline-solutions.com (both endpoints starting with https://).To enter the updated endpoint, go to Configuration > Payments > Payment Gateways > Processor/Gateway Details > API Base URL.

Level 2/Level 3 Enhancements

This feature adds Level 2 and 3 data processing support to the Worldline payment gateway. Level 2 data are included for determining a card's affluence, which may influence your marketing initiatives, and Level 3 data includes invoice line item details that allow you to receive lower transactional fees from credit card processors. Level 2 and Level 3 data are supported by the Credit Card and Tokenized Credit Card payment methods and the Visa® and Mastercard® card types.

Note: Aria sends Level 2 and 3 data to Worldline only when making a single API call to collect a payment. Level 2/3 data cannot be sent to Worldline when payment collection is made with 2 separate API calls (e.g., using authorize_electronic_payment_m to authorize a $3 payment and collect_from_account_m to capture the $3 authorized amount).

3DS Support for American Express Card Type

The Worldline 3D Secure integration now supports transactions using the American Express® (Amex) card in addition to the Visa® and Mastercard® card types.

The existing Amex credit card type is now supported in Worldline's 3DS configuration for the following APIs:

Enter the following inputs to enable this feature:

authorize_3dsecure_m

Input Description
<cc_prefix> First six digits of Amex card (starting with 3)

authorize_electronic_payment_m

Input Description
<cc_number> Amex card number (starting with 3 - 15-character numeric value)
<attempt_3d_secure> True

update_payment_method_m

Input Description
<cc_number> Amex card number (starting with 3 - 15-character numeric value)

UI Configuration Fields

The Worldline integration requires the following fields be configured in the UI:

Getting here: Click Configuration > Payments > Payment Gateways > New
clipboard_e85d5e87e8b595348f98c6126503ec64d.png

Getting here: Add or edit a payment gateway and/or collection group.

The field descriptors are the following:

  • API Key ID: Worldline-provided identifier for the secret API key. The apiKeyId can be retrieved from the Worldline Configuration Center and is also used to identify the correct Worldline account.
  • Secret API Key: Worldline-provided shared secret API Key that can be retrieved from the Worldline Configuration Center. The apiKeyId and secretApiKey always are used together, the difference is that secretApiKey is never visible in API calls to/from Worldline.
  • API Base URL: Worldline-distinct Server API endpoint that points to one of the Worldline environments (sandbox, pre-production, or production). You must include the https:// as part of the URL.
  • Merchant ID: Worldline-provided code that identifies the client.
  • WX File SFTP Host: Worldline-provided hostname for receiving WX Files via SFTP.
  • WX File SFTP Username: Worldline-provided username needed to receive WX Files via SFTP.
  • WX File SFTP Password: Worldline-provided password for receiving WX Files via SFTP.

Payment Methods

The following pay methods and card types are supported by Worldline:

Traditional Payment Methods Cards Alternate Payment Methods
Credit Card Visa iDEAL (Netherlands)
Tokenized Credit Card MasterCard Boleto Bancario (Brazil)
Tokenized Direct Debit American Express Web Money
  Discover SOFORT
  Diners Club/ Carte Blanche Yandex
  International Maestro PaySafeCard
  JCB Giropay
  ELO Qiwi
  Hipercard  

Tokenized SEPA (Single Euro Payments Area) Direct Debit

When paying by Tokenized SEPA Direct Debit, the account holder must sign a paper mandate before this method can be used. The mandate must be signed in advance of using this payment method and therefore it is not available as a payment method for one-time orders. Payments can only be made with Tokenized SEPA Direct Debit after the mandate has been approved with the record_mandate_approval_m call. It is your responsibility to ensure the end user signs the paper mandate. Once the electronic mandate is submitted and approved, neither Aria nor Worldline will be able to intervene if the end user disputes signing the paper mandate.

If the payment status is returned to Aria as pending_approval you must approve the payment on the Worldline website after a mandate is signed. You will not be able to approve the mandate and resubmit the payment using the Aria UI since Worldline does not currently provide an update capability via APIs.

To add Tokenized SEPA Direct Debit as a payment method on an account click accounts > search for accounts > plans (left panel) > plan instance ID > Edit billing group.

There are two options for selection after making your primary payment method Tokenized Direct Debit.

  • Token/Agreement ID - used if there is an approved token associated with a signed mandate
  • Direct Debit - used to generate a new token by entering the International Bank Account Number
    Ingenico_Payment_Options_B_0430.jpg

ELO, Hipercard and Maestro Credit Cards

These three credit cards are acceptable payment methods with the Worldline integration. When making a payment with either of these cards the input in the <pay_method_type> parameter should be one of the following:

  • 1 — credit card
  • 13 — Tokenized credit card

Giropay and Qiwi

Giropay and Qiwi are two alternate payment methods that can support refund transactions. There is currently no recurring payment support from Worldline for either alternate payment methods. Both methods are supported within the record_alternative_payment_m call. The <proc_payment_method_id> parameter should have one of the following as an input when using either payment method:

  • 41 — Giropay
  • 44 — Qiwi

Cardholder Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT) 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:

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 is <proc_initial_auth_txn_id>. This feature is available for Visa, MasterCard, and Discover.

Soft Descriptor

The <soft_descriptor> input supports the Visa subscription regulations update. This supports "authorization" and "payment" actions for the following card types: Visa, MasterCard, American Express, and Japan Credit Bureau (JCB).

The soft descriptor configuration allows for a transaction description to be shown on the buyer’s credit card statement. This field allows for a Merchant Name or Item Description of a specified length when paying by credit card (25 characters for Visa, American Express and JCB and 23 for MasterCard). This field is normally passed via the API; however, it can be set in the UI at the payment gateway or collection group level.

The following APIs contain the <soft_descriptor> field:

The soft_descriptor field can be configured in the UI as shown:

Configuration > Payments > Payment Gateways > Field Options:
Ingenico_UI_SD_0506a.jpg

Configuration > Payments > Collection Groups > Advanced Options:
Ingenico_UI_SD_0506b.jpg

Note: If the soft_descriptor value is blank when running an API listed in this section, then the value configured in either of the Aria UI dialogs will be used (the Collection Group value takes precedence over the Payment Gateway value).

Transaction Reference IDs

Aria will parse unique transaction reference IDs returned from Worldline in the <proc_payment_id> parameter for declined transactions. Transactions include but are not limited to the following:

  • Payments
  • Authorizations
  • Captures
  • Voices
  • Reverses
  • Refunds
  • Balance Inquires

If no reference ID is returned from Worldline, Aria returns a NULL value for <proc_payment_id>. The following API calls include the <proc_payment_id> output parameter:

** - The <soft_descriptor> input to the create_order_m API supports the Visa subscription regulations update. This supports "authorization" and "payment" actions for the following card types: Visa, MasterCard, American Express, and Japan Credit Bureau (JCB).

$0 Authorization / Authorization Reversal

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 accepted with this integration. This configuration in the UI is at the Collection Group level (Configuration > Payments > Collection Groups).
Ingenico_AAR_B_0430.jpg

Card Verification Value (CVV)/ Address Verification Service (AVS) Configuration

With the Worldline 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).
Ingenico_CVV_B_0430.jpg

The integration with Worldline also offers Address Verification Service responses. This configuration is also within the Collection Groups and Payment Gateways tab of the UI (Configuration > Payments). See image below for possible configuration options:
Ingenico_AVS_Sys_OR_B_0430.jpg

Account Updater

The Aria Worldline integration is now enhanced by the addition of the Account Updater, which automatically updates your account holders’ card information (Tokenized cards only). This feature supports Visa® and Mastercard® card types issued in the U.S. and Canada.

When an account holder's card information is updated (associated with the particular token), Worldline provides the "push" notification via the Webhooks tool, which sends real-time data from one application to another based on system events as part of a larger integration. You must configure an endpoint that will act as a "listener" to receive these notifications. A typical URL as part of a listener configuration is as follows:

Worldline/Ingenico AU listenter: https://secure.<environment>.ariasystems.net/api/update_payment_method.php/client_no/<client_no>

Note: Please contact your payment gateway representative for more information on configuring your Worldline listener endpoint.

On the Worldline configuration center, once Webhooks is enabled, you can subscribe to the token.updated and token.deleted events supported by the Account Updater.

Aria now supports the Webhook Key and Webhook Secret configuration fields from Worldline that are used to validate the incoming Webhooks notifications. These fields accept alphanumerics and special characters.

Note: Set these two field values on the Worldline configuration center for your merchant account. After doing so, configure those values in your Worldline payment gateway configuration.

These fields appear at the Payment Gateway (Configuration > Payments > Payment Gateways) for Worldline as shown:
WL_Ingenico_MA_Details_3_0215.png

These fields also appear at the Collection Group Configuration > Payments > Collection Groups) for Worldline (same view as the Worldline Payment Gateway configuration).

Notes:

  • The Collection Group configuration takes precedence over the Payment Gateway configuration.
  • The Webhook Key and Webhook Secret values are honored in the Worldline Payment Gateway configuration only and not the Collection Group configuration at this time.
  • The values for the existing Secret API Key field and the new Webhook Secret fields are hashed for security reasons.

Refund ID Mapping

Refund transactions generated from Aria now appear on the Worldline payment portal (the Aria refund payment ID appears in the Worldline Merchant Reference ID field). Previously, only original payments were supported and not payment refunds. Refunds can be generated for any payment method accepted by Worldline (e.g., credit card, tokenized credit card, Giropay, etc.).

Learn more about refunds from here.

Batch Support

The Worldline batch process has been enhanced with the following features:

  • Converting a payment authorization to a payment record
  • Voiding a payment (which increases the account balance)
  • Reinstating a failed payment to treat a payment as a success
  • Reverse-reinstating the previously reinstated payment

Aria Configuration Fields

  • API Key ID: Identifier for the secret API key. The apiKeyId can be retrieved from the Worldline Configuration Center and is also used to identify the correct Worldline account.
  • Secret API Key: Shared secret API Key that can be retrieved from the Worldline Configuration Center. The apiKeyId and secretApiKey always are used together, the difference is that secretApiKey is never visible in API calls to/from Worldline.
  • API Base URL: Worldline-distinct Server API endpoint that points to one of the Worldline environments (sandbox, pre-production, or production). You must include the https:// as part of the URL. For example, api.preprod.connect.worldline-solutions.com is the Worldline Pre-production endpoint, and api.connect.worldline-solutions.com is the Worldline Production endpoint (both endpoints starting with https://).
  • Merchant ID: Code that identifies the client.
  • WX File SFTP Host: Hostname for receiving WX Files via SFTP.
  • WX File SFTP Username: Username needed to receiving WX Files via SFTP.
  • WX File SFTP Password: Password for receiving WX Files via SFTP.

Configuration Notes

  • When you send a transaction to Worldline, be sure the currency you specify matches the account's currency in Aria. The record_alternative_payment_m API uses the currency specified in the Worldline transaction, and does not validate it against the Aria account.
  • Due to testing limitations, WebMoney can only be tested in a Production environment.
  • Tokenized SEPA Direct Debit:
    • requires the account holder sign a mandate before it can be implemented. Payments can only be made with SEPA Tokenized Direct Debit after the mandate has been approved with the record_mandate_approval_m API. It is the client's full responsibility to ensure the end user signs a paper mandate that verifies this electronic mandate is valid. Neither Aria nor Worldline can intervene if the end user disputes signing the mandate later.
    • Because this payment method requires setting up the client mandate in advance, it is not available as an alternative one-time payment method when creating orders.
    • The client must collect in the account's currency (which SEPA Direct Debit must support).
    • If the payment status for a SEPA Direct Debit payment returns “PENDING_APPROVAL,” you must approve the payment on the Worldline website after a mandate has been signed. You cannot approve the mandate and resubmit the payment using the Aria UI because Worldline does not provide an update API.

Links

Regarding Processor/Gateway Integration Certifications

If you previously implemented a custom payment processor/gateway integration, you likely completed a certification process with that processor/gateway. Aria maintains certifications with each of the processors with which it integrates. Though you may wish to certify your Aria-related processor/gateway integration before going live on Aria, this is not necessary and could add significant time and Services costs to your Aria implementation process. Please consult your Aria Implementation representative for more detailed information.

Regarding Processor- and Gateway-specific Information

All Processor- and Gateway-specific information provided on Knowledge Central exists as publicly accessible information from the respective companies, and is presented here for your convenience. We update this information from time to time as necessary.

  • Was this article helpful?