1. Home
  2. Developers
  3. Mobile API Integration Guide

Mobile API Integration Guide

Introduction

The mobile API allows transactions to be processed from within a mobile App. With this system, the App collects both order and payment details and then communicates the relevant payment details on a per order basis with payment gateway for processing.

The benefits of using the mobile API for the merchant include being able to retain full control over the payment process.

However, for this system to work successfully, it is important that the merchant ensures the App uses secure methods for handling of the card details, must destroy any card data as soon as the authorisation process has completed, must not store or log that information anywhere, and must not transmit the information to any other system.

As part of the setup process you will be supplied with an authentication key.

If your App will be collecting the card details (rather than using the hosted payment pages) then it will be required to be certified though PA DSS. This includes, but is not limited to, the following:

  • Card details MUST be destroyed as soon as the authorisation process has completed.
  • Card details MUST NOT be stored or logged in any way.
  • Card details MUST NOT be transmitted to any other system.

Security

To protect the authentication key that you must use as part of each transaction request, you should not store this key within the actual App code. Other details, such as your Store ID, can be held within the App code.

We would advise that your App obtains the authentication key by downloading it from your servers as part of either an installation or registration phase. This process must be over a secure encrypted link (for example, HTTPS). Once the App has the authentication key, it should store it in the device in a secure method, such as using the iOS Keychain.

This method also allows you to update the authentication key should this be needed.

Request methods

All payment requests must be sent as an XML request using the HTTP POST method to the following URL:

https://secure.innovatepayments.com/gateway/mobile.xml

All data must be sent in UTF-8 encoding. In order to allow processing via the global card network, only certain characters can be used. These are:

Unicode set nameCharacters allowed (hex code)
Basic Latin0009, 000A, 000D, 0020-007E
Latin-1 Supplement00A0-00FF
Latin Extended-A0100-017F
Latin Extended-BLatin Extended-B

XML Request layout

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <store>Store ID</store>
  <key>Authentication Key (Note 1)</key> 
  <device>
    <type>Mobile device type (Note 2)</type>
    <id>Mobile device ID (Note 3)</id>
    <agent>WebView user agent header (Note 4)</agent>
    <accept>WebView accept header (Note 4)</accept>
  </device>
  <app>
    <name>Application name</name>
    <version>Application version</version>
    <user>Application user ID (Note 5)</user>
    <id>Application installation ID</id>
  </app>
  <tran>
    <test>Test mode (Note 6)</test>
    <type>Transaction type</type>
    <class>Transaction class</class>
    <cartid>Transaction cart ID  (Note 7)</cartid>
    <description>Transaction description</description>
    <currency>Transaction currency (Note 8)</currency>
    <amount>Transaction amount (Note 9)</amount>
    <ref>Previous transaction reference (Note 10)</ref>
  </tran>
  <card>
    <number>Card number</number>
    <expiry>
      <month>Expiry date - month (Note 11)</month>
      <year>Expiry date - year</year>
    </expiry>
    <cvv>CVV (Note 12)</cvv>
  </card>
  <billing>
    <name>
      <title>Title</title>
      <first>Forenames (Note 13)</first>
      <last>Surname (Note 13)</last>
    </name>
    <address>
      <line1>Street address – line 1 (Note 13)</line1>
      <line2>Street address – line 2</line2>
      <line3>Street address – line 3</line3>
      <city>City</city>
      <region>Region</region>
      <country>Country (Note 14)</country>
      <zip>Zip/Area/Postcode</zip>
    </address>
    <phone>Mobile number</phone>
    <email>Email address</email>
  </billing>
</mobile>

