1. Introduction

Our Alias Manager (Tokenization) is the ideal solution for managing recurring payments worry-free.

Instead of saving your customers’ sensitive card data on your own, leave this to us! Our platform allows you to create Aliases, use them and do many more things. 

All of our integration modes support Alias usage. With our solution, you can

  • store credit card data safely on our platform and use them whenever you want
  • enhance your regular customers’ shopping experience with little or no card data to be filled in during the payment process
  • initialise yourself spontaneous or scheduled recurring payments
  • process mass uploads of Aliases at once easily

Have a look at how at how Alias Manager (Tokenization) empowers you in your daily online transaction business!

To use this feature, make sure option Alias Manager (RECX) is active in your account. Check this in your Back Office via Configuration > Account > Your options > Available options or Default Options.

2. Understand Alias Manager (Tokenization)

An Alias is a credit card or bank account number stored on our platform. It is linked to the owner of this card/bank account who has authorised you to store this data during an initial transaction. This allows you to re-use the card/bank account at will for subsequent payments.

Our Alias Manager (Tokenization) works with the following payment methods:

To ensure a safe and fair Alias usage, you need to provide information about Alias transactions (the initiator of the payment, its timing, frequency etc). Our overview of possible use cases helps you identify typical scenarios and how you can translate them in your transaction request.

But first things first: let’s have a closer look at how this feature works when processing transactions.

3. Understand ALIAS parameters

If you want to work with Aliases, you need to send Alias-specific parameters to our platform. This also includes credentials-on-file (COF) parameters introduced by the card schemes.

Have a look at the different parameters and their purpose. To help you choose the right ones for any of your request, we list them for each integration mode separately in the subsequent chapters. On top of that, our use cases overview gives you further exact instructions.

Find detailed information (short description, format, maximum length and so on) for each parameter in our Parameter Cookbook.

Parameter Description Format
ALIAS / ALIAS.ALIASID The unique identifier of the card profile on our platform. Choose a description freely using alphanumeric characters.
For existing Aliases, use this identifier to create a recurring payment or update the Alias with new card data
Data type: String (alphanumeric)
ALIASOPERATION

Instruct our platform to create a unique identifier when creating an Alias.

Use this parameter to optimise your Alias management by avoiding creating Alias duplicates. Check out our dedicated chapter how it works


Data type: String (alphanumeric)
Values accepted: 

  • NULL/BYMERCHANT = You send the unique identifier in ALIAS / ALIAS.ALIASID
  • BYPSP = Our system creates the unique identifier for you
ALIASPERSISTEDAFTERUSE /
ALIAS.STOREPERMANENTLY

Indicate for DirectLink transactions whether to store an Alias permanently or delete it after its creation. Useful for FlexCheckout requests to tokenise cards only temporarily

To ensure our platform treats newly created Aliases as intended for FlexCheckout requests, send both ALIAS.STOREPERMANENTLY ALIASPERSISTEDAFTERUSE during the Alias creation / usage requests accordingly

Data Type: Boolean
Values accepted:

  • N = We delete the Alias after two hours
  • Y = We store the Alias permanently for future purchases
ALIASUSAGE

Displays information to your customers on our e-Commerce defining the reasons for Alias creation
 

Data type: String (alphanumeric)

ECI

Indicate our platform you want to use an existing Alias for a recurring payment


Data type: String
Fixed value ECI=9

COF_INITIATOR

Initiator of the transaction

Data Type: String
Values accepted:

  • CIT = Your customer (Customer-Initiated-Transaction)
  • MIT = You (Merchant-Initiated Transaction)
COF_TRANSACTION

The first or the subsequent of a series of transactions

Data Type: String
Values accepted:

  • FIRST = First of a series of transactions
  • SUBSEQ = Subsequent of a series of transactions
COF_SCHEDULE

Time planning of the transaction request

Data Type: String
Values accepted:

  • SCHED = A scheduled transaction
  • UNSCHED = An unscheduled transaction
COF_RECURRING_EXPIRY

