Home Sign out

Introduction

We have a comprehensive range of API services that allow you to seamlessly implement payment processing into your applications. Our APIs cover a range of development environments including file and message based transaction processing, Hosted web payment pages and Web Services. We also cover the full spectrum of card processing environments including Customer not Present, Customer Present, E-Commerce, B2B level 3 enhanced data and travel enhanced data.


Key Concept

Terminology

Acquirer

A banking institute partnering with the Payment Service Provider to enable infrastructure needed to send/receive and collect card payments. The Acquirer is also responsible for crediting "Supplier/Merchants" bank accounts against monies due.

Authorisation

Authorisation confirms that the card number is valid and that the funds were available at the time the transaction took place. It is not a guarantee of payment.

B2B - Business-to-Business

Term used to describe trading activities between businesses. See also B2C

B2C - Business-to-Consumer

Term used to describe trading activities between businesses and consumers. See also B2B

Buyer

The cardholder requesting the "Supplier/Merchant" to take card payments

Cardholder Not Present

This refers to card transactions that are requested by mail, telephone or over the Internet when the cardholder is not present at the point of sale.

Enhanced Data

Additional data that flows with the transaction back to the buyer. See also Level 3 Data

Level 2 Data

Level 2 data simply refers to the electronic summary invoice data associated with a purchasing card transaction. Standard credit/debit cards are referred to as Level 1.

Level 3 Data

Level 3 data simply refers to the electronic invoice data associated with a purchasing card transaction. Standard credit/debit cards are referred to as Level 1.

Merchant

A services or goods provider to the "Buyer" whom will take card as a method of payment using the tools provided by the "EPOS provider" and "Acquiring Bank".

Merchant ID (MID)

You will require a Merchant ID to accept card payments. The MID links the money processed to your business bank account via an acquiring bank. We are able to assist with competitive merchant service charge rates to new and existing Adflex customers. For more information, please contact us.

Payment Service Provider

A company which provides the "Supplier/Merchant" with the tools needed to take card payments either via a physical terminal, web based portal or file based interchange. For example Adflex is a Payment Service Provider

Purchasing Card

A purchasing card (also abbreviated to pcard or Procurement Card) is a form of company charge card that allows goods and services to be procured without utilising a traditional purchasing process.

PAN

Primary Account Number. A numerical code consisting of 14 or 19 digits both embossed on a payment card. It identifies the Issuer of the card, the card holders account number, and a check digit (Luhn) for authentication.

PCI DSS

The Payment Card Industry Data Security Standard (PCI DSS) is a proprietary information security standard for organizations that handle branded credit cards from the major card schemes including Visa, MasterCard, American Express, Discover, and JCB.

Settlement

This is typically an end of day process that settles authorisations from the day

Supplier

See Merchant

XML

XML is the Extensible Markup Language, a system for defining specialized markup languages that are used to transmit formatted data. XML is conceptually related to HTML, but XML is not itself a markup language. Rather it's a metalanguage, a language used to create other specialized languages.

How card Processing Works

  1. Buyer Order

    Buyer uses their pcard to order goods/services from Supplier.

  2. Supplier Payment Request

    Supplier processes the Buyer order and raises a payment request and electronic invoice using an Adflex provided card processing service. Depending on the anticipated number of payments, the supplier has a choice of manually entering the card transaction, using a web portal Adflex Virtual Terminal or by an automatic file upload Adflex FilePay Service.

  3. Acquiring Bank Payment Request

    Adflex contacts the Suppliers Acquiring Bank and attempts to authorise the payment request.

  4. Acquiring Bank Payment Response

    Acquiring bank sends payment authorised/declined response back to Adflex.

  5. Adflex Payment Response

    Adflex sends the Acquiring Bank payment response back to suppliers Adflex payment service.

  6. Acquiring Bank Settlement Payment Request

    If the payment has been authorised, at end of day Acquiring Bank requests supplier payment from issuing bank.

  7. Issuing Bank Payment

    Issuing Bank transfers funds to the Acquiring Bank.

  8. Acquiring Bank Settlement

    Acquiring Bank transfers funds to supplier's bank, typically within 3-4 working days.

  9. Supplier Delivery to Buyer

    If the payment has been authorised, supplier then delivers requested goods/service to buyer.

  10. Issuing Bank Invoice Delivery

    Issuing Bank delivers suppliers e-invoice to the buyer, typically at end of month.

card payment process diagram

Processing Environments

Introduction to card processing environments
  • Card Holder Not Present (CNP/MOTO)
  • Card Holder Present (Chip and PIN)
  • e-Commerce

Purchasing Cards

Purchasing Cards, also known as Level 3, help organisations cut costs and improve cash flow with the added benefit of a more streamlined procurement process. A Purchasing card is very similar to a company charge card, but with one crucial difference; the payment request is associated with an electronic invoice.

The electronic invoice offers major benefits to the buying organisation, that include improved administration, visibility and analysis. Typically, the buyer will use their purchasing card to procure goods or services from a supplier, the supplier, in turn, will redeem the payment and enter invoice data at the same time.

Knowing the anticipated volumes up front will determine whether the supplier opts for a manual web-based card processing system (Adflex Virtual Terminal), or an automated system using a transaction file outputted from your accounts system and uploaded to the Adflex FilePay Service. Alternatively, you may wish to integrate with Adflex, using our Developer APIs, or except payments online using the Adflex Hosted PayPage.

To ensure a smooth setup process, Adflex will manage and guide you through each step and provide advice and help where needed. Our fundamental objective is to minimise any impact on your business and get you up and running as quickly as possible.

Before you get started, we highly recommend you familiarise yourself with how card processing works.

Considerations

To implement a successful card processing project, you must consider the following points. Failure to do so will inevitably result in delays and frustrations later on.

Before reading this section, please ensure you are familiar with card processing terminology

Understand the buyer requirements - Typically, the buyer will have specific needs with regards to how you process their card. The below are some questions you should ask the buyer.

  • What type of card will the buyer be using? The options are standard credit/debit cards (also known as level 1), Visa Purchasing Card, MasterCard Purchasing Card, Amex CPC Purchasing card (known as Level 3). Or other.
  • If the buyer is using a purchasing card, what data are you expected to capture at the point of sale? For example, Cost Centre, Purchase Order Number, Line details etc.
  • What are the expected number of invoices and the number of lines that you will be expected to process?
  • If purchasing card, the relationship between the order and the supplier invoice with regards to the number of lines, line values and total number of lines per invoice
  • Transaction currencies used.

How to choose the appropriate Adflex Card Processing solution - Knowing the anticipated volumes up front will determine whether you opt for a manual web-based card processing system (Adflex Virtual Terminal), or an automated system using a transaction file outputted from your accounts system and uploaded to the Adflex FilePay Service. Alternatively, you may wish to integrate with Adflex, using our Developer APIs, or except payments online using the Adflex Hosted PayPage.

Understand how purchasing cards work - Processing a purchase card transaction requires that the supplier invoice is entered at the same time as the payment request. Please refer to how card processing works for a complete description of the process.

Buyer VAT Reclaim - If the buyer is reclaiming VAT from the purchasing card transaction, the supplier should not send an invoice from their existing in-house accounting system, or at least ensure this invoice is marked with "Electronic Invoice Sent, Not for VAT Reclaim."

Understanding the payment cycle - A typical card transaction payment cycle is as follows;

  • The buyer places an order.
  • The supplier processes the order using an Adflex provided payment system entering the invoice information at the same time.
  • Once the transaction is authorised, the supplier receives payment with 3-4 working days.

Understanding Responsibilities Please refer to Contractual Relationships Roles and Responsibilities.

Acquiring Bank Payments - If non-UK, you may need to consider net settlement / cut off times / bulked transactions etc.

Monitoring - Card transactions can fail, this may be due to insufficient funds, disallowed supplies or merely an error.

Reconciliation - Adflex ensures commitments are in place to provide consistent support and make the process of payment initiation and acceptance as simple as possible. Using the Adflex Report Manager enables clients to view, print and export real-time transaction reports.

Contractual Relationships

Acquirer

A global banking specialising in providing card acceptance to "Supplier/Merchants" through their partnership with the Payment Service Provider.