Notes:

  1. The Authentication Key will be supplied by Innovate Payments as part of the Mobile API setup process after you request that this integration type is enabled for your account. This should not be stored permanently within the App.
  2. Description of the device the App is running on.
  3. Unique ID for the mobile device (such as identifierForVendor in iOS)
  4. The User-Agent and Accept headers that will be used in any webview based requests. These are required as part of E-Commerce class transactions. If no value is sent for these fields, then the gateway will use the headers that are sent as part of the mobile API request. See the section on 3-D Secure for more details.
  5. Your reference for the customer/user that is running the App. This should relate to their account within your systems.
  6. Test mode of zero indicates a live transaction. If this is set to any other value the transaction will be treated as a test.
  7. An example use of the cart ID field would be your own transaction or order reference.
  8. Currency must be sent as a 3 character ISO code. A list of currency codes can be found at the end of this document. For voids or refunds, this must match the currency of the original transaction.
  9. The transaction amount must be sent in major units, for example 9 dollars 50 cents must be sent as 9.50 not 950. There must be no currency symbol, and no thousands separators. The
    decimal part must be separated using a dot.
  10. The previous transaction reference is required for any continuous authority transaction. It must contain the reference that was supplied in the response for the original transaction.
  11. Card dates must be sent as a numeric values with a two digit month (01-12) and a 4 digit year (e.g. 2010)
  12. The requirement for the CVV (card security code) depends on the transaction class:
    Continuous Authority – Not Used
    Mo/To – Optional (* – see below)
    E-Commerce – Required
  13. Customer Forename, Surname, Address Line 1, City, Country and Email Address are the minimum required details for a transaction to be processed.
  14. Country must be sent as a 2 character ISO code. A list of country codes can be found at the end of this document.

* Although the CVV is optional within the Innovate Payments gateway for Mo/To class transactions, some acquiring banks may mandate this. Please check with Innovate Payments support to confirm if this is required for your account.

Transaction types

The transaction type and class parameters set how the transaction that will be processed. These set both the processing action and the processing category. Some transaction types (such as void and refund) are not applicable for use via the Mobile API, you should use either the Merchant Administration System or the Remote API for these. The options are:

Type
authSeek authorisation from the card issuer for the amount specified. If authorised, the
funds will be reserved but will not be debited until such time as a corresponding capture
command is made. This is sometimes known as pre-authorisation.
captureNot available within the Mobile API
releaseNot available within the Mobile API
saleImmediate purchase request. This has the same effect as would be had by performing
an auth transaction followed by a capture transaction for the full amount. No additional
capture stage is required.
refundNot available within the Mobile API
voidNot available within the Mobile API
verifyConfirm that the card details given are valid. No funds are reserved or taken from the
card.
paypageUse the hosted payment page to capture and process the card details. See the Payment
Page section in this guide for more details.
Class
motoProcess as Mail Order / Telephone Order.
ecomProcess as an Internet based E-Commerce transaction. The use of 3-D Secure is
mandatory for this class of transaction.
contProcess as a continuous authority transaction, for example a recurring subscription.

For E-Commerce transactions you may be required to perform 3D Secure authentication for the card holder. If this is required, then you will have to direct the customer to a website operated by their card issuer. Until this process is completed, the transaction cannot be authorised.

For items or services that have an immediate delivery, the sale transaction method is often the simplest one to use. If there can be a delay between the transaction and eventual shipping of the goods, then separate auth and capture transactions should be used. You must ensure that you perform the capture stage of the transaction otherwise the funds will not be taken from the card and you will not receive payment. You should process the capture request before actually shipping the goods to ensure that the card used is still valid.

Authorisation response

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <auth>
    <status>Authorisation status</status>
    <code>Authorisation code</code>
    <message>Authorisation message</message>
    <tranref>Transaction reference</tranref>
    <cvv>Result of the CVV check</cvv>
    <avs>Result of the AVS check</avs>
    <cardcode>Card type code</cardcode>
    <cardlast4>Last 4 digits of the card used</cardlast4>
  </auth>
