Advanced Data

Quick Find

Go straight to the section you need.

1.0 Gateway Integration →

1.1 Introduction

1.2 Terminology

1.3 Integration Methods

1.4 Integration Libraries

1.5 Security and Compliance

1.6 Prerequisites

1.7 Integration Details

1.8 Authentication

1.9 Supported Actions

2.0 New Transactions →

2.1 Request Fields

2.2 Response Fields

3.0 Management Requests →

3.1 Request Fields

3.2 Response Fields

4.0 AVS/CV2 Checking →

4.1 Background

4.2 Benefits and Limitations

4.3 Request Fields

4.4 Response Fields

5.0 3-D Secure Authentication →

5.1 Background

5.2 Benefits and Limitations

5.3 Hosted Implementation

5.4 Direct Implementation

5.5 Request Fields

5.6 Response Fields

5.7 Advanced Features

11 Receipts and Notifications →

11.1 Background

11.2 Customer Email Receipts

11.3 Request Fields

11.4 Response Fields

17 Advanced Data →

17.1 Customer Request Fields

17.2 Merchant Request Fields

17.3 Supplier Request Fields

17.4 Delivery Request Fields

17.5 Receiver Request Fields

17.6 Shipping Request Fields

17.7 Device Information Fields

 

19 Gateway Wallet → 

19.1 Background

19.2 Benefits and Limitation

19.3 Hosted

19.4 Direct Implentation

19.5 Request Fields

19.6 Response Fields

 

26 Digital Wallet Transactions →

26.1 Background

26.2 Benefits and Limitations

26.3 Configuration

26.4 Hosted Implementation

26.5 Direct Implementation

26.6 Request Fields

26.7 Response Fields

26.8 Digital Wallet Tokens

Appendix

A-1 Response Codes

A-1.1 Authorisation Response Codes

A-1.2 Gateway Response Codes

A-2 AVS / CV2 Check Response Codes

A-3 Secure Authentication Data

A-4 3-D Secure Enrolment/Authentication Only

A-9 Duplicate Transaction Checking

A-10 Capture Delay

A-11 Card Identification

A-12 Integration Testing

12.1 Test Amounts

12.2 Test Cards

12.3 3-D Secure Testing

 

A-13 Sample Signature Calculation

A-14 Transaction Life cycle

A-14.1 Authorise, Capture and Settlement

A-14.2 Transaction States

A-15 Transaction types

A-15.1 E-commerce (ECOM)

A-15.2 Mail Order/Telephone Order (MOTO)

A-15.3 Continuous Authority (CA)

 

A-16 Payment Tokenisation

A-16.1 PREAUTH, SALE, REFUND, VERIFY requests

A-16.2 REFUND_SALE requests

A-16.3 CANCEL or CAPTURE requests

A-16.4 QUERY requests

A-16.5 SALE or REFUND Referred Authorisation requests

 

A-18 PSD2 SCA Compliance

A-18.1 Obtaining Strong Customer Authentication

A-18.2 SCA Soft-Declines

A-18.3 Exemptions to Strong Customer Authentication

A-18.4 SCA Using 3-D Secure

 

A-19 Hosted Payment Page Options

A-20 Integration Libraries

A-20.1 Gateway Integration Library

A-20.2 Hosted Payment Page Library

A-20.3 Hosted Payment Fields Library

 

A-21 Example HTTP Requests

A-21.1 Hosted Integration

A-21.2 Direct Integration

A-21.3 Batch Integration

 

A-22 Example Integration Code

A-22.1 Hosted Integration

A-22.2 Direct Integration

A-22.3 Batch Integration

 

A-23 Example Library Code

A-23.1 Gateway Integration Library

A-23.2 Hosted Payment Page Library

A-23.3 Hosted Payment Fields Library

17.0 Advanced Data

The Gateway provides a number of fields that you can use to store information about the transaction. These fields are only sent to the Acquirer if needed. The stored data can be obtained by sending a QUERY request.

17.1 Customer Request Fields