Responsibilities include:

  • Setup of merchant within their systems and registration with the "Scheme/Association"
  • Ensure transaction requests received from "EPOS provider" are passed through to the "Scheme/Association" for authorisation by the "Issuing Bank"
  • Collect payments from the "Issuing Bank" and settle "Supplier/Merchant" bank accounts for monies due
  • Provide support to the "Supplier/Merchant" on enquiries relating to receipt of monies charged on the card
Contractual Relationship Diagram

Contractual Relationships

Adflex (Payment Service Provider)

Specialises in analysing your business processes and creating a cohesive system that delivers control back to the decision makers.

Responsibilities include:

  • Consultation with the "Supplier/Merchant" to scope best card service model of their business
  • Consultation on documentation needing to be completed for card enablement
  • Configuration and installation for card technology enabling the "Supplier/Merchant" take card payments
  • Support of software/process belonging to the direct relationship between them and the "Supplier/Merchant"
  • Ensure transactions are passed between the "Supplier/Merchant" and "Acquiring Bank" for card authorisations
  • Collection and submission of settlement to "Acquiring Bank" for transactions collected during the trading day
Buyer

The following are the roles and responsibilities of the "Buyer" relating to a card payment.

  • Ensure all cards have the correct limit to cover "Supplier/Merchant" expenses
  • Ensure the "Supplier/Merchant" is given clear details of invoice information needing on transaction
  • Ensure the "Supplier/Merchant" is aware when the card can be charged
  • Ensure the "Supplier/Merchant" is given new card details as needed
  • Notify "Supplier/Merchant" of any charges which require further clarification
Supplier/Merchant

The following are the roles and responsibilities of the "Supplier/Merchant" relating to a card payment.

  • Ensure all documentation is completed accurately as required by the "EPOS provider" or "Acquiring Bank"
  • Ensure all invoice data is present on transaction as per the agreement with "Client"
  • Ensure card is only charged in accordance with the approval from "Client"
  • Monitor transactions and raise issues regarding card declines with "EPOS provider" or "Client"
  • Work with "Acquirer" to ensure all charges made on the card settled with their bank account
Issuer

The following are the roles and responsibilities of the "Issuing Bank" relating to a card payment

  • Provide cards as requested by the "Buyer"
  • Settlement of funds with the "Acquirer"
  • Provide reporting and statements to "Buyer" on all charges

Adflex FilePay Service

Introduction to the Adflex FilePay Service

For suppliers who need to accept Purchasing Cards but do not want to introduce any software changes, Adflex have developed a flexible FilePay Service.

Without making any changes to their existing systems, most suppliers are able to export data in some form e.g. csv files, e-invoices, custom reports or even by way of an intercepted printer file. Adflex are able to analyse this data and map it to the VGIS and LID format filling in any gaps with default values and rules based look ups

By involving the cardholder in the setup process we can also ensure that certain key fields i.e. cost centres, purchase order numbers etc. are always populated correctly. This means that the cardholder always receives consistent quality data

File interchange

Even legacy systems are often able to produce simple csv exports or customised reports which can be used to authorise card transactions.

Fewer errors

Removing the need to manually key purchasing card transaction information means that the data provided to the cardholder will be accurate, which in turn means fewer queries.

Minimal expertise required

Production of a simple delimited file can usually be done in house without involvement of any IT resource.

Adaptable

Adflex are able to accept files in a wide range of formats and can even be customised to your own specific format if required.

Adflex FilePay Service is aimed at merchants who need to be able to accept card payments including Level 3 purchase cards (VGIS/MCLID/AMEX CPC). It performs two main functions:

  • Financial – The buyers purchase card will be charged for each invoice that is processed; All funds will be settled into your existing credit card merchant account.
  • Management Information – Level 3 electronic invoice information will be relayed to the buyer via the bank network. Your invoices will be received electronically and no paper based invoice is required. This is a HMRC approved invoicing process.
  • Adflex FilePay Service is ideal in the following situations:
  • The merchant is unable to (or does not want to) develop a custom interface to the Adflex Payment Gateway (APG).
  • Time constraints do not allow development of a custom interface to the APG.
  • IT restrictions do not allow modification of existing systems to interface to the APG.
  • IT restrictions may forbid the use of 3rd party software.
  • You are already producing a consolidated invoice file and do not want to change from this.
5.1 How does the Adflex FilePay Service work?

The process is simple:
1. Export the transaction information and create a Request file (.req).
2. Upload the Request file to Adflex via our FilePay Web Upload service.
3. Adflex will return a Response file giving the authorisation results via email.
4. Either import the Response file to update your GL or manually update them.

5.2 What file formats can you accept?

You can either:
1. Use a file format as determined by Adflex (see 'Standard File Format' section).
2. Use a file in a format of your own choice. We are able to accept files in a wide range of formats including XLS, CSV, XML, PRN etc. We are happy for you to send us a sample file so that we may check it for suitability.

5.3 Security

Buyer card information is pre-registered using Adflex Card Registration Service (ACRS). This simple web page allows you to enter your buyer’s name, invoice address, card number, card expiry, cost centre codes etc. onto Adflex’s PCI DSS compliant card vault. A ‘Token’ is then issued which is used as a look up to this information which removes the need for sensitive information to be included in your upload file.

5.4How do I upload the file?

There are a number of ways to upload your file including:
1. Windows/Linux/Java service agent – Supplied by Adflex
2. Secure email

Once processing is completed, two Response files will be delivered back to the Response folder. One file is a human readable processing summary, and the other is a delimited data file designed to be imported into your back office system.


Getting Started with Adflex FilePay Service

Here is a check list to get you started

  • Choose the file format you wish to use
  • Choose the file upload option you wish to use

CSV Standard Level 3 Request File Format

Please note all monetary and quantity fields must be zero to positive values. Negative values will be rejected

Header
Field No Field Name Type Size Mode Description
1 PFGID String 30 M Your Adflex Account Number - provided by Adflex when you sign up
2 DocumentType String 1 M I=Invoice, C=Credit
3 InvoiceNumber String 6-12 M Invoice Number. Must be unique and between 6-12 characters
4 DocumentDate Date 10 M Invoice Date. Formatted as YYYY-MM-DD e.g. 2015-06-02
5 CostCentre String 80 O Cost Centre
6 BuyersRef String 80 O Buyer Reference
7 PONumber String 35 O Purchase Order Number
8 BYAccCode String 50 M Buyer Account Code - Used to look up buyer details from Adflex configuration
9 BYVATNumber String 13 O Buyer VAT Number - Only used for cross border transactions
10 CardToken String 50 O Unique key used to look up pre-registered card details or if using real card, then use format: '#22;cardnumber;expirydate as MMYY'
For example: #22;4539791001730106;1115
Encryption must be used if using real card numbers
11 PaymentCurrency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
12 Net Decimal 12.2 M Document Net Value (after discount)
13 Discount Decimal 12.2 O Document Header Discount Value. If no discount, default to 0.00
14 Tax Decimal 12.2 M Document Tax (VAT) Value
15 Gross Decimal 12.2 M Sum of Net+Tax
Lines
Field No Field Name Type Size Mode Description
16 LineNumber Integer 3 M Line number - Starting at 1 incrementing by 1 for each line
17 VPartNumber String 80 O Part Number
18 VPartDescription String 80 M Part Description
19 CommodityCode String 10 O Commodity Code - Only use a valid code or leave blank
20 UOM String 12 M Unit Of Measure which Qty refers to (Each/Per Metre/Kg etc.). If unit price is zero then set to FOC
21 Qty Decimal 12.4 M Quantity of items
22 Unit Decimal 12.4 M Unit price of line item
23 LineTotal Decimal 12.2 M Sum of (Qty*Unit)-LineDiscount
24 Discount Decimal 12.2 O Line discount deducted from sum of Qty*Unit. If no discount, default to 0.00
25 TaxCode String 1 M Line Tax Code - S=Standard, E=Exempt, Z=Zero, R=Reduced
26 TaxRate Decimal 12.2 M Tax Rate Percentage
27 TaxAmount Decimal 12.2 O If TaxTreatment is NLL (Net Line Level) then Sum of ((Qty * UnitPrice)-LineDiscount)*LineTaxRate otherwise set to zero

CSV Standard Level 1 Request File Format

Please note all monetary and quantity fields must be zero to positive values. Negative values will be rejected