</mobile>
FieldDescription
statusAuthorisation status. A indicates an authorised transaction. H also indicates an
authorised transaction, but where the transaction has been placed on hold.
Any other value indicates that the request could not be processed.
codeIf the transaction was authorised, this contains the authorisation code from
the card issuer. Otherwise it contains a code indicating why the transaction
could not be processed.
messageThe authorisation or processing error message.
tranrefThe payment gateway transaction reference allocated to this request.
cvvResult of the CVV check:
Y = CVV matched OK
N = CVV not matched
X = CVV not checked
E = Error, unable to check CVV
avsResult of the AVS check:
Y = AVS matched OK
P = Partial match (for example, post-code only)
N = AVS not matched
X = AVS not checked
E = Error, unable to check AVS
cardcodeCode to indicate the card type used in the transaction. See the code list at the
end of the document for a list of card codes.
cardlast4The last 4 digits of the card number used in the transaction. This is supplied for
all payment types (including the Hosted Payment Page method) except for
PayPal.

The AVS check is currently only available for cards issued in the United Kingdom, United States of America or Canada, and only if your acquirer supports this service.

For transactions which are not authorised, it is recommended to display a generic message explaining that the transaction could not be processed rather than any specific error text.

Request verification

A request verification URL can be configured as part of this API. If this is set, then when the API receives a transaction request, the details (not including the card information) will be set to the verification URL in order to confirm that the request is valid.

The transaction details will be sent as an XML request, directly from the payment gateway to the merchants systems. The verification request will not be sent via the mobile device.

The verification request will contain the transaction details received by the mobile API.

Verification message from gateway to merchant systems:

<?xml version="1.0" encoding="UTF-8"?>
<verify>
  <store>Store ID</store>
  <key>Verification Key</key>
  <device>
    <type>Mobile device type</type>
    <id>Mobile device ID</id>
  </device>
  <app>
    <name>Application name</name>
    <version>Application version</version>
    <user>Application user ID</user>
    <id>Application installation ID</id>
  </app>
  <tran>
    <test>Test mode</test>
    <type>Transaction type</type>
    <class>Transaction class</class>
    <cartid>Transaction cart ID</cartid>
    <description>Transaction description</description>
    <currency>Transaction currency</currency>
    <amount>Transaction amount</amount>
    <ref>Previous transaction reference</ref>
  </tran>
</verify>

This provides the opportunity to either block the request, or allow it to continue for authorisation.

The verification response should consist simply of a Yes or No status

<?xml version="1.0" encoding="UTF-8"?>
<verify>
    <allow>Yes or No</allow>
</verify>

You should ensure that the verify process completes as quickly as possible. The transaction cannot be processed until this has been done. If the request to the verification URL cannot be completed (such as an error occurring whilst processing the request), the gateway will assume that verification has failed and will block the transaction request.

Update billing details

The verification response can also contain the billing details for the customer. This allows the initial mobile API request to omit the billing section. In this case, the verification response should be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<verify>
  <allow>Yes or No</allow>
  <billing>
  <name>
    <title>Title</title>
    <first>Forenames</first>
    <last>Surname</last>
  </name>
  <address>
    <line1>Street address – line 1</line1>
    <line2>Street address – line 2</line2>
    <line3>Street address – line 3</line3>
    <city>City</city>
    <region>Region</region>
    <country>Country</country>
    <zip>Zip/Area/Postcode</zip>
  </address>
  <email>Email address</email>
  </billing>
</verify>

If the <billing> section is provided, then any billing details that were sent as part of the initial request will be replaced with the details here. These details must include all of the required information.

Recurring transactions

Using the Continuous Authority transaction class, you can process additional authorisations against a card. This could be used, for example, in a subscription based system where the customer is required to pay a set amount every month.

The first transaction must be processed as either an E-Commerce transaction or as a MoTo (Mail Order / Telephone Order) transaction. If this transaction is authorised, then additional transactions can be processed as Continuous Authority.

