Last update 15/12/2015

1. Introduction

The Alias Manager offers features for recurrent invoicing (payment for periodically invoiced services), and other specific applications with card number or account number aliases (e.g. storage of customer profiles on your website).

An alias is an identifier for a customer and his card or account information, which can be used to request future payments. Every alias is bound to a single merchant and cannot be used by a third party.

With the Alias Manager for recurrent invoicing, if you use Batch, DirectLink and/or e-Terminal you do not have to store their customers' financial details after the initial payment. If you use e-Commerce, you never have to come in contact with or store the customer’s financial details. This reduces risks and investments related to the safe storage of customers’ financial information. The Alias Manager allows the deployment of a secure recurrent invoicing system without the need to make your system PCI compliant.

Even when the Alias Manager is active in your account, you can still perform transactions without specifying an Alias.

When you work in e-Commerce mode, we inform the customer that we will store his financial profile. However, given that our system complies with privacy legislation, a card holder may prohibit us from storing his financial profile. In this case, if the creation of an Alias is crucial, the merchant can decide to prevent the transaction from proceeding.

This restriction does not apply to the other modes where you yourself capture the financial information from the card holder.

This document describes the implementation of the "Alias Manager option" into your e-Commerce / DirectLink / Batch integration, as well as the combination with e-Terminal . This option guide should be read in conjunction with the e-Commerce / DirectLink / Batch / e-Terminal integration/user documentation.

2. Creating an Alias

You can create an alias with a transaction via e-Commerce, DirectLink or Batch. You can also manually create an alias on the Alias Management page.  

When using aliases for credit cards, do not use the card number as the alias name! Also, you cannot use a string of numbers with more than 14 digits starting with 2, 3, 4, 5, or 6 that resembles a card number. This is blocked by our system, as it would be highly insecure to maintain unencrypted card numbers on our system.

The ability to work with an alias for recurring invoicing or other specific applications, depends on the payment methods you wish to use. See the "Payment Methods Processing/Procedure overview page" in the Support section of your back office.

Notes about PayPal and PostFinance Card:

  • Since these brands require an authentication by the card holder, it is only possible to create aliases for these payment methods by using e-Commerce.
  • The minimum amount for the PostFinance Card is CHF 0.05.

2.1 e-Commerce

The process for creating an alias in e-Commerce mode is almost identical to that of a standard e-Commerce transaction. The main technical difference lies in the changes that need to be made in the check before the payment.

2.1.1 Additional hidden fields

To create an alias via e-Commerce, you must send the following additional hidden fields:

Field Description

ALIAS

Alias proposed by the merchant.
ALIASUSAGE A text explaining the reason for the Alias registration.

On submission of the hidden fields, we will display the secure payment page where the customer can select his payment method and enter his payment details.

We will also display the text you sent in the ALIASUSAGE field.

The dialogue includes a tick box that the customer can enable/disable to approve/refuse the storage of his financial profile.

If not enabled then as a merchant you can choose to block the transaction process. This can be done on the Alias Management page (in the Back Office menu, via "Configuration" > "Alias").

If the transaction successful on our platform (not status 0 or 1), we create the alias/financial profile in our Alias database.

2.1.2 Security: SHA signature (pre-payment check)

You must include the alias parameters (ALIAS and ALIASUSAGE) in the calculation of the SHA signature.

For more details, go to e-Commerce.

2.1.3 Transaction feedback to the merchant

If you receive feedback requests after the transaction, or you receive feedback parameters on a redirection, you will receive an extra parameter: ALIAS.

If you have configured an SHA-OUT passphrase for these feedback requests, you need to take the ALIAS parameter into account for your signature. 

To create an alias with a transaction via DirectLink, you must send the following parameters in addition to the other transaction parameters:

Field Description
ALIAS Alias proposed by the merchant
CARDNO Card number
ED Expiry date
CN Cardholder name

If the transaction successful on our platform (not status 0 or 1), we will create the alias/financial profile in our Alias database.

For Direct Debits the account number should be sent in the CARDNO field and the expiry date should not be sent. 

You must include the alias parameters (ALIAS and ALIASUSAGE) in the calculation of the SHA signature.

For more details, go to e-Commerce.

The XML response to your request will contain the extra parameter ALIAS.

2.3 Batch

To create an alias with a transaction via Batch, you must send the following fields in addition to the other transaction fields:

Field Field number
ALIAS 17
CARDNO 4
ED 5
CN 8

If the transaction is successful on our platform (not status 0 or 1), we will create the alias/financial profile in our Alias database.

Note for Direct Debits (AT/DE/NL): The expiry date should not be sent, and the account number (IBAN or regular) should be sent in the field CARDNO.

2.4 Alias Manager