The end date of the last scheduled payment in a series of transactions

Data Type: String
Values accepted:

  • YYYYMMDD (i.e. March 1st 2021: 20210103)
COF_RECURRING_FREQUENCY

Days between payments for a scheduled series of transactions

Data Type: String
Values accepted:

  • Numeric value between 2 and 4 digits (i.e. 31, 031 or 0031)

4. Create Alias

The life cycle of an Alias generally starts with a new transaction. Indicate in your transaction request that you wish to store your customers’ credit card  / bank account number on our platform.

This requires you to send

  • The standard mandatory parameters for a new transaction. Find these for each channel in the dedicated integration guide
  • Alias parameters to indicate your intention to create an Alias
  • COF parameters to indicate the specific creation scenario. Check out our use cases overview to know which parameters/values to send
To ensure PCI-DSS compliancy, our platform blocks any Alias creation attempt if the value in parameter ALIAS is or resembles are card number.
Hence, make sure respect these rules: 
  • Do not send your customers' card number
  • Do not use figures 2, 3, 4, 5, 6 at the beginning of the ALIAS name or a string of numbers with more than 14 digits
Integration mode Parameters Remarks
e-Terminal (Virtual terminal) N/A Learn in our dedicated chapter how to create Aliases via this channel
e-Commerce Customers need to agree to Alias creation on our secure payment page. Learn all about it in this chapter
FlexCheckout
  • No COF_XXX parameters necessary during this step. Send them in the subsequent DirectLink request
  • Use the (temporary) Alias in a subsequent DirectLink request
  • If you want to delete the Alias immediately after usage, send ALIAS.STOREPERMANENTLY=N and ALIASPERSISTEDAFTERUSE=N in the subsequent DirectLink request
DirectLink To create Aliases from bank account numbers, send only CARDNO instead of CARDNO/ED/CVC
Nexi Payengine Batch (advanced)

  • To create Aliases from bank account numbers, send only CARDNO instead of CARDNO/ED/CVC

  • Read our dedicated chapter about the file layout containing COF parameters
You need explicit approval from your customers to create Aliases

5. Use Alias

Once an Alias is created, you may use it for recurring payments. As the Alias points to a card profile on our platform, your customers do not have to fill in all of their card data during the payment process, making it a lot smoother.

This requires you to send

  • The standard mandatory parameters for a new transaction without the card /bank account parameters. Find these for each channel in the dedicated integration guide
  • Alias parameters to indicate your intention to use an existing Alias
  • COF parameters to indicate the specific usage scenario. Check out our use cases overview to know which parameters/values to send
You can use an existing Alias for any integration mode – regardless which one you chose for the initial Alias creation. This allows you i.e. to use an Alias for DirectLink and/or Batch transactions, although the Alias was created via e-Commerce. As you do not handle any credit card data, you keep a low PCI profile despite using these integration modes.
Integration mode Parameters Remarks
e-Terminal (Virtual terminal) N/A Learn in our dedicated chapter how to create Aliases via this channel
e-Commerce
  • Sending this request will pre-fill the credit card fields on our secure payment page, allowing your customers to update the Alias
  • Send ALIASUSAGE only when you want to display a different text to your customer than the one you displayed at the time you created the Alias
  • This scenario treats your requests as CITs. To make sure our platform treats them correctly, make sure to set the Default ECI value to “7 – E-commerce with SSL encryption” in your account (Configuration > Technical information > Global transaction parameters > Default ECI value).
FlexCheckout
  • No COF_XXX parameters necessary during this step. Send them in the subsequent DirectLink request
  • Use the (temporary) Alias in a subsequent DirectLink request
  • If you want to delete the Alias immediately after usage, send ALIAS.STOREPERMANENTLY=N and ALIASPERSISTEDAFTERUSE=N in the subsequent DirectLink request