Header
Field No Field Name Type Size Mode Description
1 PFGID String 30 M Your Adflex Account Number - provided by Adflex when you sign up
2 DocumentType String 1 M I=Invoice, C=Credit
3 InvoiceNumber String 6-12 M Invoice Number. Must be unique and between 6-12 characters
4 TransactionDate Date 10 M Date of transaction. Formatted as YYYY-MM-DD e.g. 2015-06-02
5 CostCentre String 80 O Cost Centre
6 BuyersRef String 80 O Buyer Reference
7 PONumber String 35 O Purchase Order Number
8 CardToken String 50 O Unique key used to look up pre-registered card details or if using real card, use format as: '#22;cardnumber;expirydate as MMYY'
For example: #22;4539791001730106;1115
Encryption must be used if using real card numbers
9 PaymentCurrency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
10 Gross Decimal 12.2 M Card amount

CSV Extended Level 3 Request File Format

Please note all monetary and quantity fields must be zero to positive values. Negative values will be rejected

Header
Field No Field Name Type Size Mode Description
1 PFGID String 30 M Your Adflex Account Number - provided by Adflex when you sign up
2 DocumentType String 1 M I=Invoice, C=Credit
3 InvoiceNumber String 6-12 M Invoice Number. Must be unique and between 6-12 characters
4 DocumentDate Date 10 M Invoice Date. Formatted as YYYY-MM-DD e.g. 2015-06-02
5 CostCentre String 80 O Cost Centre
6 BuyersRef String 80 O Buyer Reference
7 PONumber String 35 O Purchase Order Number
8 BYAccCode String 50 M Buyer Account Code - Used to look up buyer details from Adflex configuration
9 BYVATNumber String 13 O Buyer VAT Number - Only used for cross border transactions
10 CardToken String 50 O Unique key used to look up pre-registered card details or if using real card, then use format: '#22;cardnumber;expirydate as MMYY'
For example: #22;4539791001730106;1115
Encryption must be used if using real card numbers
11 PaymentCurrency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
12 Net Decimal 12.2 M Document Net Value (after discount)
13 Discount Decimal 12.2 O Document Header Discount Value. If no discount, default to 0.00
14 Tax Decimal 12.2 M Document Tax (VAT) Value
15 Gross Decimal 12.2 M Sum of Net+Tax
16 BYName String 50 O Buyer Name
17 BYStreet1 String 50 O Buyer Address Line 1
18 BYStreet2 String 50 O Buyer Address Line 2
19 BYStreet3 String 50 O Buyer Address Line 3
20 BYCity String 50 O Buyer Address City
21 BYCounty String 50 O Buyer Address County
22 BYPostcode String 20 O Buyer Address Zip/Postcode
23 BYCountryCode String 3 O Three character ISO 3166-1 alpha-3 Country Code
24 BYContactName String 50 O Buyer Contact Name
25 DPName String 50 O Delivery Point Name
26 DPStreet1 String 50 O Delivery Point Address Line 1
27 DPStreet2 String 50 O Delivery Point Address Line 2
28 DPStreet3 String 50 O Delivery Point Address Line 3
29 DPCity String 50 O Delivery Point Address City
30 DPCounty String 50 O Delivery Point Address County
31 DPPostcode String 20 O Delivery Point Address Zip/Postcode
32 DPCountryCode String 3 O Three character ISO 3166-1 alpha-3 Country Code
33 DPContactName String 50 O Delivery Point Contact Name
Lines
Field No Field Name Type Size Mode Description
34 LineNumber Integer 3 M Line Number - Starting at 1 incrementing by 1 for each line
35 VPartNumber String 80 O Part Number
36 VPartDescription String 80 M Part Description
37 CommodityCode String 10 O Commodity Code - Only use a valid code or leave blank
38 UOM String 12 M Unit Of Measure which Qty refers to (Each/Per Metre/Kg etc.). If unit price is zero then set to FOC
39 Qty Decimal 12.4 M Quantity of items
40 Unit Decimal 12.4 M Unit price of line item
41 LineTotal Decimal 12.2 M Sum of (Qty*Unit)-LineDiscount
42 Discount Decimal 12.2 O Line discount deducted from sum of Qty*Unit. If no discount, default to 0.00
43 TaxCode String 1 M Line Tax Code - S=Standard, E=Exempt, Z=Zero, R=Reduced
44 TaxRate Decimal 12.2 M Tax Rate Percentage
45 TaxAmount Decimal 12.2 O If TaxTreatment is NLL (Net Line Level) then Sum of ((Qty * UnitPrice)-LineDiscount)*LineTaxRate otherwise set to zero
46 BYPartNumber String 35 O Buyer part number
47 BYPartDescription String 80 O Buyer part description

Custom Request Format

If you are unable to create a FilePay request file in any of the Adflex standard formats, we can look at existing files your system is able to export and create a custom mapping. For Example an invoice report, EDI file etc

Push Payments CSV Level 1 Request File Format

Please note all monetary and quantity fields must be zero to positive values. Negative values will be rejected

Header
Field No Field Name Type Size Mode Description
1 PFGID String 30 M Your Adflex Account Number - provided by Adflex when you sign up
2 DocumentType String 1 M I=Invoice, C=Credit
3 InvoiceNumber String 6-12 M Invoice Number. Must be unique and between 6-12 characters
4 DocumentDate Date 10 M Invoice Date. Formatted as YYYY-MM-DD e.g. 2015-06-02
5 SULookUpCode String 50 M Supplier Lookup Code - Used to look up supplier payment details from Adflex configuration
6 PaymentCurrency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
7 Gross Decimal 12.2 M Total payment value
8 ClientRef1 String 50 O Additional references. Note: target system may truncate
9 ClientRef2 String 50 O Additional references. Note: target system may truncate
10 ClientRef3 String 50 O Additional references. Note: target system may truncate
11 ClientRef4 String 50 O Additional references. Note: target system may truncate
12 ClientRef5 String 50 O Additional references. Note: target system may truncate
13 ClientRef6 String 50 O Additional references. Note: target system may truncate

CSV Response File Format

Standard Response File Format
Field No Field Name Type Size Mode Description
1 ID Integer 1-9 M Adflex generated ID (eg. 100025)
2 Batch String 1 M Batch number
3 TransactionRef String 1-12 M Transaction reference from submitted file
4 TransactionGUID GUID 1-40 M Transaction GUID returned from APG
5 Type String 1 M Transaction type (I=Invoice, C=Credit)
6 Value Decimal 12.2 O Transaction value
7 Currency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
8 CardName String 50 O Card Issuer
9 CardScheme String 50 O Card Scheme
10 TID String 8 M Transaction Terminal TID
11 MID String 15 M Merchant ID used to process transaction
12 MsgNo String 4 M Authorisation message number (0000-9999)
13 AVSCVC String 8 O Transactions AVS/CVC response
14 ReferralMsg String 20 O Referral message (eg. "Phone 01277 268755")
15 AuthCode String 15 O Authorisation code
16 StatusCode Integer 2 M Transaction status code (8=Auth, 9=Decline, 19=Error, 20=ReferralA, 21=ReferralB)
17 ResponseMsg String 20 O Response message (Authorised, Declined etc.)

CSV Response File Format

Standard Response File Format
Field No Field Name Type Size Mode Description
1 ID Integer 1-9 M Adflex generated ID (eg. 100025)
2 Batch String 1 M Batch number
3 TransactionRef String 1-12 M Transaction reference from submitted file
4 TransactionGUID GUID 1-40 M Transaction GUID returned from APG
5 Type String 1 M Transaction type (I=Invoice, C=Credit)
6 Value Decimal 12.2 O Transaction value
7 Currency String 3 M Three character ISO 4217 transaction currency code e.g. GBP,EUR
8 CardName String 50 O Card Issuer
9 CardScheme String 50 O Card Scheme
10 TID String 8 M Transaction Terminal TID
11 MID String 15 M Merchant ID used to process transaction
12 MsgNo String 4 M Authorisation message number (0000-9999)
13 AVSCVC String 8 O Transactions AVS/CVC response
14 ReferralMsg String 20 O Referral message (eg. "Phone 01277 268755")
15 AuthCode String 15 O Authorisation code
16 StatusCode Integer 2 M Transaction status code (8=Auth, 9=Decline, 19=Error, 20=ReferralA, 21=ReferralB)
17 ResponseMsg String 20 O Response message (Authorised, Declined etc.)