Aliases can be registered manually in the back office:

  1. Go to "Configuration" > “Alias” in the back-office menu to enter the Alias Management page;
  2. Click the “Create” tab to register a new Alias;
  3. Enter the Alias name;
  4. Enter the account/cardholder's name, and then choose the relevant payment method: Credit Card / Direct Debit;
  5. Next enter the card number and expiry date or bank account and IBAN/BIC info;
  6. Click “Create”.

Note that this method is only possible for credit cards and direct debits. It is not possible to register new aliases for PayPal or PostFinance Card in the back office.

As the alias is created manually rather than via a transaction we will not create the alias/financial profile in our Alias database immediately. We can only enter the financial profile into our database when a transaction using the alias is accepted by the financial institution, i.e. after the payment data has been officially verified.

3. Alias usage

The ability to work with an alias for recurrent invoicing or other specific applications depends on the payment methods you wish to use.

3.1 e-Commerce

To use an existing ALIAS, the following hidden fields can or must be submitted in your request:

Field Description Mandatory
ALIAS The name of the ALIAS you want to use. We will check whether the alias already exists for your account/PSPID. Y
ALIASUSAGE Send a value with this field only if you want to show a different text to the customer than the one you initially sent at the time the alias was created. N

If the alias exists, the cardholder name, masked credit card number (or account information) and expiry date will be initialised in the payment details page for validation.

3.1.1 Alias update

If the cardholder does not change any of the pre-set details and simply clicks the “Submit” button, we will look up the financial profile (based on the alias) in the database.

However, if he wishes to update certain details, such as the expiry date, the cardholder can modify the initialised fields. If the transaction is successful on our platform (not status 0 or 1), we will update the customer’s financial details accordingly.

For more information on pre-payment checks and post-transaction feedback requests, go to Creating an Alias via e-Commerce.

To use an existing ALIAS, you must submit the following fields in your request:

Field Description
ALIAS The name of the ALIAS you want to use. We will check whether the alias already exists for your account/PSPID.
ALIASPERSISTEDAFTERUSE It indicates whether you want to store a temporary (N) or indefinite (Y) Alias. The possible values are:
  • "N": the alias will be deleted after 2 hours.
  • "Y": the alias will be stored indefinitely, for future use.
Note: 
If an Alias is created with the N value and the transaction is completed within a two-hour timeframe, the transaction too must include this parameter/value combination for the alias to be deleted. If the transaction does not contain this parameter/value combination, the alias will be retained for future use.
ECI ECI value "9" must be sent for recurring transactions.

If the alias exists, the cardholder name, masked credit card number (or account information) and expiry date will be initialised in the payment.

If you simply send us the ALIAS (with no new credit card number, expiry date, cardholder name), we will look up the financial profile (based on the ALIAS) in the database.

Apart from the ALIAS parameter, you can also send us a new credit card number, expiry date or cardholder name to update the existing ALIAS. If the transaction is successful on our platform (not status 0 or 1), we will update the cardholder’s financial details accordingly.

3.3 Batch

To use an existing ALIAS, you must submit the following fields in your file:

Field Description Field No.
ALIAS The name of the ALIAS you want to use. We will check whether the alias already exists for your account/PSPID. 17
ECI ECI value "9" must be sent for reccurring transactions. 35

3.3.1 Alias update

If you send us the alias, we will look up the financial profile (based on the alias) in the database.

Apart from the ALIAS field you can also send us a new credit card number, expiry date or cardholder name in order to update the existing alias. If the transaction is successful on our platform (not status 0 or 1), we will then update the cardholder’s financial details accordingly.

3.4 e-Terminal

To use an alias via e-Terminal, please follow these steps:

  1. Click the “Alias” link in the back-office menu.
  2. Look up the alias you want to use in the Alias Management page.
  3. Click the "Use" button in the Alias row. You will see the voucher pre-initialised with the cardholder's name, card number and expiry date.

3.4.1 Alias update

Only the expiry date can be changed in the voucher. The initialised cardholder's name and card number cannot be changed in the voucher.

3.5 Errors

If an alias is submitted with a transaction, but our system can't find the alias (usually when the alias doesn't exist), an error code and message will be returned as follows:

Return field
Value
NCERROR
50001111 (Data validation error)
NCERRORPLUS
Alias "..." not Found

If a customer has made use of the Recurring Payment Stop Service (by Visa and MasterCard), resulting in the termination of a recurring payment subscription by the card issuer, an error code and message will be returned as follows:

Return field
Value
NCERROR
31171001
NCERRORPLUS
Cardholder has cancelled the recurring payment. Any further recurring payment will be declined.

We recommend you to stop the issuing of subsequent transactions for a recurring payment, on receipt of this error.

4. Alias management