DirectLink
  • If you want to delete the Alias immediately after usage, send ALIAS.STOREPERMANENTLY=N and ALIASPERSISTEDAFTERUSE=N in the subsequent DirectLink request
  • Send ALIASPERSISTEDAFTERUSE only when you created the Alias during a immediately preceding FlexCheckout request. Send the same value for both ALIAS.STOREPERMANENTLY/ALIASPERSISTEDAFTERUSE
  • Send ECI=9 for tokens created by an initial e-Commerce or DirectLink transaction.
  • Send ECI=2 for tokens created by an initial MOTO transaction.
Nexi Payengine Batch (advanced)

6. Update Alias

Updating an Alias is essentially an Alias usage scenario in which you offer your customers to change the Alias data.
This requires you to send

  • The standard mandatory parameters for a new transaction including the card /bank account parameters
  • Find these for each channel in the dedicated integration guide
  • Alias parameters to indicate your intention to use an existing Alias
  • COF parameters to indicate the specific usage scenario. Check out our use cases overview to know which parameters/values to send

Due to the PSD2 guidelines, our platform will always create a new Alias if
    • Your customers update the card number
    • You send the same card number already stored in for an existing Alias, resulting in duplicate Aliases containing the same card number

In certain situations, you can still avoid creating Alias duplicates. Check out our dedicated chapter how it works

Integration mode Parameters Remarks
e-Terminal (Virtual terminal) N/A Learn in our dedicated chapter how to create Aliases via this channel
e-Commerce
  • Sending this request will pre-fill the credit card fields on our secure payment page, allowing your customers to update the Alias
  • If your customer changes the card number, we will create a new Alias. We include the new Alias in the transaction feedback
  • Send ALIASUSAGE only when you want to display a different text to your customer than the one you displayed at the time you created the Alias
FlexCheckout
  • Sending this request will pre-fill the credit card fields in the iframe payment form, allowing your customers to update the Alias
  • Use the updated Alias in a subsequent DirectLink
    transaction
DirectLink
Nexi Payengine Batch (advanced)
  • If you send CARDNO, we will create a new Alias. We include the new Alias in the XML response
  • Read our dedicated chapter about the file layout containing COF parameters

7. Delete Alias

Our platform offers you various ways to delete Aliases you do not want to keep anymore:

Integration mode Actions to perform

FlexCheckout

DirectLink

This applies only for Aliases you create on a temporary base and for immediate use.

Send ALIAS.STOREPERMANENTLY=N in your FlexCheckout and ALIASPERSISTEDAFTERUSE=N in the subsequent DirectLink request. We will delete the Alias after two hours

Batch

Nexi Payengine Batch (advanced)

