Alias Manager (Tokenization)
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!
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)
|
| 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
|
| 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 |
| COF_INITIATOR |
Initiator of the transaction |
Data Type: String
|
| COF_TRANSACTION |
The first or the subsequent of a series of transactions |
Data Type: String
|
| COF_SCHEDULE |
Time planning of the transaction request |
Data Type: String
|
| COF_RECURRING_EXPIRY |
The end date of the last scheduled payment in a series of transactions |
Data Type: String
|
| COF_RECURRING_FREQUENCY |
Days between payments for a scheduled series of transactions |
Data Type: String
|
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
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 |
|
|
| DirectLink |
|
To create Aliases from bank account numbers, send only CARDNO instead of CARDNO/ED/CVC |
| Nexi Payengine Batch (advanced) |
|
|
- For both e-Commerce / FlexCheckout, your customers need to give their consent in our environment. Learn more in the dedicated chapter
- For either DirectLink / Nexi Payengine Batch (advanced), you need to get their consent in your own webshop environment
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
| Integration mode | Parameters | Remarks |
|---|---|---|
| e-Terminal (Virtual terminal) | N/A | Learn in our dedicated chapter how to create Aliases via this channel |
| e-Commerce |
|
|
| FlexCheckout |
|
|
| DirectLink |
|
|
| 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
- 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 |
|
|
| FlexCheckout |
|
|
| DirectLink |
|
|
| Nexi Payengine Batch (advanced) |
|
|
7. Delete Alias
Our platform offers you various ways to delete Aliases you do not want to keep anymore:
| Integration mode | Actions to perform |
|---|---|
|
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 |
|
|
Create a specific Alias batch file with this formatting
An example looks like this: 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 |
|
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.
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
- Alias creation
- Usage of existing alias for a new COF series
| 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 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 |
- 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 |
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
"Global parameters" allows you to manage Alias creation for e-Commerce requests
"Hosted Tokenization Page" allows you to manage Alias creation for FlexCheckout requests
|
| Alias list |
This tab allows you to look up and/or download a list of your Alias(es) by
Access any Alias from this list to
|
| Create |
Create new Aliases by entering the following fields
|
. Due to the PSD2 guidelines, our platform will always create a new Alias if you enter a new card/ account number
.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.
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.