These fields can be used to store details about the Customer and any relationship between the Customer and Merchant such as any purchase order raised. 

If AVS checks are in use, then the Customer and Cardholder are assumed to be the same person and the address and postcode fields are taken as being the registered billing address of the card.

Field Name
customerName
Mandatory?
No
Description
Customer’s name.
Field Name
customerCompany
Mandatory?
No
Description
Customer’s company (if applicable).
Field Name
customerAddress
Mandatory?
No 1
Description
Customer’s address.
Field Name
customerPostcode
Mandatory?
No 1
Description
Customer’s postcode.
Field Name
customerTown
Mandatory?
No
Description
Customer’s town/city.
Field Name
customerCounty
Mandatory?
No
Description
Customer’s county/province.
Field Name
customerCountryCode
Mandatory?
No
Description
Customer’s country.
Field Name
customerPhone
Mandatory?
No
Description
Customer’s phone number.
Field Name
customerMobile
Mandatory?
No
Description
Customer’s mobile phone number.
Field Name
customerFax
Mandatory?
No
Description
Customer’s fax number.
Field Name
customerEmail
Mandatory?
No
Description
Customer’s email address.
Field Name
customerDateOfBirth
Mandatory?
No
Description
Customer’s date of birth.
Field Name
customerOrderRef
Mandatory?
No
Description
Customer’s reference for this order (Purchase Order Reference).
Field Name
customerMerchantRef
Mandatory?
No
Description
Customer’s reference for the Merchant.
Field Name
customerTaxRef
Mandatory?
No
Description
Customer’s tax reference number.

1 Mandatory if AVS checking required.

17.2 Merchant Request Fields

These fields can be used to store details about the Merchant and any relationship between the Merchant and Customer such as any invoice reference. 

Field Name
merchantName
Mandatory?
No
Description
Merchant’s contact name.
Field Name
merchantCompany
Mandatory?
No
Description
Merchant’s company name.
Field Name
merchantAddress
Mandatory?
No
Description
Merchant’s contact address.
Field Name
merchantTown
Mandatory?
No
Description
Merchant’s contact town/city.
Field Name
merchantCounty
Mandatory?
No
Description
Merchant’s contact county.
Field Name
merchantPostcode
Mandatory?
No
Description
Merchant’s contact postcode.
Field Name
merchantCountryCode
Mandatory?
No
Description
Merchant’s contact country.
Field Name
merchantPhone
Mandatory?
No
Description
Merchant’s phone number.
Field Name
merchantMobile
Mandatory?
No
Description
Merchant’s mobile phone number.
Field Name
merchantFax
Mandatory?
No
Description
Merchant’s fax number.
Field Name
merchantEmail
Mandatory?
No
Description
Merchant’s email address.
Field Name
merchantWebsite
Mandatory?
No
Description
Merchant’s website. The website must be a fully qualified URL and include at least the scheme and host components.
Field Name
merchantOrderRef
Mandatory?
No
Description
Merchant’s reference for this order (Invoice/Sales Reference).
Field Name
merchantCustomerRef
Mandatory?
No
Description
Merchant’s reference for the Customer.
Field Name
merchantTaxRef
Mandatory?
No
Description
Merchant’s tax reference number.
Field Name
merchantOriginalOrderRef
Mandatory?
No
Description
Reference to a back order.
Field Name
merchantCategoryCode
Mandatory?
No
Description
Scheme assigned Merchant Category Code (MCC).
Field Name
merchantType
Mandatory?
No
Description
Acquirer assigned Merchant type code.
Field Name
merchantAccountNo
Mandatory?
No
Description
Merchant’s bank account number

1 Mandatory if AVS checking required.

17.3 Supplier Request Fields

These fields can be used to store details about the Supplier. This is where any purchased goods are being supplied by a third-party and not directly from the Merchant.

