New Transactions

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 3-D Secure Enrolment/Authentication Codes

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 Exemptions to Strong Customer Authentication

A-18.3 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

2.o New Transactions

You can perform a new transaction, such as a sale, by sending a request with the required action and transaction type together with details about the order and payment method.

2.1 Request Fields

Field Name
merchantID
Mandatory?
Yes
Description
Your Gateway Merchant Account ID
Field Name
merchantPwd
Mandatory?
No 1
Description
Any password used to secure this account. Refer to section 1.8.1 for details.
Field Name
signature
Mandatory?
Yes 2
Description
Any hash used to sign this request. Refer to section 1.8.2 for details.
Field Name
action
Mandatory?
Yes
Description
The action requested. Refer to section 1.9 for supported actions. Possible values are: PREAUTH, VERIFY, SALE, REFUND, REFUND_SALE. If a REFUND_SALE action is used, then the request must not attempt to change the payment details, or it will fail with a responseCode of 65542 (REQUEST MISMATCH) because the refund must be made to the original card.
Field Name
amount
Mandatory?
Yes 3
Description
The amount of the transaction.
Field Name
type
Mandatory?
Yes 3
Description
The type of transaction. Refer to appendix A-15 for details. Possible values are:
1 – E-commerce (ECOM)
2 – Mail Order/Telephone Order (MOTO).
9 – Continuous Authority (CA).
Field Name
countryCode
Mandatory?
Yes 3
Description
Merchant’s location.
Field Name
currencyCode
Mandatory?
Yes 3
Description
Transaction currency.
Field Name
paymentMethod
Mandatory?
No
Description
The payment method required. For card payments either omit this field or use the value card.
Field Name
cardNumber
Mandatory?
Yes 3,4
Description
The primary account number (PAN) as printed on the front of the payment card. Digits and spaces only.
Field Name
cardExpiryMonth
Mandatory?
Yes 3,4
Description
Payment card’s expiry month from 1 to 12.
Field Name
cardExpiryYear
Mandatory?
Yes 3,4
Description
Payment card’s expiry year from 00 to 99
Field Name
cardExpiryDate
Mandatory?
No 3,4
Description
Payment card’s expiry date in MMYY format as an alternative to sending a separate cardExpiryMonth and cardExpiryYear.
Field Name
cardCVV
Mandatory?
Yes 3,4
Description
Payment card’s security number. The 3-digit number printed on the signature strip.
Field Name
transactionUnique
Mandatory?
No 3
Description
You can supply a unique identifier for this transaction. This is an added security feature to combat transaction spoofing.
Field Name
orderRef
Mandatory?
No 3
Description
Free format text field to store order details, reference numbers, etc. for the Merchant’s record.
Field Name
orderDate
Mandatory?
No
Description
Optional date to record with the transaction.
Field Name
captureDelay
Mandatory?
No
Description
Number of days to wait between authorisation of a payment and subsequent settlement. Refer to appendix A-9 for details.
Field Name
xref
Mandatory?
No 5
Description
Reference to a previous transaction. Refer to appendix A-16 for details.
Field Name
redirectURL
Mandatory?
No 6
Description
URL to which the hosted form will redirect the Customer’s browser after the transaction has been completed. The URL must be fully qualified and include at least the scheme and host components. Refer to section 1.7.6 for details.
Field Name
callbackURL
Mandatory?
No 6
Description
URL which will receive a copy of the transaction result by POST. The URL must be fully qualified and include at least the scheme and host components. Refer to section 1.7.7 for details
Field Name
remoteAddress
Mandatory?
No 7
Description
IP address of client making the transaction. This should be provided where possible to aid fraud prevention.
Field Name
rtAgreementType
Mandatory?
No 8
Description
Agreement between Merchant and Cardholder for the storage of, or subsequent use of, payment details. Refer to section 12 for further details.

1 A password is not recommended if using the Hosted Integration, use a signature instead. 

2 A signature may be mandatory on some Merchant Accounts and requests. 

3 Optional if an xref is provided as the value will be taken from the cross-referenced transaction. 

4 Optional if using the Hosted Integration, any value provided will be used to initialise any HPP input field. 

5 Mandatory for a REFUND_SALE request to specify the original SALE transaction. 

6 Not supported by the Batch Integration. 

7 Not supported by the Hosted Integration, which will automatically use the Customer’s IP address. 

8 Mandatory for recurring transactions or other transactions using stored credentials.

2.2 Response Fields

The response will contain all the fields sent in the request (minus any cardNumber and cardCVV) plus the following:

Field Name
responseCode
Returned?
Always
Description
A numeric code providing the specific outcome. Common values are:

0 - Successful / authorised transaction.
1 - Card referred – Refer to card issuer.
2 - Card referred – Special condition.
4 - Card declined – Keep card.
5 - Card declined.

Check responseMessage for more details of any error that occurred.

Refer to appendix A-1 for details.

Field Name
responseStatus
Returned?
Always
Description
A numeric code providing the outcome category. Possible values are:

0 – Authorisation Approved / No reason to decline
1 – Authorisation Declined.
2 – Authorisation Error / Transaction malformed.

Field Name
responseMessage
Returned?
Always
Description
Message received from the Acquiring bank, or any error message.
Field Name
transactionID
Returned?
Always
Description
A unique ID assigned by the Gateway.
Field Name
xref
Returned?
Always
Description
You may store the cross reference for repeat transactions. Refer to appendix A-16 for details.
Field Name
state
Returned?
Always
Description
Transaction state. Refer to appendix A-14.2 for details.
Field Name
timestamp
Returned?
Always
Description
Time the transaction was created or last modified.
Field Name
transactionUnique
Returned?
If supplied
Description
Any value supplied in the initial request.
Field Name
authorisationCode
Returned?
On success
Description
Authorisation code received from Acquirer.
Field Name
referralPhone
Returned?
If provided
Description
Telephone number supplied by Acquirer to phone for voice authorisation when provided.
Field Name
amountReceived
Returned?
On success
Description
Amount the Acquirer authorised. This should always be the full amount requested.
Field Name
amountRefunded
Returned?
If refund
Description
Total amount of original SALE that has so far been refunded. Returned when action is REFUND_SALE.
Field Name
orderRef
Returned?
If supplied
Description
Any value supplied in the initial request.
Field Name
cardNumberMask
Returned?
Always
Description
Card number masked for Merchant storage.
Field Name
cardTypeCode
Returned?
Always
Description
Code identifying the type of card used. Refer to appendix A-11 for details.
Field Name
cardType
Returned?
Always
Description
Description of the type of card used. Refer to appendix A-11 for details
Field Name
cardSchemeCode
Returned?
Always
Description
Code identifying the Card Scheme used. Refer to appendix A-11 for details.
Field Name
cardScheme
Returned?
Always
Description
Description of the card scheme used. Refer to appendix A-11 for details.
Field Name
cardIssuer
Returned?
Always
Description
Card Issues name (when known).
Field Name
cardIssuerCountry
Returned?
Always
Description
Card issuing country’s name (when known).
Field Name
cardIssuerCountryCode
Returned?
Always
Description
Card issuing country’s ISO-3166 2-letter code (when known).

Other response fields may be returned as documented elsewhere in this guide. Undocumented fields may be returned at the Gateways discretion but should not be relied upon.

The acquirerResponseXXXX fields are dependent on the Acquirer in use and are supplied for additional information only. 

The response is also POSTed to any URL provided by optional callbackURL.

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

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

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

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

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