Go to "Configuration" > “Alias” in the back-office menu to access the Alias Management page. This page is divided into the following tabs:

  • My alias information:
    • Status:
      • The number of aliases with credit cards that will expire by the end of the current calendar month. (clickable to see the list).
      • The number of active aliases. (clickable to see the list).
      • The number of aliases that have been deleted in the current calendar month.
      • The number of active aliases in the previous calendar month.
    • Global parameters: Here you can configure:
      • if the opt-in/out check box on the payment page is checked or not. The cardholder can still decide whether or not to save his credit card details, by (un)checking the box on the payment page.
      • if the transaction should be blocked if the cardholder refuses to have his details stored/an alias created.
      • the retention period: define in months how long your aliases must be stored. You can choose any number between 3 and 60 months (5 years). This period is reinitiated after each use.
    • Hosted Tokenization Page: configure whether or not to display the opt-in/opt-out checkbox on the Hosted Tokenization Page.
  • Alias list, to lookup, edit (card details), and delete aliases. Optionally, you can also make new transactions with an alias or make refunds (without prior payment).
  • Create, to make new aliases.

5. Special applications

This section explains specific, advanced alias applications, requiring a higher level of integration. These applications are not applicable for recurrent payments.

The ability to work with an alias for recurrent invoicing or other specific applications depends on the payment methods you wish to use.

5.1 e-Wallet

You can provide registered customers with an e-wallet of credit cards without having to manage their financial details.

You create a new alias for a new customer's initial payment. When the customer next visits your site, you can display the masked card(s) related to his alias(es) in the background (in your html code). The easiest way to register the masked card numbers is to extract them from the feedback parameters we send you after each transaction (e-Commerce).

Example:

<Select name=”cards”>
<option value=”alias284”>VISA – XXXXXXXXXXXX1111</option>
<option value=”alias128”>MasterCard – XXXXXXXXXXXX9999</option>
<option value=”alias389”>Use a new card</option>
</select>

When the customer selects (one of) his masked card(s) on your website, the linked alias will be sent to us in your hidden fields.

You can still propose the "Other Card" option, which will trigger the alias creation process.

5.2 Optimised Alias management

When you use the Alias Manager with e-Commerce or DirectLink, you can also send an additional ALIASOPERATION field / parameter.

Field
Possible values
ALIASOPERATION
Empty (or BYMERCHANT)
BYPSP

When you have a prospective new customer, you have to create a new alias. However, the card that will be used in the transaction might have already been used previously on your website and correspond to an already existing Alias. ALIASOPERATION BYPSP can be used to reduce the creation of double Aliases for the same card number.

To create a new Alias, you can leave the Alias field empty and send along BYPSP with ALIASOPERATION. Our system will then check whether an alias for the card number already exists and will only create a new alias if necessary. If the used card number corresponds to an already existing alias, no new alias will be created and the payment will be linked to the found alias.

When you submit an alias value in the ALIAS field/parameter (i.e. use an Alias) and BYPSP as ALIASOPERATION, we will check whether the received financial data corresponds to an existing alias.

If the customer changed his credit card details in the transaction, our feedback parameters/XML response will contain a different Alias from the one you sent us. The alias returned in the feedback parameters/XML response will correspond to an already existing alias for the new card number or a new Alias created by our system.

If your processes require aliases related to the ORDERID (a new alias for each order), the ALIASOPERATON parameter must be left empty (or set to the value BYMERCHANT).

The following table provides an overview of the possibilities of both ALIASOPERATION values for creating and using/updating your aliases. You can use a different ALIASOPERATION for creating and using/updating your aliases. In this way, you can optimise your Alias Management depending on your specific needs.

  ALIASOPERATION
 

Empty (or BYMERCHANT)
BYPSP
Sent at the time of the Alias creation
  • Merchant chooses his alias names.
  • Possibility to create a new alias for each order.
  • Our system chooses the alias names.
  • Our system only creates a new alias if the card number is not already linked to another alias.
Sent at the time of the Alias usage/update
(alias sent in ALIAS field)
One alias per customer: if the customer changes his credit card details in the transaction, the alias will be updated with the new details. One alias per credit card: if the customer changes his credit card details in the transaction, a new alias will be created.

5.2.1 Example using BYMERCHANT (or empty)

Data in our alias database:

Alias
Card number
A14352
41111…
B76985  53999…

Example 1:

  • Alias sent: A14352
  • Card used: 37411…
  • Alias received: A14352

Data in our alias database:

Alias
Card number
A14352
37411…
B76985  53999…

Example 2:

  • Alias sent: C01203
  • Card used: 53999…
  • Alias received: C01203

Data in our alias database:

Alias
Card number
A14352
41111…
B76985  53999…
C01203 53999…

5.2.2 Example using BYPSP

Existing database:

Alias
Card number
XXXXXXXX-CA55-4995-B4F0-C3424AB2C2BA 41111…
YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA 53999…