Create a specific Alias batch file with this formatting

  • OPERATION= DELALIAS (mandatory - field #1)
  • ALIAS=Alias to be deleted (mandatory - field #2)
  • Fields #3 – #7 = NULL

An example looks like this:

DELALIAS;ALIAS VALUE;;;;;;
DELALIAS;ALIAS VALUE;;;;;;
.
.
.

Upload it via the Back Office or with a server-to-server request.

Send MODE=CHECKANDPROCESS only for files containing Aliases that belong to a single PSPID.

Back Office

  • Login to the Back Office. Go to Configuration > Alias > Alias list
  • Fill in the “Search by” form and click on “SEARCH” to look up the Alias(es) to be deleted. In column “Action”, click on the delete symbol

8. Upload Alias

Our integration modes Nexi Payengine Batch (Basic) and Nexi Payengine Batch (advanced) allow not only Alias creation/usage/update/deletion, but also uploading already existing Aliases.

Uploading means to create an Alias database without actual transaction processing. This is a highly convenient solution for you if you want to migrate an Alias bulk from a different payment service provider to our platform.

Contact us if you plan to use this feature, as it requires some involvement from our side

Once you have uploaded these Aliases, you can use them for any operation and integration mode. Create a specific Alias batch file with this formatting. Upload it via the Back Office or with a server-to-server request:

Field (No / Name) Description/Possible values Format/max length
1 / OPERATION Fixed value: ADDALIAS AN/ 8

2 / ALIAS

The unique identifier of the card profile on our platform. Choose a description freely using alphanumeric characters AN, 50

3 / CN

Card holder (customer) name AN, 35

4 / CARDNO

Card number or account number AN, 21

5 / ED

Card number expiry date MMYY, 7
6 / BRAND

Card brand AN, 25
7 / PSPID Your account to which the Aliases should be uploaded AN, 30

Check out our example for credit cards /bank account numbers:

  • Credit cards
    ADDALIAS;Customer123;John Doe;XXXXXXXXXXXX1111;1012;VISA;JDoeSHOP;

  • Direct Debits
    ADDALIAS;Customer1234;John Doe;123454321BLZ00000000;;DirectDebitsDE;JDoeSHOP;
  • For every upload request, our platform checks the card /bank account format and the expiry date (parameter ED). If a card is already expired, our platform will not upload the impacted Alias
  • For uploads via Nexi Payengine Batch (advanced) we recommend asynchronous upload mode for records of more than 100 per file

9. Understand COF use cases

The introduction of the Credential-on-File guideline (COF) by card schemes changes the Alias creation and usage process.

This guideline ensures greater transparency on card data storage and their use for recurring payments. As a merchant, you need to send detailed information about the purpose of Alias creation / usages. This transparency standard also applies to your customers. In some cases, they might have to redo a 3-D Secure check or re-enter their CVC code in an Alias usage scenario.

The card schemes use this information to improve their risk assessment – which leads to higher approval rates for your transaction requests! In certain scenarios, card schemes may pass on security checks that are normally obligatory – which makes your customers’ payment experience even smoother!

The card schemes distinguish between

  • COF_INITIATOR: CIT (Customer-Initiated-Transaction) and MIT (Merchant-Initiated Transaction)
  • COF_TRANSACTION: First or subsequent transactions of a series of transactions
  • COF_SCHEDULE: Scheduled and unscheduled transactions
  • COF_RECURRING_EXPIRY: The date of the final payment
  • COF_RECURRING_FREQUENCY: The frequency of subscription payments

The below overview is a summary of use cases you might encounter in your daily business. Add the parameters to your Alias creation / usage request matching with the respective scenario:

9.1 Create Alias

The following cases require you to roll out 3-D Secure by indicating challenge flow as the preferred flow:
Use case Parameters
Subscription Payment: Customer initiates the first payment for a subscription WITH a fixed amount AND periodicity COF_INITIATOR=CIT
COF_TRANSACTION=FIRST
COF_SCHEDULE=SCHED
COF_RECURRING_EXPIRY=YYYYMMDD (end date)
COF_RECURRING_FREQUENCY=Minimum amount of days between payments

1-Click-Payment: Your customer initiates a stand-alone purchase and agree on the card data to be stored

OR

Unscheduled Payment: Customer initiates the first payment for a series of transactions WITHOUT a fixed amount OR periodicity

COF_INITIATOR=CIT
COF_TRANSACTION=FIRST
COF_SCHEDULE=UNSCHED
You need to get the explicit consent from your customers for either scenario

  • For card data to be stored ONLY for potential future payments at your customer's initiative
  • For card data to be stored AND used for future payments at your initiative based on agreed terms and conditions

9.2 Alias usage/update

Use case Parameters
Subscription payment: You initiate a subsequent payment linked to a subscription COF_INITIATOR=MIT
COF_TRANSACTION=SUBSEQ
COF_SCHEDULE=SCHED
COF_RECURRING_EXPIRY=YYYYMMDD (end date)
COF_RECURRING_FREQUENCY=Minimum amount of days between payments
1-Click-payment: Your customer initiates a stand-alone purchase with an existing Alias created during an earlier stand-alone purchase COF_INITIATOR=CIT
COF_TRANSACTION=SUBSEQ
COF_SCHEDULE=UNSCHED
Unscheduled payment: You initiate a subsequent payment within a series of transactions COF_INITIATOR=MIT
COF_TRANSACTION=SUBSEQ
COF_SCHEDULE=UNSCHED

To avoid unexpected authorization rejection, you need to provide consistent inputs for all recurring payments, notably for the subscription payment use case

10. Manage Alias in Back Office

You can manage your Aliases in your Back Office. Have a look at what is possible:

  • Login to the Back Office. Go to Configuration > Alias
  • In each of the tabs, you can perform the following actions:
Tab Possible actions
My alias information

    "Status" provides an overview about

    • Cards that will expire at the end of the current month. Click on the number to get a full list in the "Alias list" tab
    • Currently active Aliases. Click on the number to get a full list in the "Alias list" tab
    • Deleted Aliases in the current month
    • The number of active Aliases in the last month. This number is displayed on your invoice of the corresponding month.

    "Global parameters" allows you to manage Alias creation for e-Commerce requests

    • Select "Opt-in" / "Opt-out" to define whether your customers must actively agree / disagree to the creation of an Alias
    • (De)Flag "Block transaction process if cardholder refuses alias creation." to enforce the creation of an Alias for a transaction request or let your customers choose
    • "Retention period" defines how long we store an Alias (between 3 and 60 months) after its creation. This value applies to all Aliases, regardless of the integration mode you used for creation.

    "Hosted Tokenization Page" allows you to manage Alias creation for FlexCheckout requests

    • Select "Yes" / "No" to define whether the opt-in/opt-out checkbox
      for Alias creation is visible in the iframe payment form
    Alias list

    This tab allows you to look up and/or download a list of your Alias(es) by

    • Payment method
    • Alias name
    • Card / account number
    • Expiry date

    Access any Alias from this list to

    • Update it with the edit symbol AM-5.png. Due to the PSD2 guidelines, our platform will always create a new Alias if you enter a new card/  account number
    • Delete it with the delete symbol AM-6.png.
    • Make a recurring payment via the “USE” button in our e-Terminal (Virtual terminal) module. Read the dedicated chapter how it works
    Create

    Create new Aliases by entering the following fields

    • Alias
    • Account/ card holder's name
    • Card number / Expiry date

    11. Use additional possibilities

    Our tool offers many more features that will make your business thrive. Learn here what you can achieve with it.

    Optimise Alias usage/update

    You might encounter the following situation when creating an Alias: A customer uses a card that is linked to an existing Alias. Logically, you expect our platform to link the payment to this existing Alias – and not to create a new one. However, due to the PSD2 guidelines, our platform will always create a new Alias instead.

    In an Alias usage scenario, your customer might also update the card number of the Alias to be used. This allows you to choose between:

    • The Alias to be used is updated with the new credit card
    • The update results in the creation of a new Alias

    Depending on your business model, you might prefer one of these options. By sending the additional parameter ALIASOPERATION, you have full control this:

    ALIASOPERATION Result
    NULL/BYMERCHANT One alias per customer: We update the Alias to be used with the new credit card number
    BYPSP One alias per credit card: We create a new Alias with new credit card number

    Create and use Aliases with ALIAS/ALIASUSAGE only

    Although we strongly recommend using COF parameters, we offer you to create and use Aliases with parameters ALIAS/ALIASUSAGE only.
    When you create an Alias this way, we mark the transaction as COF_INITIATOR=CIT in the background. You may use this Alias for subsequent CIT transactions, but not for MIT transactions.

    This option available for e-Commerce only

    Create e-Wallet

    Our platform allows you to provide your regulars with a credit card e-Wallet for our e-Commerce solution.
    Whenever a customer with at least one Alias revisits your webshop, you can display the masked cards linked to the Aliases on your checkout page. You can look up the masked cards in various ways:

    • In the Back Office via Configuration > Alias > Alias list
    • In transaction feedback parameter CARDNO with a DirectQuery request
    • Via file download using our Reporting

    Add the following HTML code example to your checkout page. It allows your customers to choose between Aliases and a new card.

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

    Depending on your customers' choice, send either an Alias creation or usage request.