Adflex FilePay Service - File Naming Conventions

Request Files

Each FilePay Request file must be uniquely named to prevent duplicate files from being submitted. The bureau service will check and reject a duplicate file and send an email to the recipient notification list which is configured during the initial setup of the service.

The recommended file naming format is;
[YourCompanyName]_[BatchNumber].[FileExtension]

  • YourCompanyName - Between 1 and 12 characters with no spaces
  • BatchNumber - Between 6 and 18 alphanumeric with no spaces
  • FileExtension - Between 1 and 3 alphanumeric with no spaces conforming to MS Windows file system file naming conventions

The BatchNumber doesn't have to be sequential number, although this may help you in tracking and reconciling submissions later on and can be any combination of characters and numbers. For example using a datetime stamp formatted like: 'yyyyMMddHHmmss'

Example File Naming Sequence:

  • First file name - CompanyName_000001.REQ
  • Second file name - CompanyName_000002.REQ
  • Third file name - CompanyName_000003.REQ
  • and so on..

Other file naming formats can be accommodated, but please consult with Adflex first.

Response Files

Response Files typically have the same name as the Request File but with an extension of .RES

Adflex FilePay Service - File Upload Options

Adflex provide two means of uploading your FilePay Request Files

FilePay Request File upload using the Adflex Web Portal

Adflex FilePay request files can be uploaded using a web based portal.

Please see the instructions below on how to manually upload a payment file to Adflex.

1. Login to the web portal with the credentials supplied by Adflex

2. Click the ‘FilePay’ tab at the top of the page or click ‘Upload a Payment File’ from the list

3. To upload your payment file, click ‘Choose’ locate your file and click ‘Open’. Finally click ‘Upload’

4. After clicking upload your payment file will automatically process and appear in the file log on the right-hand side of the page.

5. Once the payment file has processed you will receive a notification email from Adflex.

FilePay Request File upload using the Adflex FilePay Service Agent

The Adflex FilePay Service Agent is a Windows32 service agent that can be run on any network or standalone PC/Server with an Internet connection. It's function is to monitor a designated folder for an Adflex Bureau file which matches a configured specification, and to securely deliver the bureau request file to the Adflex Payment Gateway for processing.

Once processing is completed, three response files will be delivered to a designated folder. One file is a human readable (.txt) processing summary, and the other two are machine readable files designed to be imported into the host system, including a (.csv) version of the summary values, and a (.res) itemised results file.

Technical Specification

The service is designed to run as a background service under the Windows Local Service account context and does not have any user interface. We therefore provide a UDP monitor application (PFGUDPMonitor.exe), to monitor the UDP messages sent by the service. The IP address and Port of the UDP messages is set in the configuration and stored on the host machine registry.

Overview

  • Application - Win32 Service
  • Database - none required
  • Certificates - none required
  • Local registry - [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\adflex.bureau.clientagent_[your PFGID value]\Parameters]
  • Adflex connectivity - Fixed IP/https connection to Adflex Payment Gateway across the public internet
  • Access to file folders - Local/UNC. R/O polled folder for request files and R/W access to response, log and archive folders
  • User account - Run using the Local System account with low privileges
  • Installation - Code signed MSI installer, downloaded from Adflex
  • Service activity monitoring - by default UDP activity messages are emitted on 127.0.0.1:600

System Requirements

  • Microsoft® Windows 2003 Onwards
  • 1 GB free hard disc space
  • Screen resolution: n/a
  • Microsoft® Dot Net framework V2.0
  • Fixed IP public internet connection via https

Installation

  • Download Adflex Bureau Service Agent
  • Download Adflex UDP Monitor
  • Install FilePay Service Agent on target server/PC as administrator
  • Enter FilePay Service Agent installation Config parameters as supplied in email from the Adflex Support Team



  • Install Adflex UDP Monitor on required server/PC as administrator
  • Start Adflex UDP monitor listening on the configured port (By default service emits UDP activity messages to 127.0.0.1:600. Edit service registry entry to change)
  • In Windows SCM (Services Control Manager) start the Adflex FilePay Service
  • You should now see messages from the Adflex FilePay service showing on the UDP monitor

Registry Settings

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\adflex.bureau.clientagent_[your PFGID value]\Parameters]


Default Registry Settings
Key Description Default (Decimal) Value
DebugFlags Adflex Reserved 0
PFGID Adflex assigned account code Supplied in config email
SyslogIP UDP activity monitor IP address 127.0.0.1
SyslogPort UDP activity monitor Port 600
FileWaitSeconds Number of seconds to wait after file found 3
UploadPollingSeconds Upload request file polling frequency in seconds 1800
DownloadPollingSeconds Download response files polling frequency in seconds 1800
ReqFileMask Request file mask Filename extension of file to be uploaded - Set to enc if encryption is enabled
ReqFilePath Request file path Local file path where request files are uploaded from. Note this must be a path visible by the service agent user permissions. Mapped drives are not supported, UNC paths are supported
ResFilePath Response file path Local file path where Result files are saved. Note this must be a path visible by the service agent user permissions. Mapped drives are not supported, UNC paths are supported
LogFilePath Log file path Local file path where Log files are saved. Note this must be a path visible by the service agent user permissions. Mapped drives are not supported, UNC paths are supported
ArcFilePath Archive file path Local file path where uploaded files are archived. Note this must be a path visible by the service agent user permissions. Mapped drives are not supported, UNC paths are supported
PurgeLogFilesDays Number of days to keep log files 90
PurgeArcFilesDays Number of days to keep archive files 90
PFGAccessKey Adflex assigned Supplied in config email
SessionTimeOutSeconds Adflex assigned 900
UserCode Adflex assigned Supplied in config email
UserPW Adflex assigned Supplied in config email
CheckFileColValueExpression Adflex assigned Supplied in config email
CheckFileNameMask Adflex assigned Supplied in config email
EncryptDataPK Public Key Public key provided by Adflex used to encrypt data
EncryptData Flag to enable/disable encryption 0=Disabled, 1=Enabled
NotificationEmailListOnError Optional on file upload error email recipient list, separated by semicolons example: contact1@myemail.com;contact2@myemail.com
AppID Application ID Default value: 4

Customer Message Transaction Service Agent

The Adflex cmts Service Agent is a Windows32 service agent that can be run on any network or standalone PC/Server with an Internet connection. It's function is to monitor a TCP port for a transaction message and to securely deliver the message to the Adflex Payment Gateway for processing.

Technical Specification

The service is designed to run as a background service under the Windows Local Service account context and does not have any user interface. We therefore provide a UDP monitor application (PFGUDPMonitor.exe), to monitor the UDP messages sent by the service. The IP address and Port of the UDP messages is set in the configuration and stored on the host machine registry.

Overview

  • Application - Win32 Service
  • Database - none required
  • Certificates - none required.
  • Encryption - Gold standard PKI encrypted string tunnelled via TLS over HTTPS
  • Local registry - [HKEY_LOCAL_MACHINE\SOFTWARE\Adflex\CMTS\759617457\your PFGID value]
  • Local network - Default TCP socket default listening port 5051
  • Adflex connectivity - Fixed IP/https connection to Adflex Payment Gateway across the public internet
  • Access to file folders - Local/UNC UDP log folders
  • User account - Run using the Local System account with low privileges
  • Installation - Code signed MSI installer, downloaded from Adflex
  • Service activity monitoring - by default UDP activity messages are emitted on 127.0.0.1:600

System Requirements

  • Microsoft® Windows 2008 Onwards
  • 1 GB free hard disc space
  • Screen resolution: n/a
  • Microsoft® Dot Net framework V4.0
  • Fixed IP public internet connection via https

Installation

  • Download Adflex CMTS Service Agent
  • Download Adflex UDP Monitor
  • Install CMTS Service Agent on target server/PC as administrator
  • Enter CMTS Service Agent installation Config parameters as supplied in email from the Adflex Support Team
  • Install Adflex UDP Monitor on required server/PC as administrator
  • Start Adflex UDP monitor listening on the configured port (By default service emits UDP activity messages to 127.0.0.1:600. Edit service registry entry to change)
  • In Windows SCM (Services Control Manager) start the Adflex FilePay Service
  • You should now see messages from the Adflex CMTS service showing on the UDP monitor

