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:

If you decide to work in direct sale mode, your transaction flow will be as follows:

We will now take a closer look at the Batch, Direct Link and e-Commerce submission modes.

2. Submission Mode Batch

You can send a new purchasing card order via Batch. While authorisation requests can be sent with level I or level III information, direct sale requests have to be sent with level III information.

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

Client
Client
<%COMPANY%>
Client
Client
<%COMPANY%>
Client
Client
<%COMPANY%>

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

Level I 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
25410;EUR;;374291019071995;0514;;;John Doe;;RES;;;;GFR5oes;;;;FORD;;;;;;;;;;06/30/08; OH74988;;

Level III Authorisation (without invoice number)

The minimum fields we recommend you use for a level III authorisation are:
Authorisation (Level I, RES)
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
(10) Operation code (5) Item unit price
(14) PSPID (6) VAT flag
(16) number of DET records (6)(7) VAT rate or internal VAT code
(18) Client ID (14) Total line amount (excl. VAT)
(29) Order number
(32) Total invoice amount (excl. VAT)
(34) Total invoice amount (incl. VAT)

INV 4-5 are optional if you use field 17 Cardholder Alias
(29) Order number
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
If you have already received an authorisation for the order via another channel (e.g. authorisation received by phone from your acquirer) and you want to transmit this authorisation information in the transaction, you must use the following additional fields:
  • (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
New purchasing card orders can be submitted via DirectLink. Authorisation requests are sent with level I information, direct sale requests must be sent with level III information.

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

The following table illustrates all possible parameters you can send for a standard purchasing card request in addition to the standard DirectLink parameters (see the DirectLink guide). Of course, these parameters should not be used all together. Please use this table as a reference for parameter details. In the following sections, we will list the required additional parameters per operation.
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

IMPORTANT All submitted information for e-Supply must be included in the SHA calculation!
Please refer to the DIRECTLINK integration guide for more information on SHA.

3.6 Test pages

An example (test page) order request can be found at: https://secure.ogone.com/ncol/test/testodl_pclid.asp
An example (test page) maintenance request can be found at: https://secure.ogone.com/ncol/test/testodm_pclid.asp

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

On the secure payment page, you can enter specific order references if your client and/or acquirer has requested you to do so. The references are: Cost centre, customer (ID), customer reference and cardholder reference. In the card details, the type of purchasing card is automatically selected based on the card type you configured for the Client ID.

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

These references are not indicated as mandatory in this document, but they might be important fields for some customers. Your acquirer and/or customer could ask you to consider some of these fields as mandatory when entering an order. These references may be used by the customer to automate their accounting. It is therefore important to ensure the information you send in these fields is correct. Please refer to your customer or acquirer for more information on the use of these references.
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