Batch Processing
Interface specification
This document describes the Saferpay Batch Processing, a service allowing the processing of credit card and German electronic direct debit (ELV) payments via a batch file.
Relevant parameters are highlighted in monospace in this guide.

Prequisites

The following conditions must be fulfilled to use the batch processing:
  • A corresponding license and with that an existing Saferpay account with login and password
  • At least one active Saferpay terminal via which payments can be processed. The corresponding TERMINALID respectively the ACCOUNTID must be available.
  • The format of the data set and the name of the input file must correspond to the format described in this guide

Security and PCI DSS

Although the Saferpay system meets the PCI DSS (Payment Card Industry Data Security Standard) requirements and is inspected regularly to verify compliance, you are encouraged to apply the following rules when using Saferpay Batch Processing.
When using Saferpay Batch Processing, credit card data is entered in the input file and uploaded from your system to Saferpay. You should ensure that you comply with the security requirements of your card-accepting bank (acquirer) concerning the handling of credit card data.
We recommend you use the Saferpay Secure Card Data Service in combination with Saferpay Batch Processing in order to significantly reduce the expense for the PCI DSS review of the merchant system. This service allows you to process transmit and store the credit card data directly in the secure Saferpay computer centre and no longer on the merchant system. For more information, please contact the Saferpay technical support team or customer service department.
Processing of the card verification number (also called CVC2, CVV2, CID or 4DBC) is optional. Please note, that according to PCI DSS regulation, the card verification number is part of the confidential card data that may only be stored temporarily.
Due to PCI DSS regulation the processing of magnetic stripe data is no longer possible via Batch Processing.
If you have any questions regarding PCI DSS, please contact your acquirer or a qualified security provider (see https://www.pcisecuritystandards.org).

Other information

Please note the following points:
  • Uploaded files are processed within one day (24 hours) for the card companies.
  • The Saferpay Batch Processing is designed for not time critical payments and not for online authorizations in real time or seconds.
  • For time critical authorizations we recommend the use of the Saferpay Client API.
  • In order to ensure a smooth processing we recommend to process not more than 500 transactions per file.
  • Since acquires reject non-authorized transactions all transactions are authorized in a first step before being transmitted for further processing.
  • Please note that the Batch Processing will also trigger the Batch Close for all transactions, once the batch is finished.

Supported payment means

The Saferpay Batch Processing currently allows the processing of transactions for the following payment means:
  • Visa/VPay
  • Mastercard/Maestro
  • American Express
  • Diners Club/Discover
  • JCB
  • direct debit (ELV - only for German bank accounts)
The following abbreviations for format information are used in this document:

Conventions

Format details

Format
Description
a
letters (a - z, A - Z)
n
numeric characters (0 - 9)
an
alphanumeric characters (a - z, A - Z, 0 - 9)
s
special characters (:?,-(+'.)/ and space)
ans
alphanumeric and special characters

File names

The name of the file to be processed starts with the Saferpay Customer ID followed by a dash and the unique file identifier and ends with the file extension ".IN".
Syntax: CustomerID-FileID.IN
Example: 423456-subscriptions2021.IN

Customer ID

The Saferpay Customer ID currently consists of 4 to 7 digits. This could change in the future.

File identifier (FileID)

The File identifier has to be unique and is defined as follows:
  • length: variable 1 to 40 characters
  • permitted characters: 0-9, A-Z, a-z, - (dash), _ (underscore)
  • no distinction is made between uppercase and lowercase
Examples (FileID in italics):
  • 12001-1.IN
  • 12001-002.IN
  • 12001-abcd5523.IN
  • 12001-CA4DD53A-C1BB-4378-A7EB-4AB7AA6729D9.IN

Input file format

The information required for uploading is saved in a text file. The following rules are to be respected in this context:
  • Parameters are separated by a comma (ASCII 0x44)
  • each line must terminate with a line separator CR or CRLF Incorrectly formatted lines are rejected with the error code ICCTERR in the output file. It is the responsibility of the sender to correct the format and resubmit the file.

File transfer

The files are transferred between the sender and the Saferpay system via a secure SSL connection (https) from the Saferpay Backoffice. An email address can be stored to get a message when the file processing is finished.
Could not load image

Input file

Parameters and descriptions

If not marked as optional all parameters are mandatory.
Pos
Parameter
Format
Description
1
RECORDTYPE
an[7]
File record type, must always be ICCT100
2
TERMINALID
n[8]
Saferpay Terminal ID to be used for the transaction. The Terminal ID is assigned by the Saferpay system.
3
ORDERID
an[..30]
(optional) Sender’s reference number. Processing-specific restrictions exist
4
PAN
ans[..50]
(optional) The card number (primary account number), see separate format description (3.2.3) for use of the card reference number via the Secure Card Data service. Cannot be used together with IBAN.
For card aliases use the prefix "CARDREFID:" e.g. CARDREFID:alias123
5
EXPMONTH
n[..2]
(optional if card alias is used in PAN)
Card expiry month. {1, 2, 3, ..., 12} or {01, 02, 03, ..., 12}
6
EXPYEAR
n[2] or n[4]
(optional if card alias is used in PAN) Card expiry year.
e.g. 23, 2025
7
-
-
obsolete
8
AMOUNT
n[1..12]
Amount in the smallest currency unit. Only digits (integer) and no decimal points (12,95 --> 1295) are allowed.
9
CURRENCY
a[3]
Currency in ISO 4217 alpha 3 code.
(EUR, CHF, USD, ...)
10
-
-
obsolete
11
DOCREDIT
n[1]
0 = Debit (amount is charged to the cardholder)
1 = Credit (amount is refunded to the cardholder – credits are not possible for german direct debit)
12
DOAUTHOR
n[1]
Must always be 1
13
TIMEDATE
n[12] or n[14]
Date and time of booking with format YYYYMMDDhhmm or YYYYMMDDhhmmss. If the seconds (ss) are not entered, Batch Processing sets ss = 00. TIMEDATE is only evaluated internally by Batch Processing
14
CVC
n[3] or n[4]
(optional) 3- or 4-digit card security number, also known as: CID/4DBC (American Express), CVC (MasterCard), CVV2 (Visa) or CAV (JCB)
15
-
-
obsolete
16
-
-
obsolete
17
-
-
obsolete
18
RECURRING
a[1]
(optional) Tagging for recurring transactions. Possible value is “R” to tag the transaction as recurring, e.g. for subscription.
19
REFID
ans[28]
(optional) Transaction identifier of the initial payment for recurring payments.
20
MANDATEID
ans[..35]
(optional) Mandate reference for German direct debit (ELV) payments.
21
IBAN
an[22]
(optional) IBAN for German direct debit (ELV) payments. Cannot used together with PAN.

Parameter details

TERMINALID

The Saferpay TERMINALID represents a Saferpay terminal. You will find the Saferpay TERMINALID in the Saferpay Backoffice under "Administration > Accounts".
A Saferpay ACCOUNTID consists of the customer ID, dash (-) and TERMINALID; e.g. 99867-94913159, where 99867 is the customer ID and 94913159 the TERMINALID.

ORDERID

The order ID serves to identify payments in order to enable the merchant to assign the transactions to the correct orders at a later time. The ORDERID is forwarded to the card processor (merchant bank) and is generally listed in the merchants settlement note.
Only numbers (ASCII 0x30...0x39), uppercase letters (0x41...0x5A), lowercase letters (0x61...0x7A) and “-“ and “_” (0x2D and 0x5F) are accepted. Correct processing cannot be guaranteed if other characters are transmitted.
The maximum number of digits varies from processor to processor. In most cases 12 digits has proven to be a good value.

PAN

This field is used for card payment and contains the manually entered card number. The card expiry date is to be transmitted with the fields EXPMONTH and EXPYEAR.
If a card alias (CARDREFID) is to be processed, the text “CARDREFID:” (complete with colon) must precede the alias.
Data
Value of PAN
Visa card 4000 1234 5678 9012
4000123456789012
Card alias
680023981
CARDREFID:680023981

DOCREDIT

Specifies whether the customer is to be debited (= 0 for booking) or credited (= 1 for refund). Refunds are only possible for credit card transactions.

TIMEDATE

This field contains the time of booking in the format YYYYMMDDhhmmss (14 digits), where
Part
Meaning
Allowed values
YYYY
year
2000, 2001, ..., 2999
MM
month
01, 02, 03, ..., 12
DD
day
01, 02, 03, .., 31
hh
hours
00, 01, 02, ..., 23
mm
minutes
00, 01, 02, .., 59
ss
seconds
00, 01, 02, .., 59
Alternatively the format YYYYMMDDhhmm with 12 digits is also valid and can be used. Internally the Batch Processing then sets the seconds as ss = 00.

CVC

According to the rules of the credit card organizations, the card security number (CVC, CVV2, CID, 4DBC) is to be kept strictly confidential. You are advised to always respect this concerning security requirements. For more information please contact your acquirer.

RECURRING

With these fields transactions can be tagged with value “R” as recurring payments. The consecutive payment additionally references to the transaction identifier (ID) of the initial payment by using parameter REFID. Please contact your acquirer for information if recurring transactions must be tagged or not

MANDATEID

This field contains the SEPA mandate reference of a German direct debit (ELV) payment.

IBAN

This field contains the International Bank Account Number for direct debit payments using a german bank account.

Examples

1
ICCT100,94913159,TEST1,9451123100000004,12,15,M,1000,EUR,,0,1,20120202165533
2
ICCT100,94913159,TEST2,9451123100000004,12,15,M,550,EUR,,0,1,20120202165534,442
3
ICCT100,94913159,TEST3,9451123100000004,12,15,M,105.00,EUR,,0,1,201202021655
4
ICCT100,94913159,TEST4,4000000000000002,12,2015,M,1050,EUR,,1,1,201202021656
5
ICCT100,94913159,TEST5,5232000000000017,12,2015,M,1120,EUR,,0,1,201202021500,,1,AAABCEkCYQABA314UQJhAAAAAAA=,DmZAXgVCNWAOAQN3AwAFWgN9CQM=
6
ICCT100,94913159,TEST6,375811111111115,12,10,M,1000,EUR,,0,1,201202021656
7
ICCT100,94913159,TEST7,CARDREFID:1234567890,02,15,M,670,EUR,,0,1,201202021658
8
ICCT100,94913159,TEST8,,,M,1009,EUR,,0,1,201202021659,,,,,,MyMandateID,DE77970000010123456789
Copied!

Explanations

Line 1: Authorization and booking. Line 2: Authorization, booking, card data with card security number. Line 3: Incorrect, the amount must be entered without a decimal point. Line 4: Credit (refund to cardholder). Line 5: MasterCard SecureCode payment with ECI=1, CAVV and XID. Line 6: Incorrect, card already expired. Line 7: Booking, card reference number (CARDREFID) is used. Line 8: Booking, payment by direct debit.

Identifying duplicate entries

The Batch Processing checks the transactions for duplicate entries. If an input transaction has the same values for TERMINALID, ORDERID, PAN, EXPMONTH, EXPYEAR, AMOUNT, CURRENCY, DOCREDIT and TIMEDATE as an already processed transaction, it is identified as a duplicate and returned with the following error text: "Double Transaction - Transaction in LineNumber x has already been processed."
To ensure that transactions are distinct at least within one field, TIMEDATE may optionally be stated down to the second (14 digits, the year always has four digits). If no seconds are stated, File Import sets the seconds to 00. TIMEDATE is only used internally by the batch import. It is recommended to assure the distinctness of transactions via the use of a unique timestamp for each transaction.

Output file

For each file uploaded the sender receives an output file with the same file name as the input file but suffixed with the file ID ".OUT".
Every data record is checked for format correctness. If the format check succeeds the record is processed and the .out file entry will contain RECORDTYPE "ICCT101". If the check fails the corresponding entry will contain RECORDTYPE "ICCTERR".

Processed record set

For each processed record set of the input file (ICCT100) the output file contains a corresponding response record set (ICCT101) with result and transaction identifier.
Pos
Parameter
Format
Description
1
RECORDTYPE
an[7]
Always contains the value ICCT101.
2
TERMINALID
n[8]
Saferpay terminal ID of the transaction.
3
ORDERID
an[..30]
(optional) Sender reference number if stated in the input file.
4
RESULT
n[1..3]
0 = authorization is approved
≠0 = error code
5
ID
ans[50]
Transaction ID in Saferpay
6
AUTHCODE
an[50]
(optional) Authorization code of the processor.
7
TIMEDATE
n[12]
Date and time of authorization with format YYYYMMDDhhmm
8
AUTHRESULT
n[2]
(optional) Processor reply code; only returned if RESULT contains the value "65". The reply codes may have different meanings, depending on the processor.
9
MANDATEID
ans[..35]
(optional) Mandate reference for German direct debit (ELV) payments..

Incorrect entry in the output file

If a data record in the input file fails the format verification check, the output file contains an ICCTERR message in the corresponding line of the output file.
Pos
Parameter
Format
Description
1
RECORDTYPE
an[7]
Always contains the value ICCTERR.
2
TERMINALID
n[8]
Saferpay Terminal ID of the transaction.
3
ORDERID
an[..30]
(optional) Sender reference number if stated in the input file.
4
TIMEDATE
n[12]
Timestamp of the format check.
Format: YYYMMDDhhmm
5
FIELDINDEX
n[2]
Position of the incorrect field in the record of the input file.
6
FIELDNAME
a[…]
Name of the incorrect field in the record of the input file.
7
MESSAGE
ans[…]
(optional) Additional description.

Examples

1
ICCTERR,1445001,test11,201102021612,1,RecordType,Double Transaction - Transaction in LineNumber 1 has already processed
2
ICCTERR,1445001,test12,201102021612,13,TimeDate,DateTime length is wrong: 0
3
ICCTERR,14450001,test13,201102021612,8,Amount,Amount is not numeric 105.00
4
ICCTERR,14450001,test14,201102021612,2,TerminalID,User has no access for TerminalId:1445001
5
ICCTERR,14450001,test15,201102021612,5,ExpMonth,ExpMonth is out of range
6
ICCTERR,14450001,test16,201102021612,6,ExpYear,Card is expired:1204
7
ICCTERR,14450001,test17,201102021612,4,CardNumber,7004 - No CardNumber found for this CardRefId.
8
ICCTERR,14450001,test18,201102021612,13,TimeDate,DateTime length is wrong: 13
Copied!

List of RESULT values

Value
Message
Description
61
Invalid card
The card is invalid (plausibility check).
62
Invalid date
The expiry date is invalid.
63
Card expired
The card has expired; Is no longer valid.
64
Unknown card
The card is unknown; the card could not be assigned to a card type.
65
Authorization declined
The card processor has rejected the transaction. The AUTHRESULT field contains processor-specific details explaining the reasons.
67
No contract available
There is no active contract for the concerned payment mean or currency for the terminal.
83
Invalid currency
Invalid currency code.
84
Invalid amount
The amount is invalid.
104
PAN blacklist
Card is blacklisted by Saferpay Risk Management.
105
Card country not white listed
Card issuer country is not included in the Saferpay Risk Management white list.
114
CVC mandatory
The card security number must be entered

Sample output file

1
ICCT101,94913159,TEST1,0,6bf9e707a9e64938b7e4612b2bcb,074869,201102030852
2
ICCT101,94913159,TEST2,0,9bd5f26175a14cd1bd839dc81fa3,862777,201102030852
3
ICCTERR,94913159,TEST3,201102030852,8,Amount,Amount is not numeric: 105.00
4
ICCT101,94913159,TEST4,0,682dab8de6614ae4bb15d83e94bc,,201102030852
5
ICCT101,94913159,TEST5,0,12d693de415f425a919ba4aea4f3,124865,201102030852
6
ICCTERR,94913159,TEST6,201102030852,6,ExpYear,Card is expired: 1204
7
ICCT101,94913159,TEST7,0,96c0fe28e09d40b3b98248a4ac54,395000,201102030852
8
ICCT101,94913159,TEST8,67,74301cbe-87ca-4e3c-aeb0-3223c9f69210,,201102030852
Copied!
Explanation
Line 1: Authorization and booking, successfully processed and stored. Line 2: Authorization and booking, successfully processed and stored. Line 3: Transaction rejected by Batch Processing, with error code. Line 4: Refund (credit), successfully processed. Line 5: Transaction with reference number, successfully processed. Line 6: Transaction rejected by Batch Processing, with error code. Line 7: Authorization and booking with use of CARDREFID, successful. Line 8: Request rejected, reply code 67 (no contract available).

Output file if Batch Processing is processed automatically

If Batch Processing is processed automatically via upload or download an additional result line appears at the end of the output file. In case of successful processing the result line looks like this: ResultCode: 200 OK
Could not load image
If the access is not granted because of an invalid user name the message ResultCode = 401 Unauthorized is returned:
Could not load image

Automation

File Import can be automated via the Saferpay website. Uploading and downloading are SSL encrypted with https.
For the automated use of the Saferpay Batch Processing a login and password are required.
According to the PCI DSS security regulations the upload and download files must be transmitted by POST. The GET method is not permitted.

Upload

The file to be uploaded must be sent to the following Saferpay URL:
1
https://www.saferpay.com/bo/fileimport/scriptupload
Copied!
The login data is transferred within hidden fields using the parameters spUsername, spPassword and UAFState and CustomerID.
Name
Value
spUsername
contains the user ID, e.g. e99867001.
spPassword
contains the password associated with the user ID
UAFState
must always contain the value login
CustomerID
contains the customerID, e.g. 99867

Download

Output files can be downloaded from the following Saferpay URL:
1
https://www.saferpay.com/bo/fileimport/scriptdownload
Copied!
The login data is transferred within hidden fields using the parameters spUsername, spPassword and UAFState and CustomerID. The filename is transmitted with the parameter Sequence.
Name
Value
spUsername
contains the user ID, e.g. e99867001.
spPassword
contains the password associated with the user ID.
UAFState
must always contain the value “login”
CustomerID
contains the customerID, e.g. 99867.
Sequence
contains the filename

Code examples

HTML form

Upload
Download
1
<html>
2
<head>
3
<title>Upload Example for Saferpay File Import</title>
4
</head>
5
<body>
6
<h2>Upload Example for Saferpay File Import</h2>
7
<form enctype="multipart/form-data" action="https://www.saferpay.com/bo/FileImport/ScriptUpload" method="POST">
8
<input type="hidden" name="spUsername" value="xxxxxxxxx" />
9
<input type="hidden" name="spPassword" value="xxxxxxxxx" />
10
<input type="hidden" name="UAFState" value="login" />
11
<input type="hidden" name="CustomerID" value="xxxxxxxxx" />
12
<p>
13
Select file to upload:
14
<br/>
15
<input type="file" size="50" />
16
</p>
17
<input type="submit" value="File Import" />
18
</form>
19
</body>
20
</html>
Copied!
1
<html>
2
<head>
3
<title>Download Example for Saferpay File Import</title>
4
</head>
5
<body>
6
<h2>Download Example for Saferpay File Import</h2>
7
<form enctype="multipart/form-data" action="https://www.saferpay.com/bo/FileImport/ScriptDownload" method="POST">
8
<input type="hidden" name="spUsername" value="xxxxxxxxx"/>
9
<input type="hidden" name="spPassword" value="xxxxxxxxx"/>
10
<input type="hidden" name="CustomerID" value="xxxxxxxxx"/>
11
<p>
12
file name:
13
<br/>
14
<input type="text" length="30" name="Sequence" value="" />
15
</p>
16
<input type="hidden" name="UAFState" value="login" />
17
<input type="submit" value="Download" />
18
</form>
19
</body>
20
</html>
Copied!

Visual Basic Script

Upload
Download
1
'Upload of file
2
File = "xxxxxx" : Username = "xxxxxx" : Password = "xxxxxx" : CustomerID = "xxxxxx" : UAFState = "login"
3
4
'read file data
5
Set fs = WScript.CreateObject("Scripting.FileSystemObject")
6
Set rd = fs.OpenTextFile(File) : Content = ""
7
do while rd.AtEndOfStream <> true : Content = Content & rd.ReadLine & vbCrLf : loop
8
rd.Close
9
10
'URL to Server
11
URL = "https://www.saferpay.com/bo/FileImport/ScriptUpload"
12
13
'needed for file upload
14
Boundary = "-----------------------------xaHbfgeHJ65Jk7"
15
ScriptBoundary = "--" & Boundary
16
Set http = WScript.CreateObject("Microsoft.XMLHTTP")
17
http.open "POST", URL, false
18
http.setRequestHeader "Content-Type", "multipart/form-data; boundary=" & Boundary
19
20
'send file content within boundary
21
PostFieldsBody = ScriptBoundary & vbCrLf _
22
& "Content-Disposition: form-data; name=""spUsername""" & vbCrLf _
23
& vbCrLf _
24
& Username & vbCrLf _
25
& ScriptBoundary & vbCrLf _
26
& "Content-Disposition: form-data; name=""spPassword""" & vbCrLf _
27
& vbCrLf _
28
& Password & vbCrLf _
29
& ScriptBoundary & vbCrLf _
30
& "Content-Disposition: form-data; name=""CustomerId""" & vbCrLf _
31
& vbCrLf _
32
& CustomerID & vbCrLf _
33
& ScriptBoundary & vbCrLf _
34
& "Content-Disposition: form-data; name=""UAFState""" & vbCrLf _
35
& vbCrLf _
36
& UAFState & vbCrLf _
37
& ScriptBoundary
38
39
PostFileBody = vbCrLf _
40
& "Content-Disposition: form-data; name=""f1""; filename=""" & File & """" & vbCrLf _
41
& "Content-Type: text/plain" & vbCrLf
42
& vbCrLf _
43
& Content & ScriptBoundary & "--" & vbCrLf
44
45
http.send PostFieldsBody & PostFileBody
46
47
'wait until http received all data
48
do while http.readyState <> 4 : DoEvents : loop
49
50
'clean objects
51
Set rd = nothing
52
Set fs = nothing
53
Set http = nothing
Copied!
1
'download of file number
2
FileNr = "xxxxxx" : Path = "xxxxxx" : Username = "xxxxxx" : Password = "xxxxxx" : CustomerID = "xxxxxx" : UAFState = "login"
3
4
'prepare url for download incl. login
5
URL = "https://www.saferpay.com/bo/FileImport/ScriptDownload"
6
7
'download file content
8
Boundary = "-----------------------------xaHbfgeHJ65Jk7"
9
ScriptBoundary = "--" & Boundary
10
Set http = WScript.CreateObject("Microsoft.XMLHTTP")
11
http.open "POST", URL, false
12
http.setRequestHeader "Content-Type", "multipart/form-data; boundary=" & Boundary
13
14
'send file content within boundary
15
PostFieldsBody = ScriptBoundary & vbCrLf _
16
& "Content-Disposition: form-data; name=""spUsername"""& vbCrLf _
17
& vbCrLf _
18
& Username & vbCrLf _
19
& ScriptBoundary & vbCrLf _
20
& "Content-Disposition: form-data; name=""spPassword"""& vbCrLf _
21
& vbCrLf _
22
& Password & vbCrLf _
23
& ScriptBoundary & vbCrLf _
24
& "Content-Disposition: form-data; name=""CustomerId"""& vbCrLf _
25
& vbCrLf _
26
& CustomerID & vbCrLf _
27
& ScriptBoundary & vbCrLf _
28
& "Content-Disposition: form-data; name=""UAFState"""& vbCrLf _
29
& vbCrLf _
30
& UAFState & vbCrLf _
31
& ScriptBoundary & vbCrLf _
32
& "Content-Disposition: form-data; name=""Sequence"""& vbCrLf _
33
& vbCrLf _
34
& FileNr & vbCrLf _
35
& ScriptBoundary & vbCrLf _
36
& "Content-Disposition: form-data; name=""Path"""& vbCrLf _
37
& vbCrLf _
38
& Path & vbCrLf _
39
& ScriptBoundary
40
41
http.send PostFieldsBody
42
43
'wait until http received all data
44
do while http.readyState <> 4: DoEvents: loop
45
46
'write content to file
47
Set fs = WScript.CreateObject("Scripting.FileSystemObject")
48
Set wr = fs.CreateTextFile(Path & CustomerID & "-" & FileNr &".out")
49
wr.Write http.ResponseText
50
wr.Close
51
52
'clean objects
53
Set wr = nothing
54
Set fs = nothing
55
Set http = nothing
Copied!
Last modified 6mo ago