1. Home
2. Integratie- oplossingen
3. Integraties
4. e-supply advanced

The Advanced e-Supply Integration Guide provides other possible modes for submitting purchasing card transactions (Batch, DirectLink and e-Commerce). This document complements the Basic e-Supply User Guide. Please refer to the individual submission mode technical integration guides for general information.

While as the Basic e-Supply User Guide provides information about the basic e-Supply features on configuring your account and a step-by-step guide on submitting transactions manually in the Back Office.

1. Overview

The purchasing card transaction submission modes described in this documentation are:

• Batch: submission of text files containing one or more transactions (manual or automatic).
• DirectLink: a server-to-server request per transaction.
• e-Commerce: submission mode where the card details are entered online by the customer on our secure server.

The following section contains an overview of the various transaction submission modes for new orders and maintenance transactions, indicating their possible information levels (I or III). You can send additional data (Line Item Details) for purchasing card transactions if your acquirer supports level III information.

		New Order		Maintenance
	Authorization	Direct Sale	Refund (credit note)	Data Capture
Back Office (manual)	Level I & III	Level III	Level III	Level III
Batch (manual & automatic)	Level I & III	Level III	Level III	Level III
DirectLink	Level I	Level III	Level III	Level III
e-Commerce	Level I	-	-	-

When submitting a new order, you can decide to work in two stages (authorization followed by subsequent data capture) or in a single step (direct sale).
If you decide to work in two steps, your transaction flow will be as follows:

2. Submission Mode Batch

You can also use Batch mode to send maintenance requests. Data captures and refunds (credit notes) need to be sent with level III information.

	New Order		Maintenance
Authorisation	Direct Sale	Refund (credit note)	Data Capture
Level I	Level III	Level III	Level III

Please refer to the Advanced Batch manual for information on headers, footers, etc.

2.1 General rules

The structure and format of e-Supply payment files should comply with a few basic rules:

1. File: The file should be an ASCII text file.
2. Order: There are several lines per invoice/order (except for transactions without Line Item Details). The lines need to be separated by the Carriage Return and Line Feed characters (ASCII : 13 10 – HEX : 0xD 0xA).
3. Line: Each line must contain relevant fields (corresponding to the TYPE record) separated by a semicolon (“;”)
4. Fields: The fields themselves cannot contain any semicolon (“;”)
5. File structure: The file can include several invoices/orders. Each invoice/order contains several records:

Level I

• INV: Invoice/Order Header record (1 INV record per invoice/order)

Level III

• INV: Invoice/Order Header record (1 INV record per invoice/order)
• CLI: Customer details record (Optional, 0 or 1 CLI record per invoice/order)
• DET: Invoice/Order Line Item details records (1 to x DET records per invoice/order)

Example:

Header
INV ;….. ;
DET;…..;
DET;…..;
DET;…..;
INV ;….. ;
CLI;……;
DET;…..;
INV ;….. ;
DET;…..;
DET;…..;
……
Footer

2.2 File fields

2.2.1 General layout

The following table illustrates all possible fields for a standard purchasing card batch file. Of course, these fields should not be used all together.
Please use this table as a reference for field details. In the following sections we will list the required fields per operation.

INV Record