Example 1:

  • Alias sent: XXXXXXXX-CA55-4995-B4F0-C3424AB2C2BA
  • Card used: 37411…
  • Alias received: ZZZZZZZZ-CA55-4995-B4F0-C3424AB2C2BA

Data in our alias database:

Alias
Card number
XXXXXXXX-CA55-4995-B4F0-C3424AB2C2BA
41111…
YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA  53999…
ZZZZZZZZ-CA55-4995-B4F0-C3424AB2C2BA
37411…

As the card used did not exist in the database, but the Alias sent already existed with a different card number, a new alias was created.

In the event of "ALIASOPERATION: empty (or BYMERCHANT)", the existing Alias would be updated with the card number sent.

Example 2:

  • Alias sent: empty
  • Card used: 53999…
  • Alias received: YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA

Data in our alias database:

Alias
Card number
XXXXXXXX-CA55-4995-B4F0-C3424AB2C2BA
41111…
YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA 53999…
ZZZZZZZZ-CA55-4995-B4F0-C3424AB2C2BA
37411…

As the card used was already linked to an existing Alias, the Alias sent was not created and the existing Alias was used.

In the event of "ALIASOPERATION: empty (or BYMERCHANT)", the new Alias would be created with the card number sent, in which case there would be two aliases with the same card number in the database.

Example 3:

  • Alias sent: ZZZZZZZZ-CA55-4995-B4F0-C3424AB2C2BA
  • Card used: 53999…
  • Alias received: YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA

Data in our alias database:

Alias
Card number
XXXXXXXX-CA55-4995-B4F0-C3424AB2C2BA
41111…
YYYYYYYY-CA55-4995-B4F0-C3424AB2C2BA 53999…
ZZZZZZZZ-CA55-4995-B4F0-C3424AB2C2BA
37411…

As the card used was already linked to another existing Alias and the Alias sent already existed, the Alias corresponding to the card number was used.

In the event of "ALIASOPERATION: empty (or BYMERCHANT)", the existing Alias would be updated with the card number sent, in which case there would be two different aliases with the same card number in the database.

6. Optional: Bulk Alias management via Batch

6.1 Overview

Bulk Alias management via Batch allows the merchant to:

  • create large numbers of aliases at once, without having to make transactions
  • delete large numbers of aliases at once
The merchant has to provide the batch files in “BYMERCHANT” mode, with the Alias ID included.

The batch files can be uploaded both automatically and manually through https request on the Ingenico ePayments platform. This can be done synchronously or asynchronously, although we recommend processing the files asynchronously if more than 100 records are entered per file.

With this way of creating aliases, no transactions will be made.

A format check ensures that the credit card numbers or bank account numbers are correct, though no authorisation is done. As a result, this format check will not ensure that the card/account is in fact still valid.

If the expiry date of a credit card is in the past, our system will add two years until the date is in the future. This is a standard process used for alias creation.

The merchant will be able to upload his files for alias creation/deletion in two different ways:
  1. Manual file upload: the merchant can upload the files manually from his account’s back office (see Basic Batch).
  2. Automatic upload from a merchant application: the merchant’s application makes file upload requests via https on specific pages on our system (see Advanced Batch).

For more information, go to Automatic Batch for request URL and specific parameter.

6.2 Format

The request file should be an ASCII text file and can only contain one line per alias. The fields must be separated by a semicolon (“;”) and cannot contain a semicolon themselves.

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
  Field
Format
Example
1
OPERATION
AN, 8
ADDALIAS
2
ALIAS
AN, 50
Customer123
3
CN
AN, 35
John Doe
4
CARDNO
AN, 21
XXXXXXXXXXXX1111
5
EXPDATE
MMYY 1012
6
BRAND
AN, 25
VISA
7
PSPID
AN, 30
JDoeSHOP

Example for Credit card:

ADDALIAS;Customer123;John Doe;XXXXXXXXXXXX1111;1012;VISA;JDoeSHOP;

Example for Direct Debits:

ADDALIAS;Customer1234;John Doe;123454321BLZ00000000;;DirectDebitsDE;JDoeSHOP;

6.3 Deletion

The request file should be an ASCII text file and can only contain one line per alias. The fields must be separated by a semicolon (“;”) and cannot contain a semicolon themselves.

Field Format Example
1 OPERATION A, 8 DELALIAS
2 ALIAS AN, 50 Customer123

 

Example: DELALIAS;Customer123;;;;;; (all semicolons at the end must be included!)

Automatic file upload:

To execute the deletion of an alias via Automatic file upload, a file with the following layout is expected:
OHL;PSPID;API PASSWORD;;USER API;
DELALIAS;ALIAS VALUE;;;;;;
DELALIAS;ALIAS VALUE;;;;;;

OTF;
We advise to use the "checkandprocess" and list aliases belonging to the same PSPID only.

For more information on the different automatic upload processes, go to Advanced Batch.

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data