Alias Manager (Tokenization)
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. |
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.
2.2 DirectLink
2.2.1 Additional request parameters
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.
2.2.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.2.3 Transaction response
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:
- Go to "Configuration" > “Alias” in the back-office menu to enter the Alias Management page;
- Click the “Create” tab to register a new Alias;
- Enter the Alias name;
- Enter the account/cardholder's name, and then choose the relevant payment method: Credit Card / Direct Debit;
- Next enter the card number and expiry date or bank account and IBAN/BIC info;
- Click “Create”.
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 |
|---|---|
|
ALIAS |
The name of the ALIAS you want to use. We will check whether the alias already exists for your account/PSPID. Mandatory |
| 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. Optional |
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).
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.
3.2 DirectLink
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:
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 |
|
If the alias exists, the cardholder name, masked credit card number (or account information) and expiry date will be initialised in the payment.
3.2.1 Alias update
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:
- Click the “Alias” link in the back-office menu.
- Look up the alias you want to use in the Alias Management page.
- 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.
- Status:
- Alias list, to lookup and download (in spreadsheet) , 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.
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 batch files can be uploaded both automatically and manually through https request on the Paypage 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:
- Manual file upload: the merchant can upload the files manually from his account’s back office (see Basic Batch).
- 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.
| # / 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.
7. Alias creation and usage within Credential-on-File guideline (COF)
7.1 Overview
With the introduction of the Credential-on-File guideline (COF) by the major payment schemes Visa / MasterCard, the process of Alias creation and usage will require some modifications.
COF transactions can be distinguished between cardholder-initiated transaction (CIT) and merchant-initiated transaction (MIT).
As it is initiated by the cardholder, any CIT can trigger 3DS identification. If a CIT is the initial transaction of a cycle of transactions (i.e. for a subscription), 3DS is mandatory.
As it is initiated by the merchant, a MIT will not trigger 3DS, as a MIT (i.e. a regular payment for a subscription) is generally preceded by a CIT with 3DS. To make sure such a transaction is successfully processed, the merchant needs to send additional information to Paypage. For doing so, the following COF parameters need to be sent to specify the context of the transaction (first or subsequent) and/or use cases (subscription, unscheduled etc…):
|
Parameters |
Values |
Description |
|---|---|---|
| COF_INITIATOR* | CIT | A transaction initiated by a cardholder |
| MIT | A transaction initiated by a merchant | |
| COF_SCHEDULE* | SCHED | A scheduled transaction |
| UNSCHED | An unscheduled transaction | |
| COF_TRANSACTION* | FIRST | First of a series of transactions |
| SUBSEQ |
Subsequent series of transactions |
|
| COF_RECURRING_EXPIRY* | Date YYYYMMDD (i.e. 20190914) | End date : date of the last scheduled payment of a series |
| COF_RECURRING_FREQUENCY* | numeric between 2 and 4 digits (i.e. 31, 031 or 0031) | Days between payments for a scheduled series. |
* Please send the parameter values according to the format as defined in the table. Otherwise the transaction will be blocked by our system.
For the following scenarios (CIT / MIT / Alias creation / usage), the following values apply:
|
Parameter values COF_INITIATOR-COF_TRANSACTION-COF_SCHEDULE |
Description |
|---|---|
| CIT-FIRST-UNSCHED | Applies when an alias is used or created |
| CIT-FIRST-SCHED |
Applies to a first scheduled payment/subscription |
| MIT-SUBSEQ-UNSCHED | Applies when an alias is used or created |
| MIT-SUBSEQ-SCHED | Applies to installment |
7.2 Alias usage / creation via eCommerce
Although using COF parameters for Alias creation / usage is strongly recommended, we still offer our merchants to stick to the established procedure by relying on the parameters ALIAS/ALIASUSAGE only. However, this will limit the reusability of the created Aliases significantly and is limited to eCommerce integration mode.
During Alias creation, Paypage will mark the transaction as CIT in the background. As a result, the created Alias will only be able to be used in subsequent CIT (i.e. the card holder re-visits the merchant’s web shop for another purchase without entering his credit card details anew). Consequentially, using the same Alias for MIT will fail.
Sending the aforementioned COF parameters during Alias creation / usage will lead to a more flexible Alias usability. This will allow the merchant to re-use a CIT-created Alias in a subsequent MIT.