These additional transactions requests are processed by setting a transaction type of ‘sale’, with a transaction class of ‘cont’. Although this is a sale request, the card and billing details must not be sent as part of the request, it must instead use the ‘tran_ref’ field to set the transaction ID of the initial authorisation. The card and billing details will be retrieved from that initial authorisation. Other transaction details, such as cart ID and description, must be sent as per a normal Sale request.

The initial transaction must be an authorised sale, using either the E-Commerce or MoTo transaction class. If the transaction referenced is not a sale, was not authorised, or is not of the required class, then the authorisation request will be rejected.

Should a customer require changing of their card details, maybe through needing to use a different card or simply down to the existing card expiring, then a new E-Commerce or MoTo transaction will be required to make an initial authorisation based on the new card details. All recurring transactions after that point should now refer to this new transaction and not the original transaction.

Tokenization

Tokenization is the process of replacing some piece of sensitive data with a value that is not considered sensitive in the context of the environment that consumes the token and the original sensitive data.

Transaction level

The payments gateway uses transaction level tokenization by default. In this way, only the initial transaction requires the card details. In all other transactions the card details do not form part of the transaction request. Instead, the request must include the payment gateway transaction reference from the initial transaction. All required details, such as card number and expiry date, will be retrieved from the transaction record held by gateway.

 3-D Secure

The 3-D Secure protocol was developed by Visa to improve the security of Internet payments. It is designed to allow authentication of cardholders by their issuers at participating merchants. The
objective is to benefit all participants by providing issuers the ability to fully authenticate cardholders during an online purchase, reducing the likelihood of fraudulent usage of Visa cards. It has since been licensed by other card schemes such as MasterCard, JCB and American Express. Each card scheme has its own brand name for 3-D Secure:

Scheme3-D Secure brand name
VisaVerified by Visa
MasterCardSecureCode
JCBJ/Secure
American ExpressSafeKey

The card holder verification takes place on a server called an Access Control Server (ACS) which is operated by the card issuer. The merchant or payment gateway is not involved in capturing or processing any of the authentication details.

The advantage for merchants is the reduction of “unauthorised transaction” chargebacks. The main advantage for cardholders is that there is a decreased risk of other people being able to use their payment cards fraudulently on the Internet.

In most current implementations of 3-D Secure, the issuing bank prompts the buyer for a password that is known only to the bank and the buyer. Since the merchant does not know this password and is not responsible for capturing it, it can be used by the issuing bank as evidence that the purchaser is indeed their cardholder. This decreases risk in two ways:

  1. Copying card details, either by writing down the numbers on the card itself or by way of
    modified terminals or ATMs, does not result in the ability to purchase over the Internet
    because of the additional password, which is not stored on or written on the card.
  2. Since the merchant does not capture the password, there is a reduced risk from security
    incidents at online merchants – there is no way for anyone to get the associated password.

Using 3-D Secure with the mobile API integration

When processing an e-commerce class transaction, if 3-D Secure authentication is required, then the response to the transaction request will contain details of the URL that the customer must be directed to in order to complete the transaction. This is known as a webview response rather than an authorisation response.

If no 3-D Secure authentication is required, then the response will be a standard authorisation response, and there are no additional steps to be done.

The display of the 3-D Secure page is controlled by the card issuer, the styles or layouts used cannot be changed.

During the initial check to see if any 3-D Secure authentication is needed, details of the browser that will be used must be provided. This can be passed in as part of the transaction request in the <agent> and <accept> parts of the <device> section.

These must represent the User-Agent and Accept headers that would be used by any browser based process (webview) – these are often different to the values that are sent using XML requests.

The header values are passed to the 3-D Secure system at the time then authentication requirements are checked. If authentication is required, then the user must be taken to the web page required by their card issuer. The authentication can be rejected in the browser headers presented at that stage are not the same as the headers used when initially checking for 3-D Secure.

If the headers that will be used by the browser are the same as those that are used when sending the mobile API requests, these fields can be left blank.