Registry Settings

[HKEY_LOCAL_MACHINE\SOFTWARE\Adflex\CMTS\759617457\your PFGID value]


Default Registry Settings
Key Description Default (Decimal) Value
DebugFlags Adflex Reserved 0
PFGID Adflex assigned account code Supplied in config email
SyslogIP UDP activity monitor IP address 127.0.0.1
SyslogPort UDP activity monitor Port 600
LogFilePath Log file path Local file path where Log files are saved. Note this must be a path visible by the service agent user permissions. Mapped drives are not supported, UNC paths are supported
PurgeLogFilesDays Number of days to keep log files 90
PFGAccessKey Adflex assigned Supplied in config email
AuthenticationToken Adflex authentication token Supplied in config email
EncryptData Flag to enable/disable encryption 0=Disabled, 1=Enabled
EncryptDataKey Key Store Name Local machine key store name
EncryptDataPK Public Key Public key provided by Adflex used to encrypt data
NotificationEmailListOnError Optional on file upload error email recipient list, separated by semicolons example: contact1@myemail.com;contact2@myemail.com

Account Maintenance

Upload Card Registration File Schema


Using Microsoft Excel to create CSV files

If you are using Excel to create a CSV file, card numbers may be treated as real numbers in Excel resulting in rounding or formatting as an exponent number!
To work around this please ensure card numbers are prefixed with an apostrophe '

For further information: http://office.microsoft.com/en-us/excel-help/display-numbers-as-credit-card-numbers-HA010236840.aspx

Card Security

Card submission files uploaded to the Adflex Registration Portal will be delivered using secure SSL encryption and processed on our PCI DSS accredited platform. However, as your submission file will initially be in plain readable text, you must observe the relevant PCI DSS security policies concerning card number security.

The sending of card data by non-secure methods contravenes PCI DSS compliance.

For further information about PCI DSS https://www.pcisecuritystandards.org

How to upload your registered card submission file

You will be provided with login details to our secure web upload portal which will allow you to securely upload your submission files.

For automated upload of submission files, please contact Adflex for details of our client side service agent.

Upload Card Registration Schema

Field Field Name DataType Mode Comments
1 BuyerContactName String(50) Mandatory Buyer Account Contact Name (the card holder name)
formatted as: firstname+space+lastname
2 CardAlias String(50) Mandatory Pre-agreed between client and Adflex during setup and is the code used to look up the card when processing a submitted FilePay transaction file.
This can be overridden by the config CardAliasKeyParseRule agreed with Adflex during setup.
3 MID String(20) Optional Merchant ID. If blank, then will use default Adflex configured merchant
4 CardNumber Number(20) Mandatory The card number to register
5 CardExpiry Number(4) Mandatory Card Expiry Date. Format MMYY
6 CardStart Number(4) Optional Card Start Date. Format MMYY
7 CardIssueNumber Number(2) Optional Card issue number
8 UpdateMode Number(1) Optional How the Adflex system is updated.
0 = Raise error if CardAlias is not found
1 = Create CardAlias if not found

If blank, then will default to UpdateMode of 1


Testing and Go Live

This section covers what steps are needed in order to bring your development from testing to go live.

The Go Live Process

This section covers what steps are needed in order to bring your development from testing to go live.

Choose your Adflex Service

This Go Live Process is only applicable to the following Adflex services:

  • Adflex Hosted Pay Page
  • Adflex Web Services
  • Adflex FilePay Service
  • Adflex Chip and PIN API
  • Adflex Client API

Request an Adflex Test Account

In order to prepare to go live, you must request a APG Test Account from Adflex. This will give you a realistic simulation of the live environment and allow you to develop your application without having to use real cards in the live environment.

Test Cards

We have made available a number of test cards to enable you to test simulated transactions using a wide range of card schemes.

Adflex test cards must only be used with Adflex services and should never be used in any live environment.

Test Scripts

Once you have developed your application to a production level, you must run the relevant test script that will exercise your system prior to going live.

These scripts can be used at any part of your development cycle and the results will be ignored by Adflex until you book the final Go Live Sign-off Testing below.

Go Live Sign-off Testing

When you are ready to go live, please book a go live test slot with Adflex by sending an email to support@adflex.co.uk using the following subject line format: "XXXXXXXX Go Live Test Request" where XXXXXXXX is your Adflex Account Number (PFGID) given to you when your APG Test Account has been issued.

The body of this request email must include the following information;

  • Your required test date and time
  • Your testers contact name, email address and phone number
  • The Adflex Service to be tested
  • Using Test Script name

Once we have notified you of your allocated test slot, you must run all tests in the chosen test script, adding the transaction outcome and any comments you may have against each test.

If there are any tests you are unable to perform, please state the reason in the testers comments and move onto the next test. For example 'unable to perform this test as order entry screen will not allow invalid card numbers to be entered'

Once you have completed the script, please notify support@adflex.co.uk that you have completed all the tests in the test script.

Go Live Approval Notification

We will notify you within 5 working days of the outcome of your tests with either a go live sign off or a request to redo and/or your comment on any failed tests.

If approved, you are then ready to progress to the next stage, Live Proving.

Live Proving

In order to ensure the end to end connectivity is correct, you must put through a small number of low value real transactions to prove that the expected transaction funds are received in your bank account, and in the case of Purchasing Cards, the buyer is seeing the correct data in their reporting system.

Once the Living Proving stage is complete and you (and if appropriate, the buyer) is happy that all is working ok, you are then ready to go live.

Early Life Monitoring

We strongly advise you to monitor all transaction end to end flows for at least a few weeks to ensure your applications are working as expected.

Test Cards

The following Adflex test cards must only be used with Adflex services and should never be used in any live environment.

Adflex provides you with a customised set of tests to run prior to launch. In addition you may formulate your own tests using any of the test cards from the table below:

  • The Adflex test environment will respond with a particular outcome based on the card number used.
  • Use any valid (in date) expiry date.
  • Use any security code of the appropriate length (3 digits for Visa/MC and 4 for Amex).
Level 1 CREDIT Cards
Outcome MasterCard MasterCard 2 Range Visa Amex Retail
Auth 5185 5110 0000 0010 2223 0000 1001 1804 4012 0010 3627 5556 3782 8224 6310 005
Decline 5185 5150 0000 0045 2223 0000 1001 0095 4012 0010 3629 8889 3782 8224 6317 000
Refer 5185 5150 0000 0052 2223 0000 1001 0202 4012 0010 3685 3337 3782 8224 6320 004
Error 5185 5110 0000 0002 2223 0000 1001 0194 4012 0010 3698 3332 3782 8224 6319 006
Level 3 CREDIT Cards
Outcome MasterCard Visa Amex CPC
Auth 5569 5100 0000 0018 4715 0570 0000 0107 3742 9048 2911 992
Decline 5569 5000 0000 2296 4715 0570 0000 0123 3742 9048 2907 990
Refer 5569 5000 0000 2312 4715 0570 0000 0164 3742 9048 2920 993
Error 5569 5000 0000 2338 4715 0599 9900 0437 3742 9048 2919 995
Level 1 DEBIT Cards
Outcome MasterCard Visa Visa Electron Maestro Intl Maestro
Auth 5573 4899 0000 0028 4137 3356 0011 7780 4844 2155 0011 5643 5033 9619 8900 0008 18 6799 9901 0000 0000 019
Decline 5573 4899 0000 0721 4137 3356 0011 0785 4844 2155 0011 7649 5033 9619 8900 0381 15 6799 9901 0000 0000 076
Refer 5573 4899 0000 2024 4137 3356 0011 2088 4844 2155 0012 0643 5033 9619 8900 0320 19 6799 9901 0000 0000 209
Error 5573 4899 0000 1927 4137 3356 0011 1981 4844 2155 0011 9645 5033 9619 8900 0319 12 6799 9901 0000 0000 191

Test Scripts

Note these test scripts must only be used with Adflex products and services and should never be used in any live environment

Please contact Adflex at support@adflex.co.uk


Appendix

Error Codes

