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:

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Field

Description

FormatMandatory
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

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.

FAQs

In your Worldline account menu, you can easily lookup your transactions by choosing "Operations" and then clicking either "View transactions" or "Financial history", depending on the type of transaction results you're looking for.

Go to Consult your transactions for more information.

By default you can send goods or deliver your service once a transaction has reached the status "9 - Payment requested". However, although status 5 is a successful status, it's only a temporary reservation of an amount of money on the customer's card. A transaction in status 5 still needs to be confirmed (manually or automatically) to proceed to the status 9, which is the final successful status for most payment methods.

Go to Transaction statuses for more information.

You can easily refund a payment with the "Refund" button in the order overview of a transaction (via View transactions). If your account supports it, you can also make refunds with a DirectLink request or with a Batch file upload (for multiple transactions).

Please note that the Refunds option has to be enabled in your account.

Go to Maintain your transactions for more information.

If you want to check specific details of an order/transaction or perform maintenance on transactions, you should use View transactions. "Financial history" is the most convenient to periodically check incoming and outgoing funds.

For more information, go to View transactions vs Financial history.

You can only perform refunds on transactions which have already received status 9 for at least 24 hours. A cancellation or deletion can be done within approximately 24 hours after final status has been received (status 9 or 5).

To know the cut-off time of the acquirer, we recommend you to check directly with our Customer Care department.