WebView response

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <webview>
    <start>URL the customer must be directed to</start>
    <close>URL that marks the end of the process</close>
    <abort>URL that marks an error during the process</abort>
    <code>Transaction code used in completing the request</code>
  </webview>
</mobile>

When a webview response is received, the App will need to direct the customer to the URL given as the start address. The App should monitor the progress of the webview, and once it reaches the URL
provided as the close address, it should close the web display and continue with the transaction process.

To complete the transaction, the App must now make a second request to the gateway. This request includes will trigger the final authorisation stage of the transaction, and return the authorisation response. The request must be sent to:

https://secure.innovatepayments.com/gateway/mobile_complete.xml

XML Request Layout for transaction completion:

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <store>Store ID</store>
  <key>Authentication Key</key>
  <complete>Transaction code obtained in the WebView response</complete>
</mobile>

If the App detects an error during the webview process, or the webview reaches the URL given as the abort address, then it should close the web display and send an abort request to the gateway at the following URL:

XML Request Layout for transaction abort:

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <store>Store ID</store>
  <key>Authentication Key</key>
  <abort>Transaction code obtained in the WebView response</abort>
</mobile>

Using the Hosted Payment Pages

You can generate a transaction request which will use the Hosted Payment Pages to capture the customer’s card details, rather than having them entered directly into your App.

This removes any PA DSS certification requirements for your application, as it is no longer handling any card data. Transactions processed in this way can still be used as the base for any future continuous-authority transactions if required. The Hosted Payment Page method will automatically deal with any 3-D Secure pages without any further action required from the App.

To generate a Hosted Payment Page request, set the transaction type field to ‘PayPage’. You must not include any card details (card number, expiry or cvv). Where possible, you should provide as much information about the customer as you can (name and address) as this will simplify the payment process for the customer. If these details are not supplied, then the Hosted Payment Page will prompt for them. The customers email address must be supplied.

<?xml version="1.0" encoding="UTF-8"?>
<mobile>
  <store>Store ID</store>
  <key>Authentication Key</key>
  <device>
  ... See XML Response Layout for details ...
  </device>
  <app>
  ... See XML Response Layout for details ...
  </app>
  <tran>
  <test>Test mode</test>
  <type>PAYPAGE</type>
  <cartid>Transaction cart ID (Note 1)</cartid>
  <description>Transaction description</description>
  <currency>Transaction currency</currency>
  <amount>Transaction amount</amount>
  </tran>
  <billing>
  ... See XML Response Layout for details ...
  </billing>
</mobile>

If the request can be processed, a webview response will be generated. This will direct the customer to the Hosted Payment Pages. The webview process should be monitored as described in the WebView response section above, including sending the final transaction completion request through the mobile API.

Notes:

  1. The Hosted Payment Pages require a unique identifier for each transaction. You must use a unique value for the cart ID for each transaction request.
  2. The customers email address is a mandatory field as part of the request, but other customer billing fields (name and address) can be left blank if they are not known. However, it is recommended to provide these if possible, as that simplifies the payment process for the customer.
  3. No server-to-server callback is made for transactions processed via the Hosted Payment
    Pages in this way, as the transaction is not server generated

Device Identification

The <device> and <app> parts of the XML request are used to help identify the device, application and user. Other than the Application name and Application Version fields, these must not be hard- coded to pre-set values within the App – they must be determined from the actual device the App is installed on.

For each transaction request a reference is created using these idenfication values. For any Continuous-Authority requests (recurring payments), the reference must match the reference generated for the initial transaction. If it does not match, then the request will be declined.

WebView browser headers

Transaction requests where the App captured the card details and where that request is using the E-Commerce transaction class, must provide the User Agent and Accept headers that will be used within any subsequent WebView request.

These headers are transmitted to the 3-D Secure system as part of the card enrolment check. Should 3-D Secure verification be required, the issuers systems may compare any headers received from within the WebView at that stage with the headers used during the enrolment check. If these do not match, some card issuers may reject the authentication request, which would cause the transaction to decline.