Error Code Primary Application Error Description Severity Level
50001 ERP Ok Green
51400 APG APACS30: ERROR_CODE_EFT_MSG_MISMATCH Yellow
51401 APG APACS30: ERROR_CODE_EFT_TXLRC Yellow
51402 APG APACS30: ERROR_CODE_EFT_NOCARRIER Yellow
51403 APG System timeout Yellow
51404 APG Timeout connecting to Acquirer Yellow
51405 APG APACS30: ERROR_CODE_EFT_MAXTXRETRY Yellow
51406 APG APACS30: ERROR_CODE_EFT_SOFTWAREERROR Yellow
51407 APG APACS30: ERROR_CODE_EFT_RXLRC Yellow
51450 APG ERROR_CODE_EFT_RAS_SUCCESS Yellow
51451 APG ERROR_CODE_EFT_RAS_FAIL Yellow
51452 APG ERROR_CODE_EFT_RAS_ALREADY_CONNECTED Yellow
51500 APG AP29: No data Yellow
51501 APG Missing Acquirer Yellow
51502 APG AP29: Invalid target path Yellow
51503 APG Invalid MID Yellow
51504 APG AP29: File create error Yellow
51505 APG AP29: Invalid seg1 tx code Yellow
51506 APG AP29: Invalid seg1 expiry data Yellow
51507 APG AP29: ERROR_CODE_EFT_SUB29_UPDATELOG_FAILED Yellow
51508 APG AP29: ERROR_CODE_EFT_SUB29_FILEWRITE_ERROR Yellow
51509 APG AP29: ERROR_CODE_EFT_SUB29_TEST_FAILED Yellow
51510 APG AP29: ERROR_CODE_EFT_SUB29_MISSING_AUTH_CODE Yellow
51511 APG AP29: ERROR_CODE_EFT_SUB29_INVALID_ISSUE_NO_LEN Yellow
51512 APG AP29: ERROR_CODE_EFT_SUB29_INVALID_CARD_NO Yellow
51513 APG AP29: ERROR_CODE_EFT_SUB29_INVALID_FTP_PUT_FILE_SRC_PATH Yellow
51514 APG AP29: ERROR_CODE_EFT_SUB29_MISSING_29_FILE Yellow
51515 APG AP29: ERROR_CODE_EFT_SUB29_CREATE_SCRIPT_FILE_FAILED Yellow
51516 APG AP29: ERROR_CODE_EFT_SUB29_WRITE_SCRIPT_FILE_FAILED Yellow
51517 APG AP29: ERROR_CODE_EFT_SUB29_FTP_TX_FAILED Yellow
51518 APG AP29: ERROR_CODE_EFT_SUB29_FTP_RX_FAILED Yellow
51519 APG AP29: ERROR_CODE_EFT_SUB29_FTP_RX_FILENOTFOUND Yellow
51520 APG AP29: ERROR_CODE_EFT_SUB29_SUBFILE_NOT_AVAILABLE Yellow
51521 APG ERROR_CODE_EFT_LOG_TOT_TX_COUNT_ERROR Yellow
51522 APG ERROR_CODE_EFT_LOG_SALES_SUM_ERROR Yellow
51523 APG ERROR_CODE_EFT_LOG_REFUNDS_SUM_ERROR Yellow
51524 APG ERROR_CODE_EFT_LOG_NET_SUM_ERROR Yellow
51525 APG Missing VGIS Data Yellow
51526 APG Invalid VGIS Data Yellow
51527 APG ERROR_CODE_EFT_CLASS_GEN29_ERROR Yellow
51531 APG Invalid Submission File Seq no (<=0) Yellow
51550 APG TID Lockout. Please retry in 3 minutes Yellow
51551 APG APAC30: ERROR_CODE_EFT_30_MSG_NO_OVERFLOW Yellow
51552 APG APACS30: ERROR_CODE_EFT_30_NO_DATA_IN_WRK Yellow
51553 APG APACS30: ERROR_CODE_EFT_30_CREATE_AUTH_BATCHHEADER_FAILED Yellow
51554 APG APACS30: ERROR_CODE_EFT_30_UPDATE_AUTH_BATCHHEADER_FAILED Yellow
51555 APG APACS30: ERROR_CODE_EFT_30_NO_TIDS_AVAILABLE Yellow
51556 APG APACS30: ERROR_CODE_EFT_30_AUTH_BATCH_ALL_SKIPPED Yellow
51557 APG APACS30: ERROR_CODE_EFT_30_UNSUPPORTED_MSG_TYPE Yellow
51558 APG APACS30: ERROR_CODE_EFT_30_INVALID_TERM_TYPE Yellow
51559 APG APACS30: TID must equal the original to reverse transaction Yellow
51560 APG APACS30: The message number must be one greater than the original transaction to reverse Yellow
51561 APG APACS30: Time between the original transaction and the reversal must be less than 30 seconds Yellow
51562 APG Invalid TransactionType Yellow
51563 APG TID invalid or not registered Yellow
51564 APG Only Authorised transactions can be reversed Yellow
51565 APG Reversal failed. Transaction has already been sett Yellow
51600 APG Create wrk failed Yellow
51601 APG File re-name failed Yellow
51602 APG Invalid document status Yellow
51603 APG Invalid card status Yellow
51604 APG In EFT queue Yellow
51605 APG Invalid host ERP bank nominal Yellow
51606 APG Nothing to do Yellow
51607 APG Missing Acquirer Yellow
51608 APG Missing card number Yellow
51609 APG Missing day phone Yellow
51610 APG Missing evening phone Yellow
51611 APG Missing postcode Yellow
51612 APG In phone hot list Yellow
51613 APG In post code hot list Yellow
51614 APG In card hot list Yellow
51615 APG Card BIN not found Yellow
51616 APG Card not supported Yellow
51617 APG Card failed LUHN check Yellow
51618 APG Found in hot list but Overridden Yellow
51619 APG Invalid Expiry Date Yellow
51620 APG Invalid Card BIN Yellow
51621 APG Invalid service Code Yellow
51622 APG Card is ATM only Yellow
51623 APG Pin Device required for this card type Yellow
51624 APG Prompt for PIN Yellow
51625 APG Card not active. Check start/valid from date Yellow
51626 APG Invalid PAN length Yellow
51627 APG Invalid Issue Number Length Yellow
51628 APG Invalid Start Number Date Yellow
51629 APG Card does not support keyed entry Yellow
51630 APG General error, extra info may follow Yellow
51631 APG Error Connecting Yellow
51632 APG Session Connection Error Yellow
51633 APG Session Connection Exception Yellow
51634 APG Winsock BG Socket Exception Yellow
51635 APG Socket Yellow
51636 APG Socket Socks Yellow
51637 APG Authentication error Yellow
51638 APG EFT session failure Yellow
51639 APG Duplicate card transaction Yellow
51640 APG General Client error see ErrorString Yellow
51641 APG Encryption error. Transaction failed Yellow
51642 APG Invalid payment token Yellow
51643 APG Missing authorisation response Yellow
51644 APG Process queued transaction error Yellow
51645 APG Failed to match transaction reference Yellow
51646 APG Failed to find merchant account Yellow
51647 APG Transaction status is Cancelled request denied Yellow
51648 APG Transaction status is Authorised request denied Yellow
51649 APG Transaction status is Declined request denied Yellow
51650 APG Check merchant manger. Note must be Numeric.",Inv Yellow
51651 APG Check merchant manger.",Invalid Merchant Number Yellow
51652 APG Check Acquirer manger field POSID. Note must be N Yellow
51653 APG Transaction value is below mininum allowable Yellow
51654 APG Transaction value is above the maximum allowable Yellow
51655 APG Cashback not supported Yellow
51656 APG Missing Transaction Reference Yellow
51657 APG Invalid Transaction Reference length Yellow
51658 APG Invalid EnhancedDataEncodingMethod Yellow
51659 APG Invalid GUID Yellow
51660 APG Missing card last four digits Yellow
51661 APG Invalid Auth Status Yellow
51662 APG Invalid Hold Status Yellow
51663 APG Invalid date format Yellow
51664 APG ERROR_CODE_EFT_FAILED_STORE_L3DATA Yellow
51665 APG Invalid CSC Yellow
51666 APG Invalid Transaction GUID for Settle Yellow
51667 APG Transaction amount exceeds the original authorised Yellow
51668 APG Transaction is marked as settled Yellow
51669 APG Can only part settle a Sale 3DS Sale Refund Yellow
51670 APG Duplicate Transaction Reference Yellow
51672 APG Invalid ISO 4217 Currency Code Yellow
51673 APG Merchant account is not setup to support 3DS Yellow
51674 APG Cardholder is not enrolled for 3DS Yellow
51675 APG Failed to decode 3DS VeRes Yellow
51676 APG Invalid Amount Yellow
51677 APG Card does not support 3DS Yellow
51678 APG 3DS transaction failed Yellow
51679 APG Authorisation has expired Yellow
51680 APG Failed to validate PaRes Yellow
51681 APG Invalid EMV Type Yellow
51682 APG Invalid TID data Yellow
51683 APG Invalid Enhanced Data Yellow
51684 APG Account disabled Yellow
51685 APG Card must be authenticated using 3DS Yellow
51686 APG Invalid Merchant URL Yellow
51687 APG Invalid Merchant Name length Yellow
51688 APG Invalid transaction Description length Yellow
51689 APG Account password expired Yellow
51690 APG Account is locked out Yellow
51691 APG Error with external 2FA. Please contact support Yellow
51692 APG You cannot settle a non-authorised transaction Yellow
51694 APG 3DS Authorise Missing 3DS Data Yellow
51699 APG Invalid test card number Yellow
51700 APG General VGIS Exception Yellow
51701 APG CoFInvalidFormat Red
51702 APG CoFInvalidFormatCofMode Red
51703 APG CoFInvalidFormatInitiatorFlag Red
51704 APG CoFInvalidFormatEntryMode Red
51705 APG CoFInvalidFormatOriginalTxRefGUID Red
51706 APG CoFOriginalTransactionNotFoundOrMarkedAsStored Red
51707 APG CoFOriginalTransactionWasDeclined Red
51900 APG Invalid column values in BatchHeader row Yellow
51901 APG Invalid column values in BatchHeader row Yellow
51902 APG Invalid column values in SummaryDocLine row Yellow
51903 APG Invalid column values in DocHeader row Yellow
51904 APG Invalid column values in DetailDocLine row Yellow
51905 APG Invalid column values in SummaryDocLine row Yellow
51906 APG DocHeader/DetailDocLine validation failed Yellow
51907 APG DocHeader/SummaryDocLine validation failed Yellow
51908 APG DocHeader/SummaryDocLine validation failed Yellow
51909 APG DocHeader/SummaryDocLine validation failed Yellow
51910 APG DocHeader/SummaryDocLine validation failed Yellow
51911 APG Invalid column values in BatchHeader row Yellow
51912 APG Invalid column values in BatchTrailer row Yellow
51913 APG Invalid column values in RegisterCard row Yellow
51914 APG Invalid column values in DeleteRegisterCard row Yellow
51915 APG Invalid column values in Card row Yellow
51916 APG Invalid column values in CardByToken row Yellow
51917 APG Invalid column values in CardSettle row Yellow
51918 APG Invalid column values in VGISDocHeader row Yellow
51919 APG Invalid column values in VGISDocSupplier row Yellow
51920 APG Invalid column values in VGISDocSupplierHO row Yellow
51921 APG Invalid column values in VGISDocSupplierMerchant r Yellow
51922 APG Invalid column values in VGISDocBuyer row Yellow
51923 APG Invalid column values in VGISDocDeliveryPoint row Yellow
51924 APG Invalid column values in VGISDocLine row Yellow
51925 APG Invalid column values in VGISDocTaxSummary row Yellow
51926 APG Invalid column values in VGISDocSupplierHO row Yellow
51927 APG Invalid column values in VGISDocSupplierMerchant r Yellow
51928 APG Invalid column values in VGISDocBuyer row Yellow
51929 APG Invalid column values in VGISDocDeliveryPoint row Yellow
51930 APG Invalid column values in VGISDocSupplierHO row Yellow
51931 APG Invalid number of columns Yellow
51932 APG Invalid VAT amount Yellow
51933 APG Transaction value does not match document value Yellow
51934 APG Line calculations are outside tolerance Yellow
51935 APG Cannot decode APGLVGIS Yellow
53000 PFG AVT Exception Red
53001 PFG PFGAdmin Exception Red
53002 PFG PFGBureau Exception Red
53003 PFG Hosted Pay Page Exception Red
53004 PFG Config Exception Red
53005 PFG Sproc Exception Red
53006 PFG General Method Error Red
53007 PFG CMTSException Red
53008 PFG AuthenticationException Red
53009 PFG GeneralException Red
53010 PFG AirPlusException Red
53011 PFG DBDirectException Red
53012 PFG DuplicateTransactionGUID Red
53013 PFG InvalidSessionLifetime Red
53014 PFG InvalidTemplateID Red
53015 PFG InvalidCardTokenTTL Red
53030 PFG Create File Error Red
53031 PFG Log Send Error Red
53032 PFG No Data Found Red
53033 PFG Open Registry Error Red
53034 PFG Registry Key Error Red
53035 PFG Open DB Error Red
53036 PFG Open DLL Error Red
53037 PFG Invalid Card String Format Red
53038 PFG Invalid Document Type Red
53039 PFG Import Documents Failed Red
53040 PFG Document Integrity Test Failed Red
53041 PFG Documents Integrity Test Failed Red
53042 PFG Document Line Sum Error Red
53043 PFG Card Data Not Found Red
53044 PFG Invalid Document Line Unit Price Red
53045 PFG Invalid Document Line Qty Red
53046 PFG Missing URI Red
53047 PFG Connect To Merchant Failed Red
53048 PFG Delete Document Failed Due To Status Red
53049 PFG Patch Already Applied Red
53050 PFG Cancel Document Failed Red
53051 PFG Release Transaction Failed Red
53052 PFG Pay Page Validation Failed Red
53053 PFG Account Not Status Clear Red
53054 PFG Skip Account Red
53055 PFG Invalid PSPID Red
53056 PFG Invalid Document Tax Treatment Red
53057 PFG Invalid Document Discount Treatment Red
53058 PFG Invalid Delimiter Count Red
53059 PFG User Not Found Red
53060 PFG Create Document Enhanced Data Failed Red
53061 PFG Create Document MCLID Data Failed Red
53062 PFG Document Not Found Red
53063 PFG Batch Number Already Assigned Red
53064 PFG Invalid Document Gross Amount Red
53065 PFG Too Many Document Tax Summaries Red
53066 PFG Unknown APG Error Red
53067 PFG Invalid Date Red
53068 PFG Send Email Failed Red
53069 PFG Default Merchant Not Set Red
53070 PFG Currencies Not Set Red
53071 PFG Merchant Currencies Not Set Red
53072 PFG Merchant Account Not Found Red
53073 PFG Change User Password Failed Red
53074 PFG Session Authentication Failed Red
53075 PFG User Password Expired Red
53076 PFG User Disabled Red
53077 PFG Client Disabled Red
53078 PFG User Password Failed Policy Check Red
53079 PFG User Locked Out Red
53080 PFG User Password Recently Used Red
53081 PFG Merchant Currency Not Supported Red
53082 PFG Default Currency Not Set Red
53083 PFG Unsupported Mode Red
53084 PFG Invalid Document TaxRate Red
53085 PFG Validation Error Red
53086 PFG Skip Document Red
53087 PFG Invalid Registration Red
53088 PFG Oversize Data Red
53089 PFG File Exists Red
53090 PFG BIN Cache Data Not Set Red
53091 PFG Application Not Assigned To Client Red
53092 PFG Merchant Disabled Red
53093 PFG Merchant Is Off-line Red
53094 PFG Duplicate Account Red
53095 PFG Value Is Null Red
53096 PFG Payment Token Expired Red
53097 PFG Payment Token Exceeds Period Usage Count Red
53098 PFG Payment Token Exceeds Period Usage Value Red
53099 PFG Payment Token Currency Not Supported Red
53100 PFG Payment Token Not Found Red
53101 PFG A2P Reason Other Red
53102 PFG A2P Reason Not Ordered Red
53103 PFG A2P Reason Missing PO Ref Red
53104 PFG A2P Reason Not Delivered Red
53105 PFG A2P Reason Missing Items Red
53106 PFG A2P Reason Incorrect Qty Red
53107 PFG A2P Reason Incorrect Value Red
53150 PFG ClientOnHold Red
53200 PFG Currency Code Not Found Red
53201 PFG Country Code Not Found Red
53202 PFG Invalid Logon Red
53203 PFG File Open Error Red
53204 PFG File Read Error Red
53205 PFG Directory Not Found Red
53206 PFG Config Error Red
53207 PFG Invalid Card Data Red
53208 PFG Card Amount not equal to Document Gross Value Red
53209 PFG Transaction Ref Already Authorised Red
53210 PFG Transaction Settle Failed Red
53211 PFG Web Form Invalid Control Count Red
53212 PFG Sproc Failed To Return Results Red
53213 PFG Method Failed To Return Results Red
53214 PFG Client Authentication hash match failed Red
53215 PFG Message hash match failed Red
53216 PFG Invalid TxRefGUID Red
53217 PFG Failed to find session key Red
53218 PFG ExpiredCardToken Red
53300 PFG 3DS Exception Red
53302 PFG AccountVerification Exception Red
53303 PFG Failed GetTransactionMerchant Red
53304 PFG Transaction Rule Data Missing Red
53305 PFG Transaction Rule Data Exception Red
54000 PFG Secret Key not found Red
54001 PFG Secret Key expired Red
54002 PFG Authentication Key not found Red
54003 PFG Authentication Key expired Red
54004 PFG Authentication Key usage exceeded Red
54005 PFG ResourceID not found Red
54006 PFG Resource Permission denied Red
54007 PFG Failed to find assigned Default Merchant Account Red
54101 PFG APIRequestHeaderValidationError Red
54102 PFG APIRequestBodyValidationError Red
54201 PFG AGDefault4XX Red
54202 PFG AGDefault5XX Red
54203 PFG AGAccessDenied Red
54204 PFG AGApiConfigError Red
54205 PFG AGAuthorizerConfigError Red
54206 PFG AGAuthorizerFailure Red
54207 PFG AGBadRequestBody Red
54208 PFG AGBadRequestParameters Red
54209 PFG AGExpiredToken Red
54210 PFG AGIntegrationFailure Red
54211 PFG AGIntegrationTimeout Red
54212 PFG AGInvalidAPIKey Red
54213 PFG AGInvalidSignature Red
54214 PFG AGMissingAuthenticationToken Red
54215 PFG AGQuotaExceeded Red
54216 PFG AGRequestTooLarge Red
54217 PFG AGResourceNotFound Red
54218 PFG AGThrottled Red
54219 PFG AGUnauthorized Red
54220 PFG AGUnsupportedMediaType Red