Field (# / content)	Source	Format / Max Length / Example
1 / Identifier of the INV record type or amount including tax (* 100 to avoid decimals)	-	INV or N 3 or 12 INV 121000
2 / Currency Unit (alphabetic ISO code)	Supplier	A 3 EUR
3 / Card type/brand	Client	AN 25 VISA PC
4 / Card number	Client	N 20 (Amex: 15) 374291019071995
5 / Card expiry date	Client	MMYY 4 0915
6 / Invoice number / credit note number	Supplier	AN 15 (Amex: 12) 2009-0000568
7 / Client reference 1. Can be client order reference or other data	Client	AN 20 YUJ7885
8 / Cardholder name	Client	AN 35 (Amex: 20) John Doe
9 / Worldline identifier/ref (PAYID) for the authorisation/settlement, stored by the supplier	Worldline	N 12 12759645
10 / Operation Code Possible values for new orders: RES: request for authorisation SAL: request for direct sale (payment) RFD: refund (credit note) Possible values for maintenance: SAL: partial data capture (payment), leaving the transaction open for a possible further data capture SAS: (last) partial or full data capture (payment), closing the transaction for further data captures	Supplier	AN 3 SAL
11 / Authorisation code, not received via our system	Supplier	AN 15  759642
12 / Authorisation mode: the way in which the authorisation code in field 11 was received	Supplier	AN 3 TEL (Telephone)
13 / Authorisation date/time: the date/time when the authorisation code in field 11 was received	Supplier	MM/DD/YY hh:mm:ss 17 12/26/09 14:02:56
14 / PSPID of the Worldline Supplier (login name)	Supplier	AN 30 TESTCPC
15 / Supplier order identifier/ref for the authorisation/settlement, stored by the supplier	Supplier	AN 15 AB4568TR
16 / Number of DET records in the file for this transaction	Supplier	N 4 2
17 / Cardholder Alias (if configured in the Worldline account)	Supplier	AN 15 BennyB
18 / Client ID: identifier of the client company, as defined in the Worldline> account	Supplier	AN 20 PEUGEOT
19 / Original invoice number corresponding to the credit note	Supplier	AN 15 (Amex: 12) 17358948
20 / Blank field	...	...
21 / Client reference 2. Can be cardholder order reference or other data	Client	AN 16 Order 06/09/11
Blank fields	...	...
27 / CVC/CVV2: Card Verification Code. Usually not used or inexistent for purchasing cards.	Client	N 4 123
28 / Order/Invoice date to appear in bank files. Current date by default	Supplier	MM/DD/YY 8 06/23/15
29 / Order Number corresponding to the invoice	Supplier	AN 15 4358
30 / Invoice Level Discount rate Do not use % This discount rate will be stated in the item name in the order details. The invoice level discount rate will be added to the item level discount rate: “Item name (- (INVdiscount + DETdiscount) %)” We do not use this discount rate to calculate order amounts. The amounts you send us must already include the discount.	Supplier	N xx.xx 5 05.00 (Item name "Scissors" will be "Scissors (-5%)')
31 / Client reference 3. Can be customer number or other data.	Client	AN (Amex: 12) 73TO45
32 / Total Invoice amount (VAT excl.). Calculated with sent line item details. (* 100 to avoid decimals).	Supplier	N 12 100000
33 / Total Invoice VAT amount. Calculated with sent line item details. (* 100 to avoid decimals).	Supplier	N 12 21000
34 / Total Invoice amount (VAT incl.) Calculated with sent line item details. (* 100 to avoid decimals)	Supplier	N 12 121000

The CLI record is optional, as the client configuration is stored in the <%COMPANY%> Back Office. If you do want to enter address fields in the CLI record, the whole address should be completed for it to be taken into account (name, first name, street, postcode, city, country).

CLI Record

Field (# / content)	Source	Format / Max. length / Example
1 / Identifier of the CLI (Client) record type.	-	CLI 3 CLI
2 / Cost Centre with which the order is associated	Client	AN 20 Y567K8
3 / VAT Number of the Client company (without separators)	Client	AN 20 123456789
4 / Delivery name	Client	AN 35 Doe
5 / Delivery first name	Client	AN 35 John
6 / Delivery address line1	Client	AN 35 1st Avenue 1
7 / Delivery address line2	Client	AN 35 Building 123
8 / Delivery postcode	Client	AN 10 1000
9 / Delivery town	Client	AN 25 Brussels
10 / Delivery country code (alphabetic ISO code)	Client	A 2 BE
11 / Billing name	Client	AN 35  John
12 / Billing first name	Client	AN 35 Smith
13 / Billing address line 1	Client	AN 35 1st Avenue 1
14 / Billing address line2	Client	AN 35 Building 123
15 / Billing postcode	Client	AN 10 1000
16 / Billing town	Client	AN 25 Brussels
17 / Billing country code (alphabetic ISO code)	Client	A 2 BE
18 / Cardholder e-mail address	Client	AN 50 name@youremail.com
19 / Phone Number	Client	AN 20 +32 1 23 45 56 89
20 / Fax Number	Client	AN 20 +32 1 23 45 56 89

DET Record

Field (# / content)	Source	Format / Max. length / Example
1 / Identifier of the DET (details) record type	-	DET 3 DET
2 / Quantity Max. 2 decimals supported	Order	N xxxx.xx 12 52
3 / Item ID/Code	Order	AN 15 U419-52
4 / Item description/name Sent to the bank and available on the client’s statements	Order	AN 40 HP710C Cartridge
5 / Item unit price 4 decimals supported, but * 100 to use cents, which gives max. 2 decimals	Order	N xxxx.xx 12 5355
6 / VAT flag: 0 (VAT not included in Unit Price) or 1 (VAT included)	Order	N 1 0
7 / VAT rate or internal VAT code (0, 1, 2, etc. see VAT configuration in <%COMPANY%> account)	Order	N xxxx.xx or x 6 19.6%
8 / Line item reference 1 Can be a unit of measure or other data (Although American Express accepts a field length of 12, <%COMPANY%> only allows 10)	Client	AN 10 Piece
9 / Line item reference 2 Can be commodity code or other data	Client	AN 12 (Amex: 8) TY1627
10 / Item internal description Not sent to bank or client, just available in the back-office.	Supplier	AN 255 Black HP catridge
Blank fields	...	...
13 / Item Discount Rate Do not use % This discount rate will be stated in the item name in the order details. The item level discount rate will be added to the invoice level discount rate: “Item name (- (DETdiscount + INVdiscount) %)” We do not use this discount rate to calculate order amounts. The amounts you send us must already include the discount.	Supplier	N xxxx.xx 5 02.00 (Item name “Scissors” will be “Scissors (-2%)”)
14 / Total Line amount (excl. VAT) (* 100 to avoid decimals).	Supplier	N 12 15000

2.3 Required fields for new transactions_orders

The following section lists the minimum fields we recommend you to use. Your client and/or acquirer may also possibly request you to provide other specific fields of the layout in addition to the ones listed here, e.g. Client references, line item references.

2.3.1 Authorisation

The minimum fields we recommend you use for a level I authorisation are:

Authorisation (Level I, RES)
INV
(1) Amount tax included
(2) Currency
(4) Card number
(5) Card expiry date
(10) Operation code
(14) PSPID
(18) Client ID
(29) Order number

Example:

Level I authorisation

Example:

Level III authorisation without invoice number
INV;EUR;;374291019071995;0514;;;John Doe;;RES;;;;GFR5oes;;2;;FORD;;;;;;;;;;06/30/08;OH74988;;;21000;4410;25410;
DET;10;5634;Scissors;200;0;21%;;;;;;;2000
DET;10;5635;HP720c printer cartridge;1900;0;21%;;;;;;;19000

2.3.2 Direct sale Level III

The minimum fields we recommend you to use for a level III direct sale are:

Direct sale (Level III, SAL)
INV	DET
(1) INV identifier	(1) DET identifier
(2) Currency	(2) Quantity
(4) Card number	(3) Item ID/code
(5) Card expiry date	(4) Item description/name
(6) Invoice number	(5) Item unit price
(10) Operation code	(6) VAT flag
(14) PSPID	(7) VAT rate or internal VAT code
(16) number of DET records	(14) Total line amount (excl. VAT)
(18) Client ID
(29) Order number
(32) Total invoice amount (excl. VAT)
(33) Total invoice VAT amount
(34) Total invoice amount (incl. VAT) INV 4-5 are optional if you use field 17 Cardholder Alias

Example:

Level III direct sale
INV;EUR;;374291019071995;0514;7845968574;;John Doe;;SAL;;;;GFR5oes;;2;;FORD;;;;;;;;;;06/30/08;OH74988;;;21000;4410;25410;
DET;10;5634;Scissors;200;0;21%;;;;;;;2000
DET;10;5635;HP720c printer cartridge;1900;0;21%;;;;;;;19000

• (11) Authorisation code
• (12) Authorisation mode
• (13) Authorisation date / date

Example:

Level III direct sale (authorisation received outside Worldline)
INV;EUR;;374291019071995;0514;7845968574;;John Doe;;SAL;52485;TEL;06/29/08 14:12:30;GFR5oes;;2;;FORD;;;;;;;;;;06/30/08;OH74988;;;21000;4410;25410;
DET;10;5634;Scissors;200;0;21%;;;;;;;2000
DET;10;5635;HP720c printer cartridge;1900;0;21%;;;;;;;19000

2.3.3 Refund_credit note Level III

The minimum fields we recommend you to use for a credit note are:

Refund (credit note): Level III, RFD
INV	DET
(1) INV identifier	(1) DET identifier
(2) Currency	(2) Quantity
(4) Card number	(3) Item ID/code
(5) Card expiry date	(4) Item description/name
(6) Credit note number	(5) Item unit price
(10) Operation code	(6) VAT flag
(14) PSPID	(7) VAT rate or internal VAT code
(16) number of DET records	(14) Total line amount (excl. VAT)
(18) Client ID
(19) Original invoice number corresponding to the credit note (mandatory for the de-materialization of invoices)
(29) Order number
(32) Total invoice amount (excl. VAT)
(33) Total invoice VAT amount
(34) Total invoice amount (incl. VAT) INV 4-5 are optional if you use field 17 Cardholder Alias

Example:

Refund (credit note)
INV;EUR;;374291019071995;0514;C58945743;;John Doe;;RFD;;;;GFR5oes;;2;;FORD;;;;;;;;;;06/30/08;OH74988;;;21000;4410;25410;
DET;10;5634;Scissors;200;0;21%;;;;;;;2000
DET;10;5635;HP720c printer cartridge;1900;0;21%;;;;;;;19000

2.4 Required fields for maintenance operations

Maintenance operations are based on transactions (orders) that have been entered in our system. As the details of the original transaction are logged in our system, you do not have to repeat specific details such as the card number and expiry date. Instead, you should refer to the original transaction using its PAYID. Information you send us in maintenance transactions will overwrite any contrary corresponding information in the original transaction, except for the card number and the currency. The following section lists the minimum fields we recommend you to use. Your client and/or acquirer may also possibly request you to provide other specific fields in the layout, in addition to the ones listed here, e.g. Client references, line item references, etc.

2.4.1 Data capture Level III

The minimum fields we recommend you to use for a data capture are:

Data capture: Level III, SAL/SAS
INV	DET
(1) INV identifier	(1) DET identifier
(2) Currency	(2) Quantity
(6) Invoice number	(3) Item ID/code
(9) Initial authorisation PAYID	(4) Item description/name
(10) Operation code	(5) Item unit price
(14) PSPID	(6) VAT flag
(16) number of DET records	(7) VAT rate or internal VAT code
(18) Client ID	(14) Total line amount (excl. VAT)
(33) Total invoice VAT amount	(34) Total invoice amount (incl. VAT)

Example:

Data capture
OHF;;MTR;SAS;1;
INV;EUR;;;;7845968574;;;82759845;SAS;;;;GFR5oes;;2;;FORD;;;;;;;;;;;;;;21000;4410;25410;
DET;10;5634;Scissors;200;0;21%;;;;;;;2000
DET;10;5635;HP720c printer cartridge;1900;0;21%;;;;;;;19000
OTF

2.5 Field usage overview

M = mandatory, A = advised, O = optional, / = not applicable

INV record ATR (new transactions): Authorisation (RES) Level I // III

Field	RES (I)	RES (III)
1 INV Identifier/Amount	M (amount)	M (INV)
2 Currency unit	M	M
3 Card type/brand	O	O
4 Card number	M	M
5 Card expiry date	M	M
6 Invoice number / credit note number	/	/
7 Client reference 1	O	O
8 Cardholder name	O	O
9 PAYID of original transaction	/	/
10 Operation Code	A	A
11 Authorisation code	/	/
12 Authorisation mode	/	/
13 Authorisation date/time	/	/
14 PSPID	A	A
15 Supplier order identifier	/	/
16 Number of DET records	/	M
17 Cardholder Alias	O	O
18 Client ID	M	M
19 Original invoice number	/	/
21 Client reference 2	O	O
27 CVC/CVV2	O	O
28 Order/Invoice date	O	O
29 Order Number	M	M
30 Invoice Level Discount rate	/	O
31 Client reference 3	O	O
32 Total Invoice amount (excl. VAT )	/	A
33 Total VAT amount	/	A
34 Total Invoice amount (incl. VAT)	/	A

INV record ATR (new transactions): Direct Sale (SAL) / Refund (RFD) Level III

Field	SAL (III)	RFD (III)
1 INV Identifier/Amount	M (INV)	M (INV)
2 Currency unit	M	M
3 Card type/brand	O	O
4 Card number	M	M
5 Card expiry date	M	M
6 Invoice number / credit note number	M	M
7 Client reference 1	O	O
8 Cardholder name	O	O
9 PAYID of original transaction	/	/
10 Operation Code	A	A
11 Authorisation code	/	O
12 Authorisation mode	/	O
13 Authorisation date/time	/	O
14 PSPID	A	A
15 Supplier order identifier	/	/
16 Number of DET records	M	M
17 Cardholder Alias	O	O
18 Client ID	M	M
19 Original invoice number	/	/
21 Client reference 2	O	O
27 CVC/CVV2	O	O
28 Order/Invoice date	O	O
29 Order Number	M	M
30 Invoice Level Discount rate	O	O
31 Client reference 3	O	O
32 Total Invoice amount (excl. VAT )	A	A
33 Total VAT amount	A	A
34 Total Invoice amount (incl. VAT)	A	A

INV record MTR (maintenance transactions): (Last) data capture (SAL / SAS) Level III

Field	SAL/SAS (III)
1 INV Identifier/Amount	M
2 Currency unit	M
3 Card type/brand	O
4 Card number	M
5 Card expiry date	M
6 Invoice number / credit note number	M
7 Client reference 1	O
8 Cardholder name	O
9 PAYID of original transaction	M
10 Operation Code	A
11 Authorisation code	/
12 Authorisation mode	/
13 Authorisation date/time	/
14 PSPID	A
15 Supplier order identifier	O
16 Number of DET records	M
17 Cardholder Alias	O
18 Client ID	M
19 Original invoice number	/
21 Client reference 2	O
27 CVC/CVV2	O
28 Order/Invoice date	O
29 Order Number	O
30 Invoice Level Discount rate	O
31 Client reference 3	O
32 Total Invoice amount (excl. VAT )	A
33 Total VAT amount	A
34 Total Invoice amount (incl. VAT)	A

CLI record: all fields are optional, as the customer addresses should be completed in the <%COMPANY%> back office.

CLI record ATR (new transactions): Authorisation (RES) Level I // III

Field	RES (I)	RES (III)
1 INV Identifier/Amount	M (amount)	M (INV)
2 Currency unit	M	M
3 Card type/brand	O	O
4 Card number	M	M
5 Card expiry date	M	M
6 Invoice number / credit note number	/	/
7 Client reference 1	O	O
8 Cardholder name	O	O
9 PAYID of original transaction	/	/
10 Operation Code	A	A
11 Authorisation code	/	/
12 Authorisation mode	/	/
13 Authorisation date/time	/	/
14 PSPID	A	A
15 Supplier order identifier	/	/
16 Number of DET records	/	M
17 Cardholder Alias	O	O
18 Client ID	M	M
19 Original invoice number	/	/
21 Client reference 2	O	O
27 CVC/CVV2	O	O
28 Order/Invoice date	O	O
29 Order Number	M	M
30 Invoice Level Discount rate	/	O
31 Client reference 3	O	O
32 Total Invoice amount (excl. VAT )	/	A
33 Total VAT amount	/	A
34 Total Invoice amount (incl. VAT)	/	A

CLI record ATR (new transactions): Direct Sale (SAL) / Refund (RFD) Level III

Field	SAL (III)	RFD (III)
1 INV Identifier/Amount	M (INV)	M (INV)
2 Currency unit	M	M
3 Card type/brand	O	O
4 Card number	M	M
5 Card expiry date	M	M
6 Invoice number / credit note number	M	M
7 Client reference 1	O	O
8 Cardholder name	O	O
9 PAYID of original transaction	/	/
10 Operation Code	A	A
11 Authorisation code	/	O
12 Authorisation mode	/	O
13 Authorisation date/time	/	O
14 PSPID	A	A
15 Supplier order identifier	/	/
16 Number of DET records	M	M
17 Cardholder Alias	O	O
18 Client ID	M	M
19 Original invoice number	/	/
21 Client reference 2	O	O
27 CVC/CVV2	O	O
28 Order/Invoice date	O	O
29 Order Number	M	M
30 Invoice Level Discount rate	O	O
31 Client reference 3	O	O
32 Total Invoice amount (excl. VAT )	A	A
33 Total VAT amount	A	A
34 Total Invoice amount (incl. VAT)	A	A

CLI record MTR (maintenance transactions): (Last) data capture (SAL / SAS) Level III

Field	SAL/SAS (III)
1 INV Identifier/Amount	M
2 Currency unit	M
3 Card type/brand	O
4 Card number	M
5 Card expiry date	M
6 Invoice number / credit note number	M
7 Client reference 1	O
8 Cardholder name	O
9 PAYID of original transaction	M
10 Operation Code	A
11 Authorisation code	/
12 Authorisation mode	/
13 Authorisation date/time	/
14 PSPID	A
15 Supplier order identifier	O
16 Number of DET records	M
17 Cardholder Alias	O
18 Client ID	M
19 Original invoice number	/
21 Client reference 2	O
27 CVC/CVV2	O
28 Order/Invoice date	O
29 Order Number	O
30 Invoice Level Discount rate	O
31 Client reference 3	O
32 Total Invoice amount (excl. VAT )	A
33 Total VAT amount	A
34 Total Invoice amount (incl. VAT)	A

DET record M = mandatory, A = advised, O = optional, / = not applicable

INV record ATR (new transactions): Authorisation (RES) Level I // III

Field	RES (I)	RES (III)
1 DET Identifier	/	M
2 Quantity	/	M
3 Item Id/Code	/	M
4 Item description/name	/	A
5 Item unit price	/	A
6 VAT flag	/	A
7 VAT rate/code	/	A
8 LIne item reference 1	/	O
9 Line item reference 2	/	O
10 Item internal description	/	O
13 Item Discount Rate	/	O
14 Total Line amount (excl. VAT)	/	A

INV record ATR (new transactions): Direct Sale (SAL) / Refund (RFD) Level III

Field	SAL (III)	RFD (III)
1 DET Identifier	M	M
2 Quantity	M	M
3 Item Id/Code	M	M
4 Item description/name	A	A
5 Item unit price	A	A
6 VAT flag	A	A
7 VAT rate/code	A	A
8 LIne item reference 1	O	O
9 Line item reference 2	O	O
10 Item internal description	O	O
13 Item Discount Rate	O	O
14 Total Line amount (excl. VAT)	A	A

INV record MTR (maintenance transactions): (Last) data capture (SAL / SAS) Level III

Field	SAL/SAS (III)
1 DET Identifier	M
2 Quantity	M
3 Item Id/Code	M
4 Item description/name	A
5 Item unit price	A
6 VAT flag	A
7 VAT rate/code	A
8 LIne item reference 1	O
9 Line item reference 2	O
10 Item internal description	O
13 Item Discount Rate	O
14 Total Line amount (excl. VAT)	A

3. Submission Mode Directlink

You can also use DirectLink to send maintenance requests. Data captures and refunds (credit notes) need to be sent with level III information.

	New Order		Maintenance
Authorisation	Direct Sale	Refund (credit note)	Data Capture
Level I	Level III	Level III	Level III

This chapter complements the DirectLink Integration Guide. Please refer to the DirectLink integration guide for general information on the DirectLink submission mode. This chapter only refers to the parameters needed for submitting a purchasing card transaction.

3.1 General request parameters

Parameter	Content	Format / Max. length / Example
ECOM_CONSUMERID	Client ID, as configured in your <%COMPANY%> account	AN 20 PEUGEOT
ECOM_ CONSUMERUSERALIAS	Allows for credit card detail usage in a PCI compliant environment.	AN 20 Test123!
ORDERID	Order reference. If your order reference is unique you can use it for maintenance transactions to refer to the original transaction; otherwise you need to use the PAYID to refer to the original transaction.	AN 15 AB5456CB896
INVORDERID	Invoice number for invoices (SAL operation code). Credit note number for credit notes (RFD operation code).	AN 15 (Amex: 12) 2009-0000568
OR_INVORDERID	Original invoice number (for credit notes).	AN 15 (Amex: 12) 17358948
REF	Cardholder reference. (as requested by the client).	AN 16 Order 06/09/11
REF_CUSTOMERREF	Customer reference. (as requested by the client).	AN 20 YUJ7885
COSTCENTER	Cost Centre. (as requested by the client).	AN 20 Y567K8
REF_CUSTOMERID	Customer number. (as requested by the client).	AN 17 (Amex: 12) 73TO45
AMOUNT	Invoice amount including VAT. (* 100 to avoid decimals).	N 12 121000
AMOUNTHTVA	Invoice amount excluding VAT. (* 100 to avoid decimals).	N 12 100000
AMOUNTTVA	VAT amount. (* 100 to avoid decimals).	N 12 21000
INVDATE	Invoice/order date Default: current date	MM/DD/YY 8 09/25/15
DISCOUNTRATE	Discount rate at invoice level. Can have up to 2 decimals. Do not use %. This discount rate will be stated in the item name in the order details. The invoice level discount rate will be added to the item level discount rate: “Item name (- (DiscountRate + ItemDiscount) %)” We do not use this discount rate to calculate order amounts. The amounts you send us must already include the discount.	N xx.xx 5 05.00 (Item name “Scissors” will be “Scissors (-5%)”)
DATATYPE	“LID” Use if your requests contain Line Item Details.	LID 3 LID

The following fields can be repeated n times, changing the digit at the end of the field name (X):

ITEMIDX	Product code	AN 15 U419-52
ITEMNAMEX	Product name	AN 40 HP710C Cartridge
ITEMPRICEX	Unit Price Can have up to 4 decimals. Decimal separator: ‘.’ (full stop).	N xxxxxx.xx 12 (EUR 35,2575 =) 35.2575
LIDEXCLX	Total line amount, excluding VAT. Can have 2 decimals. (* 100 to avoid decimals).	N 12 (Amex: 12) 15000
ITEMDISCOUNTX	Item Discount Rate at line level. Can have up to 2 decimals. Do not use %. This discount rate will be stated in the item name in the order details. The item level discount rate will be added to the invoice level discount rate: “Item name (- (ItemDiscount + DiscountRate) %)” We do not use this discount rate to calculate order amounts. The amounts you send us must already include the discount.	N xx.xx 5 02.00 (Item name “Scissors” will be “Scissors (-2%)”)
TAXINCLUDEDX	Possible values: 1 (ItemPriceX includes VAT) 0 (ItemPriceX does not include VAT), default and recommended	N 1 0
ITEMVATCODEX	VAT rate with 2 decimals and % or Internal VAT code as configured in the VAT rules of your account (0, 1, etc.)	xx.xx% or N 6 21.00% 2
ITEMQUANTX	Item quantity 2 decimals allowed Decimal separator: ‘.’ (full stop)	N xxx.xx 12 52
ITEMCATEGORYX	Category or Commodity Code This field can also be used to send a reference at line level for some customers. (line item reference 2)	AN 12 (Amex: 8) TY1627
ITEMUNITOFMEASUREX	Unit Of Measure This field can also be used to send a reference at line level for some customers. (line item reference 1) (Although American Express accepts a field length of 12, <%COMPANY%> only allows 10.)	AN 10 Piece

3.2 Required parameters for new orders

The following section lists the minimum parameters we recommend you to use. Your client and/or acquirer may also possibly request you to use other specific parameters in addition to the ones listed here, e.g. Client references.

3.2.1 Authorisation (Level I)

The minimum fields we recommend you use for a level I authorisation are:

Authorisation (Level I, RES)
PSPID
USERID
PSWD
ORDERID
AMOUNT
CURRENCY
CARDNO
ED
OPERATION
ECOM_CONSUMERID

Example:

Level I authorisation
POST request on https://secure.ogone.com/ncol/test/orderdirect.asp containing the following parameters:
PSPID=GFR5oes2
USERID=GFR5oes2api
PSWD=UMPCOP24
orderID=Order758845M
amount=25410
currency=EUR
CARDNO=374291019071995
ED=06/21
OPERATION=RES
Ecom_ConsumerID=FORD

3.2.2 Direct sale Level III

The minimum parameters we recommend you use for level III direct sale are:

Direct sale (Level III, SAL)
PSPID
PSPID
USERID
PSWD
ORDERID
AMOUNT
CURRENCY
CARDNO
ED
OPERATION
ECOM_CONSUMERID
INVORDERID
AMOUNTHTVA
AMOUNTTVA
DATATYPE
ITEMIDX
ITEMNAMEX
ITEMPRICEX
TAXINCLUDEDX
ITEMVATCODEX
ITEMQUANTX
LIDEXCLX

Example:

Level III direct sale
POST request on https://secure.ogone.com/ncol/test/orderdirect.asp containing the following parameters:
PSPID=GFR5oes2
USERID=GFR5oes2api
PSWD=UMPCOP24
orderID=Order759864P
amount=25410
currency=EUR
CARDNO=374291019071995
ED=06/21
OPERATION=SAL
Ecom_ConsumerID=FORD
INVorderID=7598645384
amountHTVA=21000
amountTVA=4410
INVDATE=07/06/08
DataType=LID
ItemID1=5634
ItemName1=Scissors
ItemPrice1=200
TaxIncluded1=0
ItemVatCode1=21%
ItemQuant1=10
ItemUnitOfMeasure1=piece
LIDEXCL1=2000
ItemID2=5635
ItemName2=HP720c+printer+cartridge
ItemPrice2=1900
TaxIncluded2=0
ItemVatCode2=21%
ItemQuant2=10
ItemUnitOfMeasure2=piece
LIDEXCL2=19000
SHASIGN=a65d09014de61bc88a11f248f4995907d548dc0f

3.2.3 Refund/credit note (Level III)

The minimum parameters we recommend you use for a credit note are:

Refund (credit note) (Level III, RFD)
PSPID
USERID
PSWD
ORDERID
AMOUNT
CURRENCY
CARDNO
ED
OPERATION
ECOM_CONSUMERID
INVORDERID
AMOUNTHTVA
AMOUNTTVA
DATATYPE
ITEMIDX
ITEMNAMEX
ITEMPRICEX
TAXINCLUDEDX
ITEMVATCODEX
ITEMQUANTX
LIDEXCLX

Example:

Refund (credit note)
POST request on https://secure.ogone.com/ncol/test/orderdirect.asp containing the following parameters:
PSPID=GFR5oes2
USERID=GFR5oes2api
PSWD=UMPCOP24
orderID=Order759864P
amount=25410
currency=EUR
CARDNO=374291019071995
ED=06/21
OPERATION=RFD
Ecom_ConsumerID=FORD
INVorderID=12458654
OR_INVorderID=7598645384
amountHTVA=21000
amountTVA=4410
DataType=LID
ItemID1=5634
ItemName1=Scissors
ItemPrice1=200
TaxIncluded1=0
ItemVatCode1=21%
ItemQuant1=10
ItemUnitOfMeasure1=piece
LIDEXCL1=2000
ItemID2=5635
ItemName2=HP720c+printer+cartridge
ItemPrice2=1900
TaxIncluded2=0
ItemVatCode2=21%
ItemQuant2=10
ItemUnitOfMeasure2=piece
LIDEXCL2=19000
SHASIGN=ee2c95e0259a5d546a1fcf0afdb6e3be46be1a39

3.3 Required parameters for maintenance operations

Maintenance operations are based on transactions (orders) that have been entered in our system. Since the details of the original transaction are logged in our system, you do not have to repeat specific details such as the card number and expiry date. Instead, you should refer to the original transaction using its PAYID. Information you send us in maintenance transactions will overwrite any corresponding contrary information in the original transaction, except for the card number and the currency. The following section lists the minimum parameters we recommend you to use. Your client and/or acquirer may also possibly request you to provide other specific parameters in addition to the ones listed here, e.g. Client references, line item references.

3.3.1 Data capture (Level III)

The minimum parameters we recommend you use for a data capture are:

Data capture (Level III, SAL/SAS)
PSPID
USERID
PSWD
ORDERID
AMOUNT
CURRENCY
OPERATION
ECOM_CONSUMERID
INVORDERID
AMOUNTHTVA
AMOUNTTVA
DATATYPE
ITEMIDX
ITEMNAMEX
ITEMPRICEX
TAXINCLUDEDX
ITEMVATCODEX
ITEMQUANTX
LIDEXCLX

Example:

Data capture
POST request on https://secure.ogone.com/ncol/test/maintenancedirect.asp containing the following parameters:
PSPID=GFR5oes2
USERID=GFR5oes2api
PSWD=UMPCOP24
ORDERID=Order758845M
PAYID=18759754
AMOUNT=25410
CURRENCY=EUR
OPERATION=SAS
ECOM_CONSUMERID=FORD
INVORDERID=7598612385
AMOUNTHTVA=21000
AMOUNTTVA=4410
INVDATE=07/06/08
DATATYPE=LID
ITEMID1=5634
ITEMNAME1=Scissors
ITEMPRICE1=200
TAXINCLUDED1=0
ITEMVATCODE1=21%
ITEMQUANT1=10
ITEMUNITOFMEASURE1=piece
LIDEXCL1=2000
ITEMID2=5635
ITEMNAME2=HP720c+printer+cartridge
ITEMPRICE2=1900
TAXINCLUDED2=0
ITEMVATCODE2=21%
ITEMQUANT2=10
ITEMUNITOFMEASURE2=piece
LIDEXCL2=19000
SHASIGN=D2AF81D0E11BCA7531A8E59B698D0FDAC189884F

3.4 Overview of parameter usage

M = mandatory, A = advised, O = optional, / = not applicable

ATR (new transactions): Authorisation (RES) Level I // III

Field	RES (I)	RES (III)
ECOM_CONSUMERID	M	M
ORDERID	M	M
OR_INVORDERID	/	/
REF	O	O
REF_CUSTOMERID	O	O
AMOUNT	M	M
AMOUTHTVA	M	M
AMOUNTTVA	M	M
INVDATE	O	O
DISCOUNTRATE	O	O
DATATYPE LID	/	M
ITEMIDX	/	M
ITEMNAMEX	/	M
ITEMPRICEX	/	M
LIDEXCLX	/	O
ITEMDISCOUNTX	/	O
TAXINCLUDEDX	/	M
ITEMVATCODEX	/	M
ITEMQUANTX	/	M
ITEMCATEGORYX	/	O
IMTEUNITOFMEASUREX	/	O

ATR (new transactions): Direct Sale (SAL) / Refund (RFD) Level III

Field	SAL (III)	RFD (III)
ECOM_CONSUMERID	M	M
ORDERID	M	M
OR_INVORDERID	/	M
REF	O	O
REF_CUSTOMERID	O	O
AMOUNT	M	M
AMOUTHTVA	M	M
AMOUNTTVA	M	M
INVDATE	O	O
DISCOUNTRATE	O	O
DATATYPE LID	M	M
ITEMIDX	M	M
ITEMNAMEX	M	M
ITEMPRICEX	M	M
LIDEXCLX	O	O
ITEMDISCOUNTX	O	O
TAXINCLUDEDX	M	M
ITEMVATCODEX	M	M
ITEMQUANTX	M	M
ITEMCATEGORYX	O	O
IMTEUNITOFMEASUREX	O	O

MTR (maintenance transactions): (Last) data capture (SAL / SAS) Level III

Field	SAL/SAS (III)
ECOM_CONSUMERID	M
ORDERID	O
OR_INVORDERID	/
REF	O
REF_CUSTOMERID	O
AMOUNT	M
AMOUTHTVA	M
AMOUNTTVA	M
INVDATE	O
DISCOUNTRATE	O
DATATYPE LID	M
ITEMIDX	M
ITEMNAMEX	M
ITEMPRICEX	M
LIDEXCLX	O
ITEMDISCOUNTX	O
TAXINCLUDEDX	M
ITEMVATCODEX	M
ITEMQUANTX	M
ITEMCATEGORYX	O
IMTEUNITOFMEASUREX	O

3.5 Security: SHA signature

3.6 Test pages

4. e-Commerce Submission Mode

You can send a new purchasing card order via e-Commerce. Authorisation requests are sent with level I information, level III information; direct sale requests or maintenance requests are not possible via e-Commerce.

	New Order		Maintenance
Authorisation	Direct Sale	Refund (credit note)	Data Capture
Level I	-	-	-

This chapter complements the e-Commerce integration guide. Please refer to the Advanced e-Commerce integration guide for general information on e-Commerce submission mode. This chapter only refers to the additional items necessary for submitting a purchasing card transaction.

4.1 Additional hidden fields

The following hidden field needs to be transmitted to our system along with the general parameters:

Field	New Order
ECOM_CONSUMERID	The Client ID as you entered/adapted it in our system via the “Customers” link

4.2 Payment page

4.3 Test page

An example (test page) to submit an authorisation can be found at: https://secure.ogone.com/ncol/test/teststd_pc.htm

5. Appendix 1: Troubleshooting

The following section contains a non-exhaustive list of possible errors:
Not enough DET records compared to NBDETAILS param for invoice
This error means the number of DET records you indicated in the INV record is too high compared to the number of DET lines according to the INV record. You have an inadequate number of DET lines for the invoice or have entered an incorrect number in the INV record.
DET or CLI record without corresponding payment record
This error means the number of DET records you indicated in the INV record is too low compared to the number of DET lines according to the INV record. You have too many DET lines for the invoice or have entered an incorrect number in the INV record.
Payment detail validation failed
In general, you will receive this error message if there is an error in the amounts you entered in the invoice. If you cannot find the error, please contact our Customer Care Team.
Details not sent for a Purchasing card transaction
You will receive this error message if you were expected to send Level III details in your transaction but you failed to do so. You need to send along Level III details for this order.
ConsumerID not defined for merchant
This error means the Client ID you used in the order is not registered (or registered with another name) in the Customer management section in our back office.
Invoice level amount sounds too big compared to amounts computed from Line Items
You will receive this error when the total invoice amount you sent us is too high compared to the invoice details you sent us. For instance, your invoice amount is 500 EUR and your line item details contain 10 scissors at 2 EUR each and 10 ink cartridges at 20 EUR each: 500 > (20 + 200).
Item Vat Code > 4 and not a Vat Rate for ItemID
This error means you entered a VAT code value higher than 4 as the VAT rate for an ItemID. You can use a VAT percentage (e.g. 21%) or a VAT code. The VAT code will be 0, 1, 2, 3 or 4, as configured in the VAT rules in your account. Invalid combination of amounts (amount - AM)
In general, you will receive this error message if there is an error in the amounts you entered in the invoice. If you cannot find the error, please contact our Customer Care Team.
Not enough customer data for customer
This error means you either forgot to complete some mandatory fields in the Customer profile in your account or you failed to send any Client ID in your order.
This Invoice Number has already been used
This error means you sent us an order with an Invoice number that has already been used for another order.
Card type not active for the merchant
This error means you are trying to send a transaction using a card brand which has not yet been added/activated in your account.
No global orderID
You will receive this error message if you were expected to send an orderID (Order Number, INV 29) in your transaction details but you failed to do so. You need to send along an orderID/Order Number for this order.

6. Appendix 2: Customer References

There are 4 customer references you can send along in transactions:

Cost centre
Customer Reference
Customer ID
Cardholder Reference

Reference	Batch	DirectLink	Field on bank statement Only for BNP Paribas Customers who are active in the public sector
Cost centre	Cost Center (CLI 2)	COSTCENTER	Référence Client 4/Numéro d’Engagement
Customer Reference	Client reference 1 (INV 7)	REF_CUSTOMERREF	Référence Client 3/Numéro de Marché
Customer ID	Client reference 3 (INV 31)	REF_CUSTOMERID	Référence Client 2
Cardholder Reference	Client reference 2 (INV 21)	REF	Référence Client 1