The methods used when sending XML requests to the gateway often use different headers to those within a WebView session, as such you should ensure that you obtain the correct headers before
sending the request. In some systems this may only be possible by creating a WebView element, intercepting the headers from the http request it was going to send out, and closing the WebView before it actually makes any communication. This can be done by attaching event handlers to the appropriate stage of the WebView. This check should be done either at application startup, or just prior to making a transaction request that will require these headers. It should not be done at application installation time, as the browser details used within the WebView may be updated after the application is installed.

Location Information

Where possible, you should also provide the current location of the user as provided by the location services with the device. These can be supplied using the following fields:

<mobile>
    ...
   <location>
        <lat>Current latitude</lat>
        <long>Current longitude</long>
    </location>
     ...
</mobile>

Authorisation response codes

StatusCodeMessage
ASet by issuerAuthorised
HSet by issuerAuthorised, but placed on hold. Manual inspection required
E01Invalid request
E02Transaction cost or currency not supplied
E03Cart ID not set
E04Invalid store ID
E05Transaction cost or currency not valid
E06Invalid transaction mode
E07Card expiry not supplied
E10Card number not supplied
E11Invalid card number
E12Card expired
E14Card type mismatch
E15Invalid card security code (CVV)
E16Card security code (CVV) not supplied
E17Name not valid/not supplied
E18Address not valid/not supplied
E19Country not valid/not supplied
E20IP address not valid/not supplied
E21Card/Currency/Class combination not supported
E22Invalid transaction reference
E23Amount differs from original
E24Currency differs from original
E25Original transaction not authorised
E26Original transaction already voided
E27Original transaction mismatch
E28Invalid start date
E29Amount greater than available balance
E30Card details differ from original
D31Not authorised
D32Original transaction cannot be voided
C33Transaction cancelled
D34No response
E35Unable to refund
E36Previous transaction is on hold
D37Blocked by acquirer
E38Invalid expiry date
E39Invalid expiry date
E40Invalid transaction type
D41Insufficient funds
D42Card security code (CVV) mismatch
E43Email not valid/not supplied
E44Phone number not valid/not supplied
E45Transaction mode differs from original
D463DSecure authentication not available for this card
D473DSecure authentication rejected
E48Description not set
D49Sold out
E50Card is for ATM use only
D51Transaction part 1 not authorised
D52Transaction part 2 not authorised
X53Authorisation expired
E54Transaction part not specified
E55Unable to access transaction part
E56Duplicate transaction
D57Continuous authority not available on referenced transaction
E58Error connecting to service provider
E59Request aborted
E60Verification failed
D61Not authorised
D62Not authorised
D63Address verification (AVS) mismatch
D64Card security code (CVV) and address (AVS) mismatch
D65Card is not enabled for e-commerce
D66Card cancelled
D67Transaction not permitted by issuer
D68No suitable account
D80Not authorised
Card Filter module. Message text can be changed
D90Not authorised
D91Not authorised
D92Not authorised
D93Card limits exceeded
D94Not authorised
D95Not authorised
D96Not authorised
E98Internal system error
E99Unknown error

Response code 01 (Invalid Request)

This data is not used as part of the transaction processing, but a record of the data is kept with the transaction. This can be of use should a customer dispute a transaction, providing additional details of where the device was when the transaction was processed.

There are many possible causes of the ‘Invalid Request’ response. In order to help maintain system security the exact cause is not contained with the response. For example the reason could be that the request has been received from an un-authorised IP address, or that the password used is not correct. This information is not divulged as part of the response data, you will need to view the exception report to see the full details.

A common cause of this error is attempting to use the mobile API without first requesting that it is added to your account. You must first request that the mobile API is added to your account before you start to use it – this is not enabled by default. As part of the activation process you will be supplied with the authentication key.