Field Name
supplierName
Mandatory?
No
Description
Supplier’s contact name.
Field Name
supplierCompany
Mandatory?
No
Description
Supplier’s company name.
Field Name
supplierAddress
Mandatory?
No
Description
Supplier’s contact address.
Field Name
supplierTown
Mandatory?
No
Description
Supplier’s contact town/city.
Field Name
supplierCounty
Mandatory?
No
Description
Supplier’s contact county.
Field Name
supplierPostcode
Mandatory?
No
Description
Supplier’s contact postcode.
Field Name
supplierCountryCode
Mandatory?
No
Description
Supplier’s contact country.
Field Name
supplierPhone
Mandatory?
No
Description
Supplier’s phone number.
Field Name
supplierMobile
Mandatory?
No
Description
Supplier’s mobile phone number.
Field Name
supplierFax
Mandatory?
No
Description
Supplier’s fax number.
Field Name
supplierEmail
Mandatory?
No
Description
Supplier’s email address.
Field Name
supplierOrderRef
Mandatory?
No
Description
Supplier’s reference for this order (Invoice/Sales Reference).
Field Name
supplierAccountNo
Mandatory?
No
Description
Supplier’s bank account number

17.4 Delivery Request Fields

These fields can be used to store details about the delivery address. This is where any purchased goods are being delivered to if different from the Customer’s address.

Field Name
deliveryName
Mandatory?
No
Description
Name of person receiving the delivery.
Field Name
deliveryCompany
Mandatory?
No
Description
Name of company receiving the delivery.
Field Name
deliveryAddress
Mandatory?
No
Description
Delivery address.
Field Name
deliveryTown
Mandatory?
No
Description
Delivery town/city.
Field Name
deliveryCounty
Mandatory?
No
Description
Delivery county.
Field Name
deliveryPostcode
Mandatory?
No
Description
Delivery postcode.
Field Name
deliveryCountryCode
Mandatory?
No
Description
Delivery country.
Field Name
deliveryPhone
Mandatory?
No
Description
Phone number of delivery location.
Field Name
deliveryMobile
Mandatory?
No
Description
Mobile phone number of delivery location.
Field Name
deliveryFax
Mandatory?
No
Description
Fax number of delivery location.
Field Name
deliveryEmail
Mandatory?
No
Description
Delivery email address.

17.5 Receiver Request Fields

These fields can be used to store details about the recipient of the purchased goods where different from the Customer’s and Delivery details. It is most commonly used by Financial Institutions (MCC 6012 Merchants) who need to record the primary recipient of a loan.

Field Name
receiverName
Mandatory?
No
Description
Receiver’s contact name.
Field Name
receiverCompany
Mandatory?
No
Description
Receiver’s company name.
Field Name
receiverAddress
Mandatory?
No
Description
Receiver’s contact address.
Field Name
receiverTown
Mandatory?
No
Description
Receiver’s contact town/city.
Field Name
receiverCounty
Mandatory?
No
Description
Receiver’s contact county.
Field Name
receiverPostcode
Mandatory?
No
Description
Receiver’s contact postcode.
Field Name
receiverCountryCode
Mandatory?
No
Description
Receiver’s contact country.
Field Name
receiverPhone
Mandatory?
No
Description
Receiver’s phone.
Field Name
receiverMobile
Mandatory?
No
Description
Receiver’s mobile phone number.
Field Name
receiverFax
Mandatory?
No
Description
Receiver’s fax number.
Field Name
receiverEmail
Mandatory?
No
Description
Receiver’s email address.
Field Name
receiverAccountNo
Mandatory?
No
Description
Receiver’s account number.
Field Name
receiverDateOfBirth
Mandatory?
No
Description
Receiver’s date of birth.

17.6 Shipping Request Fields

These fields can be used to store details about the shipping method and costs.

