Last update 11/02/2016

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 Ingenico ePayments 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 Ingenico ePayments 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

    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 e-Commerce transactions. For more information about SHA signatures and how to generate them, go to e-Commerce.

    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, Ingenico ePayments 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 Ingenico ePayments 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 e-Commerce 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

    This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

    Cookie settings

    Introduction

    Functional

    Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

    Optimized

    Optimization cookies allow us to analyze site usage so we can measure and improve our website.
    This is the default level.

    Personalized

    Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


    Example functionality allowed

    • Store country preference
    • Store language preference

    Example functionality not allowed

    • Saving personal data
    • Anonymous tracking via Google Analytics
    • Tracking for remarketing purposes

    Example functionality allowed

    • Store country preference
    • Store language preference
    • Anonymous tracking via Google Analytics

    Example functionality not allowed

    • Saving personal data
    • Tracking for remarketing purposes

    Example functionality allowed

    • Store country preference
    • Store language preference
    • Anonymous tracking via Google Analytics
    • Serve content relevant to your interests
    • Serve ads relevant to your interests
    • Tracking for remarketing purposes

    Example functionality not allowed

    • Saving personal data