Card Type Codes

VIVisa
VCVisa Credit
VDVisa Debit
VEVisa Electron
VPVisa Purchasing
VBVisa Corporate
MSMasterCard
MCMasterCard Credit
MDMasterCard Debit
MAMaestro UK
MUMaestro
AXAmerican Express
AMAmerican Express
APAmerican Express Purchasing
DNDiners
JCJCB
DSDiscover
PPPayPal
XXUnknown

Supported Currency Codes

AEDUnited Arab Emirates Dirham
BHDBahraini Dinar
CADCanadian Dollar
EGPEgyptian Pound
EUREuro
IDRIndonesian Rupiah
GBPPound Sterling
JODJordanian Dinar
JPYJapanese Yen
KHRCambodian Riel
KWDKuwaiti Dinar
MYRMalaysian Ringgit
OMROmani Rial
PHPPhilippine Peso
QARQatari Rial
SARSaudi Riyal
SGDSingapore Dollar
THBThai Baht
USDUS Dollar
VNDVietnamese Dong
INRIndian Rupee

ISO Country Codes

ISOCountry
AFAfghanistan
ALAlbania
DZAlgeria
ASAmerican Samoa
ADAndorra
AOAngola
AIAnguilla
AGAntigua and Barbuda
ARArgentina
AMArmenia
AWAruba
AUAustralia
ATAustria
AZAzerbaijan
BSBahamas
BHBahrain
BDBangladesh
BBBarbados
BYBelarus
BEBelgium
BZBelize
BJBenin
BMBermuda
BTBhutan
BOBolivia
BABosnia and Herzegovina
BWBotswana
BRBrazil
IOBritish Indian Ocean Territory
VGBritish Virgin Islands
BNBrunei Darussalam
BGBulgaria
BFBurkina Faso
BIBurundi
KHCambodia
CMCameroon
CACanada
CVCape Verde
KYCayman Islands
CFCentral African Rep
TDChad
CLChile
CNChina
CXChristmas Island
CCCocos (Keeling) Islands
COColombia
KMComoros
CDCongo, Democratic Rep of
CGCongo, Republic of
CKCook Islands
CRCosta Rica
CICote d'Ivoire
HRCroatia
CUCuba
CYCyprus
CZCzech Rep
DKDenmark
DJDjibouti
DMDominica
DODominican Rep
ECEcuador
EGEgypt
SVEl Salvador
GQEquatorial Guinea
EREritrea
EEEstonia
ETEthiopia
FKFalkland Islands
FOFaroe Islands
FJFiji
FIFinland
FRFrance
GFFrench Guyana
PFFrench Polynesia
GAGabon
GMGambia
GEGeorgia
DEGermany
GHGhana
GIGibraltar
GRGreece
GLGreenland
GDGrenada
GPGuadeloupe
GUGuam
GTGuatemala
GNGuinea
GWGuinea-Bissau
GYGuyana
HTHaiti
HNHonduras
HKHong Kong
HUHungary
ISIceland
INIndia
IDIndonesia
IRIran
IQIraq
IEIreland
ITItaly
JMJamaica
JPJapan
JOJordan
KZKazakhstan
KEKenya
KIKiribati
KPKorea, North
KRKorea, South
KWKuwait
KGKyrgyzstan
LALaos
LVLatvia
LBLebanon
LSLesotho
LRLiberia
LYLibya
LILiechtenstein
LTLithuania
LULuxembourg
MOMacau
MKMacedonia
MGMadagascar
MWMalawi
MYMalaysia
MVMaldives
MLMali
MTMalta
MHMarshall Islands
MQMartinique
MRMauritania
MUMauritius
YTMayotte
MXMexico
FMMicronesia
MDMoldova, Rep of
MCMonaco
MNMongolia
MEMontenegro
MSMontserrat
MAMorocco
MZMozambique
MMMyanmar
NANamibia
NRNauru
NPNepal
NLNetherlands
ANNetherlands Antilles
NCNew Caledonia
NZNew Zealand
NINicaragua
NENiger
NGNigeria
NUNiue
NFNorfolk Island
MPNorthern Mariana Islands
NONorway
OMOman
PKPakistan
PWPalau
PSPalestinian Territory, Occupied
PAPanama
PGPapua New Guinea
PYParaguay
PEPeru
PHPhilippines
PNPitcairn Islands
PLPoland
PTPortugal
PRPuerto Rico
QAQatar
REReunion
RORomania
RURussian Federation
RWRwanda
WSSamoa
SMSan Marino
STSao Tome and Principe
SASaudi Arabia
SNSenegal
RSSerbia
SCSeychelles
SLSierra Leone
SGSingapore
SKSlovakia
SISlovenia
SBSolomon Islands
SOSomalia
ZASouth Africa
ESSpain
LKSri Lanka
SHSt Helena
KNSt Kitts and Nevis
LCSt Lucia
PMSt Pierre and Miquelon
VCSt Vincent and Grenadines
SDSudan
SRSuriname
SZSwaziland
SESweden
CHSwitzerland
SYSyria
TJTajikistan
TWTaiwan, Rep of China
TZTanzania
THThailand
TLTimor-Leste
TGTogo
TKTokelau
TOTonga
TTTrinidad and Tobago
TNTunisia
TRTurkey
TMTurkmenistan
TCTurks and Caicos Islands
TVTuvalu
UGUganda
UAUkraine
AEUnited Arab Emirates
GBUnited Kingdom
VIUnited States Virgin Islands
USUnited States of America
UYUruguay
UZUzbekistan
VUVanuatu
VAVatican City
VEVenezuela
VNViet Nam
WFWallis and Futuna Islands
EHWestern Sahara
YEYemen
ZMZambia
ZWZimbabwe