Field Name
shippingTrackingRef
Mandatory?
No
Description
Shipping tracking reference.
Field Name
shippingMethod
Mandatory?
No
Description
Shipping method (eg Courier, Post, etc.).
Field Name
shippingAmount
Mandatory?
No
Description
Cost of shipping.
Field Name
shippingGrossAmount
Mandatory?
No
Description
Gross cost of shipping.
Field Name
shippingNetAmount
Mandatory?
No
Description
Net cost of shipping.
Field Name
shippingTaxRate
Mandatory?
No
Description
Tax rate as percentage to 2 decimal places.
Field Name
shippingTaxAmount
Mandatory?
No
Description
Tax cost of shipping.
Field Name
shippingTaxReason
Mandatory?
No
Description
Tax reason (eg VAT).
Field Name
shippingDiscountAmount
Mandatory?
No
Description
Discount on shipping.
Field Name
shippingDiscountReason
Mandatory?
No
Description
Reason for discount.

Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct.

17.7 Device Information Fields

These fields can be used to provide details of the device from which the transaction is being made. Although not strictly mandatory, they may be required for fraud checking or 3-D Secure authentication, in which case it is highly recommended that they be provided.

Field Name
deviceType
Mandatory?
No
Description
Type of Consumer’s device. One of the following values: desktop, laptop, tablet, phone, other.
Field Name
deviceChannel
Mandatory?
No
Description
Communications channel used by the Consumer’s device. One of the following values: browser, app, other.
Field Name
deviceIdentity
Mandatory?
No 1
Description
Content of the HTTP User-Agent header received from the Consumer’s device. Truncated to 2048 characters maximum.
Field Name
deviceTimeZone
Mandatory?
No 1
Description
Time zone offset in minutes between UTC and the Consumer’s device. The offset is positive if the local time zone is behind UTC and negative if it is ahead.
Field Name
deviceCapabilities
Mandatory?
No 1
Description
Comma separated list of capabilities supported by the Consumer’s device. One or more of the following values: java, javascript.
Field Name
deviceAcceptContent
Mandatory?
No 1
Description
Content of HTTP Accept header received from the Consumer’s device. Truncated to 2048 characters maximum.
Field Name
deviceAcceptCharset
Mandatory?
No 1
Description
Content of HTTP Accept-Charset header received from the Consumer’s device. Truncated to 2048 characters maximum.
Field Name
deviceAcceptEncoding
Mandatory?
No 1
Description
Content of HTTP Accept-Encoding header received from the Consumer’s device. Truncated to 2048 characters maximum.
Field Name
deviceAcceptLanguage
Mandatory?
No 1
Description
Content of HTTP Accept-Language header received from the Consumer’s device. Truncated to 2048 characters maximum.
Field Name
deviceScreenResolution
Mandatory?
No 1
Description
Screen resolution of the Consumer’s device. Formatted as [HxWxD] where:

H – screen height in pixels
W – screen width in pixels
D – colour depth in bits

Screen height and width must be between 1 and 999999 pixels.

Colour depth must be one of the following values: 1, 4, 8, 15, 16, 24, 32, 48.

Field Name
deviceOperatingSystem
Mandatory?
No
Description
Operating system used by the Consumer’s device. One of the following values: win, unix, linux, macos, ios, android, other.

1 This field is mandatory for 3-D Secure v2 unless an alternative is provided via the threeDSOptions field.

 

Integrated Payments - connecting your till to your terminal

Integrated payments - connecting your EPOS till to your card terminal - enables your business to process payments faster and increase your profits.

There are many benefits to an integrated solution for almost all business types, most importantly, the removal of human error, giving you accurate reporting from all tills and terminals.

At Swipen, we offer Integrated Payments free of charge and you can use our Pay at Table or Pay at Counter software, or both if it suits your business:

Pay at Table

A software design with restaurants in mind:

Split the bill at the table

Automatic table closing

Integrated gratuity & reporting

Turn tables faster

More efficient payment

Pay at Counter

Suitable for most businesses, offering:

Faster payments

Shorter queues

Better conversion

Greater profits

COVID secure

Discover which terminal type is best for your business

Portable

Restaurants

Pubs

Cafes

Countertop

Bars

Clubs

Takeaways

Retail & Shops

Take your payments to the next level

get in touch today

E-Commerce Payment Solutions

With the arrival of Covid-19 into all our lives, online only payments are looking to have a bright future that’s here to stay.

