1. Home
2. Integration Solutions
3. Recurring Payments
4. Alias Gateway

1. Introduction

Alias Gateway enables you to post transactions to the Worldline platform by using a payment page built by yourself:

1. Alias Gateway: You submit the card data to our system, where it is securely stored (including the CVC, but for a limited time only)
2. DirectLink: You submit the actual order, without needing to submit the card data.

Advantages:

• You have full control over the look & feel of the payment page, including the check-out sequence.
• Worldline is completely invisible in the payment process.
• Seamless integration for various checkout scenarios including One Page Checkout.
• You can offer upselling and cross-selling on the final checkout page.
• All major credit card brands (VISA, MasterCard, American Express, Diners) are supported, as well as Direct Debits and PostFinance Card.

2. Implementation scenario

Note: No operation is performed on the card in the first step. Our system simply performs a basic format validation, but cannot guarantee that the card is still valid, or has sufficient funds to proceed.

3. Step 1: Alias Gateway

To use One Page Checkout, you must construct a web page containing a form that does NOT send data to your own website but directly to the Worldline page. In this way, the card details never pass through your own web server.

The URLs for the Alias Gateway are:

• https://ogone.test.v-psp.com/ncol/test/alias_gateway.asp for Test
• https://secure.ogone.com/ncol/prod/alias_gateway.asp for Production

Note: The Alias Gateway will use the character encoding specified in the “Global security parameters” tab of your account's Technical information page. You can enforce the usage of UTF-8 by calling the "Alias_gateway_utf8.asp" page. The character encoding is preserved in all subsequent redirections and responses.

Important It is extremely risky to send credit card information to your own website, both from a security as well as a legal perspective! Please ensure that the data is always sent only to the Worldline platform.

3.1 Input fields

The form can or must contain the following parameters:

Field	Description	Format	Mandatory
ACCEPTURL	URL for redirection in the event of success	AN, 255	Yes
ALIAS	Customer alias	AN, 50	No
ALIASPERSISTEDAFTERUSE	This parameter should only be used in combination with Alias Manager. 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.	Y / N	No
BRAND	Card brand	AN, 25	Credit cards: No Direct Debits, PostFinance Card: Yes
CARDNO	Card/account number	AN, 35	Credit cards, Direct Debits: Yes PostFinance Card: n/a
CN	Cardholder's name	AN, 50	Credit cards, Direct Debits: Yes PostFinance Card: No
CVC	Card Verification Code	AN, 6	Credit cards: Yes Direct Debits, PostFinance Card: n/a
ECOM_CARDINFO_EXPDATE_MONTH*	Expiry month	N, 2 (MM)	Credit cards: Yes Direct Debits: n/a PostFinance Card: No
ECOM_CARDINFO_EXPDATE_YEAR*	Expiry year	N, 4 (YYYY)	Credit cards: Yes Direct Debits: n/a PostFinance Card: No
ED*	Expiry date	N, 4 (MMYY)	Credit cards: Yes Direct Debits: n/a PostFinance Card: No
EXCEPTIONURL	URL for redirection in the event of error	AN, 255	Yes
LANGUAGE	Language of the card holder (e.g. de_CH, en_US, etc.)	AN, 5	Credit cards, Direct Debits: No PostFinance Card: Yes
ORDERID	Order identification	AN, 40	Yes
PARAMPLUS	Additional parameters to be sent by the merchant	AN, 1000	No
PSPID	Merchant's identification	AN, 30	Yes
SHASIGN	SHA hash calculation (security feature)	AN, 128	Yes

_{* You can choose whether to send the expiry date in a single field (ED) or in two fields; both formats are supported. If both are submitted, the “ED” field will prevail.}

Notes:

• If any of the mandatory input fields, e.g. ED (expiry date), contain no or invalid data, no alias will be returned.
• All parameters are hidden, except those that have to be filled in by the cardholder: CN, CARDNO, CVC and ED

3.1.1 SHA Signature for input

