Last update 24/07/2018

3. Request a new order

3.1 Request URL

  • The request URL in the TEST environment is https://ogone.test.v-psp.com/ncol/test/orderdirect.asp.
  • The request URL in the PRODUCTION environment is https://secure.ogone.com/ncol/prod/orderdirect.asp.

Change "test" to "prod"

Replace “test” with “prod” in the request URL when you switch to your production account. If you forget to change the request URL, once you start in production with real orders, your transactions will be sent to the test environment and will not be processed by the acquirers/banks.

3.2 Request parameters

The following table contains the request parameters for sending a new order request:

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Field Description Format Mandatory
PSPID
Your affiliation name in our system.
AN, 30
Yes
ORDERID
Your unique order number (merchant reference).
AN, 40
Yes
USERID
Name of your application (API) user. Please refer to the User Manager documentation for information on how to create an API user.
AN, 20 (min 2)
Yes
PSWD
Password of the API user (USERID).
AN
Yes
AMOUNT
Amount to be paid, MULTIPLIED BY 100 as the format of the amount must not contain any decimals or other separators.
N, 15 Yes
CURRENCY
ISO alpha order currency code, for example: EUR, USD, GBP, CHF, etc.
AN, 3 Yes
CARDNO
Card/account number.
AN, 21
Yes
ED
Expiry date.
MM/YY or MMYY
Yes
COM
Order description.
AN, 100
No
CN
Customer name.
AN, 35
No
EMAIL
Customer’s email address.
AN, 50
No
SHASIGN
Signature (hashed string) to authenticate the data (see SHA-IN Signature).
AN, 128
Yes
CVC
Card Verification Code. Depending on the card brand, the verification code will be a 3- or 4-digit code on the front or rear of the card, an issue number, a start date or a date of birth.
N, 5
Yes
ECOM_PAYMENT_
CARD_VERIFICATION
Alternative to CVC: date of birth / issue number / etc. (depending on country/bank)
N, 5
No
OWNERADDRESS
Customer’s street name and number.
AN, 50
No
OWNERZIP
Customer’s postcode.
AN, 10
No
OWNERTOWN
Customer’s town/city name.
AN, 40
No
OWNERCTY
Customer’s country, e.g. BE, NL, FR, etc.
AN, 2 No
OWNERTELNO
Customer’s telephone number.
AN, 30
No
OPERATION

Defines the type of requested transaction.

You can configure a default operation (payment procedure) in the "Global transaction parameters" tab, "Default operation code" section of the Technical Information page. When you send an operation value in the request, this will overwrite the default value.

Possible values:
  • RES: request for authorization
  • SAL: request for direct sale
  • RFD: refund, not linked to a previous payment, so not a maintenance operation on an existing transaction (you can not use this operation without specific permission from your acquirer).

Optional:

  • PAU: Request for pre-authorization:
      In agreement with your acquirer you can use this operation code to temporarily reserve funds on a customer's card. This is a common practice in the travel and rental industry.
      PAU/pre-authorization can currently only be used on MasterCard and Visa transactions and is supported by selected acquirers. This operation code cannot be set as the default in your Ingenico ePayments account.
      Should you use PAU on transactions via acquirers or with card brands that don't support pre-authorization, these transactions will not be blocked but processed as normal (RES) authorizations.
A, 3
Yes
WITHROOT
Adds a root element to our XML response. Possible values: ‘Y’ or empty.
Y or <empty>
No
REMOTE_ADDR
Customer's IP address (for Fraud Detection Module only). If a country check does not need to be performed on the IP address, send 'NONE'.
AN
No
RTIMEOUT

Request timeout for the transaction (in seconds, value between 30 and 90)

Important: The value you set here must be smaller than the time out value in your system (!)

 

N, 2
No
ECI

Electronic Commerce Indicator.

You can configure a default ECI value in your account's Technical information page, "Global transaction parameters" tab, "Default ECI value" section. When you send an ECI value in the request, this will override the default ECI value.

Possible (numeric) values:
0 - Swiped
1 - Manually keyed (MOTO) (card not present)
2 - Recurring (from MOTO)
3 - Instalment payments
4 - Manually keyed, card present
7 - E-commerce with SSL encryption
9 - Recurring (from e-commerce)
N, 2
No

COF_INITIATOR           Credential-on-file initiator
Possible values:
  • CIT: A transaction initiated by a cardholder
  • MIT: A transaction initiated by a merchant                                                                                                                  