At Swipen, we want to bust the myth that taking payments online is complicated, and help you
adapt to this changing world.

We offer two types of E-Commerce payment solution either directly integrated with your website or a hosted payment page.

Directly Integrated

Integrated into your own website

Completely customisable

Branded to your business

Customers stay on your website

150 currencies supported

Shopping carts

No long-term contract

Alternative payment methods, including: Alipay, Apple Pay, Google Pay, WeChatPay

Hosted Payment Page

Easy to set up

Take payments in minutes

Swipen branded

Data processed by Swipen

150 currencies supported

Shopping carts

No long-term contract

Alternative payment methods, including: Alipay, Apple Pay, Google Pay, WeChatPay

Take your payments to the next level

get in touch today

Virtual Terminal - Taking Payments over the Phone

Many businesses find it useful to take payments over the phone, whether you’re a travel agent
needing to take deposits, a mobile tradesperson, travelling salesperson, you have a call centre, or you don’t have a website to take payments online.

Swipen’s Virtual Terminal allows you to take card payments over the phone quickly and securely.

Our solution is a web portal that can be used on a desktop, tablet or mobile device.

Virtual Terminal Key Features

More secure than a card terminal - Completing the payment over the phone with full customer details reduces the risk of chargebacks or fraud.

Pay By Link - Send a payment link to complete the purchase or pay a balance. This is also a useful feature for customers who prefer to not give their details over the phone.

Capture Customer Details - The Virtual Terminal allows you to capture all the customer details you will need for your CRM or Booking Systems reducing the need for double inputting.

Control Permissions - Restrict user access to only certain functionality so you can control what your staff can process and see.

Take Payments anywhere - The Virtual Terminal is compatible to all devices and allows you to take payments from anywhere - office, home or on the move in a safe and secure way.

Ideal for call centres, travel agents, travelling salespeople, mobile tradespeople, restaurants for pre-bookings and parties, hotels for rooms and events, or any business that doesn’t have a website that customers can pay through.

Take your payments to the next level

get in touch today

Web & App Solutions - Order and Pay-at-Table Platform

With COVID regulations in force across the country, restaurants and pubs are adjusting the way they work to reduce the spread of this virus.

Swipen are also adapting to these changing times, and working with our expert partners, we can now offer order and pay-at-table platforms, allowing you to benefit from cashless and cardless payment options.

Our solutions can be either Web or App based and we provide the choice between
a ‘Simple Solution’ and a ‘Bespoke Solution’, depending on the size of your business

Bespoke Solution

The best option for individual pubs and restaurants, small chains, or if location offers a different menu:

Use your own branding

At table QR code or WiFi login

Bespoke rates and fees

Links to your EPOS till *

*Depending on the EPOS company

Simple Solution

Ideal for larger chains where every location requires exactly the same functionality and offers the same menu:

Custom built to fit your business

Customers can access the way you want

Links to both your till and kitchen

No training required

Working with Pizza Hut

Swipen have helped create a bespoke value-for money solution for Pizza Hut, and we could do the same for you.

Get in contact to find out more.

Take your payments to the next level

get in touch today

Tip Per Tap -Contactless Tipping System

With the dawn of cashless and touchless checkouts along with app ordering systems and pay online methods, many restaurants, bars, cafés and hotels are finding that their waiting staff are no longer able to receive cash or card tips.

Swipen has the perfect solution: the new ‘Tip Per Tap’ Contactless Tipping System

Directly Integrated

A dedicated terminal is placed in a prominent location in your restaurant.

The terminal is set to ‘donation’ and the debit amount is set at a specific figure. e.g. £2

Your happy customers simply tap their card, phone or watch against the terminal to leave a £2 tip.

They can tap multiple times to leave a larger amount

Works automatically without the need for a member of staff to supervise.

End-of-day report is separate, making it quicker and easier to share the total tips received between staff members.

How about a little Tip Per Tap

Read our blog all about our new Tip Per Tap Contactless Tipping System.

Get in contact to find out more.

Take your payments to the next level

get in touch today