To check the integrity of the data, we require all requests to be accompanied by an SHA signature, in the same way as for Hosted Payment Page transactions. For more information about SHA signatures and how to generate them, go to Hosted Payment Page.

Our system will use the SHA algorithm as defined in the Global security parameters tab of your Technical information page.

Note: As you don't have the card details (CARDNO, CN, CVC, ED) at your disposal, which is the underlying reason for the Alias Gateway, these parameters should of course NOT be included in the SHA. You can choose whether or not to submit the parameter BRAND in the form. If the BRAND is submitted, it has to be included in the SHA calculation.

Example:

• Fields (in alphabetical order):
  
  • ACCEPTURL: https://www.myshop.com/ok.html
  • EXCEPTIONURL: https://www.myshop.com/nok.html
  • PSPID: test1
• Secret passphrase (as defined in Technical information): Mysecretsig1875!?
• String to hash: ACCEPTURL=https://www.myshop.com/ok.htmlMysecretsig1875!?EXCEPTIONURL=https://www.myshop.com/nok.htmlMysecretsig1875!?PSPID=test1Mysecretsig1875!?
• Resulting SHA signature (SHA-1): 0F3455990D4859E20FD2B9F7B326304549DE6069

3.1.2 Direct Debits

If you use the Alias Gateway and Direct Debits (DE, NL and/or AT):

• The account number (regular or IBAN) has to be sent with the CARDNO field.
• When relevant, the BIC (bank code) must be sent with the same parameter: BIC
• The BRAND input field must contain either 'Direct Debits NL', 'Direct Debits DE' or 'Direct Debits AT'.
• The expiry date and CVC fields should be left empty.

3.1.3 Maestro and Bancontact

If you have both the Maestro and Bancontact payment methods activated in your account, you need to send the BRAND parameter if you want the correct brand value to be returned accordingly in the output/feedback fields.

If you don't send the BRAND parameter, Worldline will consider a Belgian Maestro card as a Bancontact card.

3.1.4 PostFinance Card

When using PostFinance Card, note that the process is slightly different, as the cardholder will be prompted to authenticate himself when the alias is created.

The LANGUAGE and AMOUNT fields are mandatory. The minimum amount is CHF / EUR 0.05.

3.1.5 Split credit/debit cards

The functionality to split VISA and MasterCard into a debit and a credit payment method allows you to offer them to your customers as two different payment methods (e.g. VISA Debit and VISA Credit), or you can decide only to accept one of both split brands.

To use the split of credit and debit cards via, you need to include the CREDITDEBIT parameter in the fields that you send to the alias_gateway.asp page (and therefore also include in the SHA-IN calculation!).

Field	Format
CREDITDEBIT	"C": credit card "D": debit card

Related error: When the buyer selects the debit card method but next enters a credit card number, an error code will be returned: ‘Wrong brand/Payment method was chosen’.

If the payment is successfully processed with the CREDITDEBIT parameter, the same parameter will also be returned in the DirectLink XML response. However, whereas the submitted values are C or D, the return values are "CREDIT" or "DEBIT".

You will also find these return values in transaction overview via "View transactions" and "Financial history", and in reports you may download afterwards.

Configuration in your account The split functionality can also be activated and configured per payment method, in your Worldline account. Go to Split Credit/Debit Cards for more information.

3.2 Pass-through fields

In addition to the input data, you may also submit supplementary fields; these will not be stored in our system, but will be appended to the redirection URLs so that you can re-use them in your order process. These fields are known as “pass-phrough" fields.

Note:

• These fields should NOT be included in the SHA signature.
• These fields are not supported in combination with PostFinance Card; we recommend to use PARAMPLUS instead (cf. Input parameters)

3.3 Output fields

Our system will append the following parameters to the Return URL (ACCEPTURL or EXCEPTIONURL) in order to provide you with feedback on the operation:

Field	Description	Max Length
ALIAS	Generated alias. According to the 32 digit GUID format. Example: 34F5302C-85D7-4F35-BDF5-103CCEC2FB61	50
ALIASPERSISTEDAFTERUSE	This parameter should only be used in combination with Alias Manager. 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.	1 (Y / N)
BIC	The Bank Identifier Code A value is returned only if initially submitted, i.e. not derived from the IBAN Only relevant for Direct Debits	11
BRAND	Brand of the payment method	25
CARDNO	Card/Account number (regular or IBAN), with Xs to replace sensitive information. Example: XXXXXXXXXXXX1111 Note: In the event of an error, the card/account will also be masked.	35
CN	Card/Account holder name	50
CVC	Card Verification Code for credit cards, with Xs to replace sensitive data. Example: XXX	6
ED	Expiry date, e.g. 0216 (for February 2016) Only relevant for credit cards and PostFinance Card	4
LANGUAGE	Language of the card holder (e.g. de_CH, en_US, etc.)	5
NCERROR	Error code	50
NCERRORCARDNO	Error code for CARDNO	50
NCERRORCN	Error code for CN	50
NCERRORCVC	Error code for CVC Only relevant for credit cards	50
NCERRORED	Error code for ED Only relevant for credit cards and PostFinance Card	50
ORDERID	The unique identifier of the order. This must be sent in the event of a retry, so we can match them with the aliases (card/CVC) The ORDERID is generated automatically and is numeric.	40
SHASIGN	SHA signature for output	128
STATUS	Result of the alias creation: 0=OK 1=NOK 2=Alias updated 3=Cancelled by user	1
(more)	Pass-through fields + fields contained in PARAMPLUS	/

3.3.1 SHA Signature for output

Our system will return an SHA-OUT signature, in the same way as for Hosted Payment Page transactions, for the following parameters:

ALIAS
BIC
BRAND
CARDNO
CN
CVC
ED
NCERROR
NCERRORCARDNO
NCERRORCN
NCERRORCVC
NCERRORED
ORDERID
STATUS

3.4 Resubmission

When resubmitting data (e.g. because the first attempt was unsuccessful), the cardholder does not have to re-enter previously validated details.

E.g. if the card number is OK, then the browser will submit the “X-ed” card number, and our system will match it with the one stored for the previous request.

To achieve this, you must submit the ORDERID with every request. The same ORDERID is sent back every time. If no ORDERID is submitted, one will be generated by our system. If a new ORDERID is used, the error 5555554 will be returned.

3.5 Error messages

The following error messages may be returned by the Alias Gateway:

NCERROR	Description
5555554	Incorrect ORDERID (after resubmission)
55555555	General error
50001184	SHA-IN mismatch
50001186	*Operation not allowed (when an ORDERID is sent for which an alias already exists)
50001187	*Operation not allowed (when an alias is sent that already exists)
50001300	Wrong brand specified (Direct Debits)
50001301	Wrong bank account format (Direct Debits)
NCERRORCN
60001057	Name is missing
50001174	Name is too long
NCERRORCARDNO
30141001	Invalid card number
50001069	Brand and card number do not match
50001176	Card number is too long
50001177	Card number contains non-numeric info
50001178	Card number too short/empty
NCERRORCVC
50001090	CVC missing or too short
50001179	CVC too long
50001180	CVC contains non-numeric information
NCERRORED
50001181	Expiry date contains non-numeric information
50001182	Invalid expiry month
50001183	Expiry date must be in the future
31061001	Expiry date empty or wrong format

4. Step 2: DirectLink

To use the Alias generated with the Alias Gateway, you must submit the ALIAS parameter with a transaction via DirectLink using our standard DirectLink implementation.

This mechanism is also compatible with DirectLink with 3-D Secure.

For more information about Alias usage, go to Alias Manager.

5. Alias update using Alias Gateway

The Alias Gateway can also be used to update existing aliases, using the same input fields as for the alias creation.

Note: If you want to simply update the cardholder name, it is not sufficient to only supply the new name and the existing alias; The X-ed card number must also be sent in the CARDNO field. The CVC is not necessary.

In the response, the STATUS output field will inform the merchant of the alias update (status 2).

Result of the alias creation:

• 0 OK
• 1 Not OK
• 2 Alias Updated

For more information, go to Alias Manager.