AN          No             
COF_SCHEDULE  Credential-on-files scheduled (or unscheduled)
Possible values:
  • SCHED: A scheduled transaction
  • UNSCHED: An unscheduled transaction
AN No
COF_TRANSACTION Credential-on-file transaction
Possible values:
  • FIRST: A scheduled transaction
  • SUBEQ: Subsequent series of transaction 
AN No
The list of possible parameters to send can be longer for merchants who have activated certain options/functionalities in their accounts. Please refer to the respective option documentation for more information on extra parameters linked to the option.

The following request parameters are mandatory in new orders:

  • PSPID and USERID
  • PSWD
  • ORDERID
  • AMOUNT (x 100)
  • CURRENCY
  • CARDNO
  • ED
  • CVC
  • OPERATION 

3.3 Test page

Our test page to send order requests in DirectLink can be found here: https://ogone.test.v-psp.com/ncol/test/testodl.asp.

3.4 Excluding specific payment methods

If there are payment methods you don't want a customer to be able to pay with, you can use a parameter to do so.
This is particularly useful for sub-brands, when you want to accept a brand (e.g. MasterCard) but not one of its sub-brands (e.g. Maestro).

The parameter is the following:

Field Usage
EXCLPMLIST
List of payment methods and/or credit card brands that should NOT be used.
Values must be separated by a “;” (semicolon).

If a customer tries paying with a card linked to a payment method and/or (sub)brand thT you've excluded BY using the EXCLPMLIST parameter, the error message “Card number incorrect or incompatible” will be returned with the NCERRORPLUS return field.

3.5 Order request using 3-D Secure

Our system supports the usage of 3-D Secure with DirectLink.

Important

  • If you wish to use 3-D Secure with DirectLink, you need to have the D3D option activated in your account.
  • Some acquiring banks require the use of 3-D Secure. Please check with your acquirer if this is the case for you.

3.6 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 DirectLink, you need to include the CREDITDEBIT parameter in the fields that you send to the orderdirect.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 XML response, and/or can be requested with a Direct Query. 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.7 Processing transactions with stored credentials

Credential-on-file (COF) transaction uses existing card details that are already stored by merchants to process the payment. Before initiating a credential-on-file (COF) transaction, the cardholder will first need to authorize the merchant to store the card details. Credential-on-file (COF) mostly applies to recurring payments and states whether the payment is initiated by a cardholder or merchant.

There are two types of credential-on-file (COF) transactions: cardholder-initiated transaction (CIT) or merchant-initiated transaction (MIT). Cardholder-initiated transaction (CIT) will always need to take place before initiating merchant-initiated transaction (MIT).

A cardholder-initiated transaction (CIT) is a transaction where the cardholder is involved in the transaction and personally authenticates the transaction, by means of a signature, 3D-Secure appliance, or presenting IDs.

Example of a cardholder-initiated transaction (CIT):

A cardholder buys a train ticket online and makes a payment. He/She makes the payment with his/her credit card and is being asked to authenticate and authorize the payment. At the same, the cardholder is also asked if he/she wants to save the credit card information related to this payment. If the cardholder agrees, this information can then be re-used in future transactions initiated by the merchant.

A merchant-initiated transaction (MIT) is a transaction initiated by a merchant that acts as a follow-up to a cardholder-initiated transaction (CIT) and a pre-agreed standing order for goods and services purchased by the cardholder. The cardholder does not have to be involved in the transaction.

Example of a merchant-initiated transaction (MIT):

A merchant can automatically initiate a transaction to fulfill a cardholder’s payment on a monthly magazine subscription.

In compliance with the regulations set by Visa and MasterCard for credential-on-file (COF) transaction, new parameters need to be sent to determine the COF transaction.

Impacted if:

  • You are using an Alias
  • You plan to initiate recurring transactions (scheduled or not) after initiating a cardholder-initiated transaction (CIT) for the first time

Required action

By default, these parameters are used in a DirectLink Server-to-Server transaction:

Parameters

Description

CIT-FIRST- UNSCHEDULED
Applies when an alias is used or created
CIT-FIRST- SCHEDULED

Applies to a first scheduled payment/subscription

MIT-SUBSEQUENT-UNSCHEDULED Applies when an alias is used or created
MIT-SUBSEQUENT-SCHEDULED Applies to installment

The default values are flagged if you don't add any parameters. However, if you want to change it, you can overwrite these default values by sending the new parameters. Do not forget to recalculate the SHA signature as well (click here for more information about SHA signature).

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

SUBEQ

Subsequent series of transactions

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