About GUIDs

Adflex Card Transactions are uniquely tagged with a GUID (Globally Unique Identifier). A GUID is a unique 128-bit number. Specified as a string consisting of eight hexadecimal digits followed by a hyphen, then three groups of four hexadecimal digits each followed by a hyphen, then twelve hexadecimal digits in this format: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

e.g.

{BA828AFE-0C03-4BC4-AD17-53CF3FDA2014}
Refer to these examples on how to create a GUID

Card Luhn Check

Luhn formula for calculating the PAN check digit. The following steps are involved in this calculation, which applies to any length PAN:

  1. Double the value of alternate digits beginning with the first right-hand digit (low order)
  2. Add the individual digits comprising the products obtained in (a) to each of the unaffected digits in the original number
  3. Subtract the total obtained in (a) from the next higher number ending in 0 (this is the equivalent of calculating the 'ten complement' of the low order digit (unit digit) of the total)
  4. The resultant digit is the PAN check digit that should equal the last digit of the PAN

Note. If the total obtained in (a) is a number ending in zero (30, 40 etc.), the check digit is 0.

For more information on Card LUHN check refer to Luhn Algorithm

Card AVS/CVC Status Response

When is an AVS/CVC check performed?

The AVS/CVC check takes place when a transaction has an amount greater than 0. So therefore will not be triggered when a card is being registered.