Test Cards

These card numbers can be used when testing your integration to the payment gateway. These cards will not work for live transactions.

Card numberTypeCVVMPI
4000 0000 0000 0002Visa123No
4111 1111 1111 1111Visa123Yes
4444 3333 2222 1111Visa123Yes
4444 4244 4444 4440Visa123Yes
4444 4444 4444 4448Visa123Yes
4012 8888 8888 1881Visa123Yes
5105 1051 0510 5100Mastercard123No
5454 5454 5454 5454Mastercard123Yes
5555 5555 5555 4444Mastercard123Yes
5555 5555 5555 5557Mastercard123Yes
5581 5822 2222 2229Mastercard123Yes
5641 8209 0009 7002Maestro UK123Yes
6767 0957 4000 0005Solo123No
3434 343434 34343American Express1234No
3566 0020 2014 0006JCB123No
3111 1111 1111 1111MADA123No

When these card numbers are used with a transaction class that requires the card security data (such as e-commerce transactions) then you should use the value 123 for all cards except for American Express which requires 1234.

For e-commerce transactions, cards which show ‘Yes’ in the MPI column will use a simulated 3D Secure authentication page, allowing you to test the transaction flow when Verified by Visa or MasterCard SecureCode is used.

Simulating decline/error responses

When it test mode, and when using the above test cards, you can simulate any of the transaction response codes by using specific values for the card security code (CVV). By taking the response code you want to simulate, pad that code with a leading ‘0’ in order to make it a 3 digit code and use that for the CVV.

For example, to simulate the Insufficient Funds response (status ‘D’, code ‘41’) use 041 as the CVV.

You can also simulate an on-hold transaction in the same way. On hold is where the transaction has been authorised, but the anti-fraud system has flagged the transaction for inspection. Whilst the transaction is on-hold, no funds will be debited from the customers’ card. You would need to use the Merchant Administration System to either accept or reject the transaction. To simulate the on-hold response within the test system, use a CVV value of ‘999’ with one of the above test cards.

Updated on March 9, 2021

Related Articles