If you require a transaction to carry out a AVS/CVC check on a card being registered an alternative solution is to perform a 'card payment and register card'. This will ensure a transaction has been authorised and will trigger the checks.

Note: AVS/CVC settings are applied at account level to a merchant account by Adflex and will be applied across all transactions processed under the merchant account with an amount greater than 0.

Some Adflex APIs give you the opportunity to test the issuers risk response of the authorised transactions CVC and Address verification enabling you to accept or reject the transaction.

If you do not want to accept the risk and reject the transaction, Adflex will attempt a reversal to cancel the transaction.

Value
Position 1 2 4 8 Description
First Digit
CVC
Not Checked
Match
Not Matched
Reserved
Second Digit
Postcode Numerics
Not Checked
Match
Not Matched
Partial Match
Third Digit
Address Numerics
Not Checked
Match
Not Matched
Partial Match
Fourth Digit
Authorising Entity
Card Acceptor
Acquirer
Card Scheme
Card Issuer

Values other than 0, 1, 2, 4 or 8 are not valid in digit positions 1 to 4.

A value of zero in any digit position indicates that no additional information is available

If the Authorising Entity is not known, digit 4 is set to zero and the authoriser is assumed to be the issuer.

Processing of these data elements will be by separate agreement between Acquirers and Card Acceptors.

Card Support Flags

Value (Hex) Description Value (Hex) Description
1 Keyed entry allowed 1000 Reserved
2 Cashback supported 2000 Reserved
4 CSCAVS supported 4000 Reserved
8 VGIS MI function supported 8000 Reserved
10 VGIS tax function supported 10000 Reserved
20 Refunds must go online 20000 Mastercard LID/VAT Summary
40 Reserved 40000 Amex LID
80 MOTO supported 80000 Online Reversal
100 ECOM supported 100000 3DS-MasterCard SecureCode
200 ICC Card has chip 200000 3DS-Verified by Visa
400 Cash Advance supported (ATM) 400000 J Secure
800 Reserved

NOTES

The CardFlags value returned is a 32 bit integer bitmask and this is ANDed using a bitmask value from the above list, where each flag value corresponds to a bit in the 32 bit number

For help on bitmasks refer to
https://www.safaribooksonline.com/library/view/c-cookbook/0596003390/ch04s05.html

Card Scheme Codes

CardSchemeCode Card Scheme Description CardSchemeCode Card Scheme Description
52000Unknown52012GE Capital
52001AirPlus52013JCB
52002AMEX52014LASER
52003ATM52015International Maestro
52004CREATE52016MasterCard
52005Visa Debit or Visa Delta52017Platima
52006Diners Club52018SOLO
52007DISCOVER52019STYLE
52008Debit MasterCard52020Domestic Maestro
52009EDGE52021Visa
52010Visa Electron52022Visa Purchase
52011IKANO

IMPORTANT NOTES

1. This list will grow as and when new card schemes are added or discontinued and your host system business logic needs to take this into account.

AuthenticationToken

An AuthenticationToken is issued to merchants on setup and provides secure authentication access to Adflex payment Gateway API services.

Off-line Authorisation

Applicable to Web Services only. Off-line authorisations (where the auth code is provided by the merchant and not the issuer) are supported by Adflex, provided that you have agreement with your acquiring bank and Adflex.

To create an off-line authorisation:

  1. Call Authorise() using parameter values
  2. ProcessMode = 1
  3. TID=pipe delimited parameter string of the following parameters:
Field Name Type Size Option Example Comments
Ident A 8 M TERMINFO Set to: TERMINFO
Version N 1 M 1 Set to: 1
TID N 8 O 22620015 Your Terminal ID
MSG N 4 O 1452 Msg Number from other system
AuthStatus N 1 M 8 8=Authorised, 9=Declined
AuthCode AN 8 O 1234 Your auth code
AuthMessage AN 20 O AUTH CODE:1234 Your auth message
AuthDateTime AN 20 M 2009-02-28 11:55:39 Format yyyy-mm-dd, hh:mm:ss
Online N 1 M 1 0=Offline Auth, 1=Online Auth gained from other system
Capture Environment A 1 M 1 1=Mail order, 13=Ecomm
HoldStatus N 1 M 0 0=Settle now, 2=Settle Later (using Settle/SettleEx)

Example:

TERMINFO|1|22620015||8|1234|AUTH CODE:1234|2009-02-28 11:55:39|1|1|0