Payments API

Methods of Operation

The TransactDirect Payments API allows merchants to process transactions directly with Monek. Primary use cases for this are:

• Automated processing of repeat transactions. e.g. Monthly billing or ad-hoc card on file charges.
• Automated processing of refunds or cancellations.
• Integration in call centre systems or automated telephony solutions.
• Integration from PCI:DSS accredited parties wishing to take full control of their payment journey.

For merchants integrating a secure checkout page for their website or application see our Checkout Page documentation.

Gateway URLs

Gateway URLs

• Primary: https://elite.monek.com/Secure/Transact.ashx
• Staging: https://staging.monek.com/Secure/Transact.ashx

Note: Both gateways are LIVE and will process for all Monek Merchant accounts.

The staging API is available for integration and compatibility testing of new features before they are available on the primary platform.

Recommended Features

The TransactDirect Payments API supports a number of features we recommend for additional security and convenience:

• Idempotency Tokens provide a reliable way to protect against against duplicate transactions and replay events.
• Basket Details provides an updated and flexible method of sending itemised basket details for your transaction that also satisfies required transaction details for American Express.

Sequence of Events

A typical sequence of events with the TransactDirect Payments API is a synchronous transaction request and response. Transaction request data is passed securely over the Internet to TransactDirect, processed by Monek, and returned directly to the calling party.

Additional flows are supported where required for custom integrations by using alternate ResponseAction and ThreeDSAction parameters, e.g.

• Response redirects
• EMV 3-D Secure by API

Payments API Request

The following tables detail the fields that are used to pass transaction data from the merchant to TransactDirect. Every transaction that is passed to TransactDirect must include those fields listed in the 'Mandatory Generic Transaction Request Fields' table.

Further sections contain fields marked as mandatory that are situational and should be considered mandatory when using that functionality. For example where Card Keyed Transaction Request Fields are marked mandatory they should only be considered mandatory when sending Card Keyed transactional data, if you are sending a Cross Reference in lieu of Card Keyed details then those fields are no longer required.

A selection of optional fields is provided to allow access to further functionality and a number of additional features are also supported and documented separately for clarity:

• Prepared Payments provide a secure way to protect merchant and transaction details with a simple redirect token.
• Idempotency Tokens provide a reliable way to protect against against duplicate transactions and replay events.
• The Integrity Digest provides a secure method to verify that responses, redirects, and webhooks are genuine and unmodified.
• Webhooks provide a simple notification service for transaction results without relying on the cardholder transaction flow.

Mandatory Generic Transaction Request Fields

Field Name	Description	Req'd	Size	Type
Amount	The transaction amount, numeric, in minor currency i.e. pence/cents etc. No decimal point. e.g. £10.02 = 1002	M	10 max.	N
CountryCode	ISO standard country code for merchant location. Use 826 for UK based merchants. Other options available on request.	M	3	N
CurrencyCode	ISO standard currency code of transaction. Use 826 for Sterling transactions. Other options available on request.	M	3	N
Dispatch	Used for Deferred Dispatch. Options are NOW or LATER.	M	5 max.	A
MerchantID	Monek merchant ID. Test accounts are available on request.	M	7	N
MessageType	Indicates the transaction type for the request.See later table for acceptable message types.	M	V	A
ResponseAction	Specifies the return method for the transaction response data. Options are HTMLQS, XML, REDIRECT, or JSON	M	V	A

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Card Keyed Transaction Request Fields

Field Name	Description	Req'd	Size	Type
CardNumber	Card number.	M	20 max.	N
ExpiryMonth	Expiry month.	M	2	N
ExpiryYear	Expiry year.	M	2	N
ExpiryDate	Expiry date in MM/YY format. Can be supplied in place of ExpiryMonth and ExpiryYear.	M	4	N
StartMonth	Start month.	O	2	N
StartYear	Start year.	O	2	N
StartDate	Start date in MM/YY format. Can be supplied in place of StartMonth and StartYear.	O	4	N

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Tokenised Card Transaction Request Fields

Field Name	Description	Req'd	Size	Type
CardToken	This is sent in lieu of the card details (card number, expiry month and year, start month and year) and can be used for reprocessing a stored card. e.g. For continuous authority. Note: Deprecated in favour of CrossReference.	O	50 max.	A
CrossReference	This is sent in lieu of the card details (card number, expiry month and year, start month and year) and is typically used for completing transactions that were originally submitted as Dispatch = LATER, processing referrals, re-billing or refunding previous transactions.	O	50 max.	A
ValidityID	Is used by TransactDirect in conjunction with MerchantID to provide additional security. ValidityID will be issued by Monek and can be used to authenticate repeat transactions and refunds performed by Cross Reference. Note: ValidityID must be kept private and should only be used on direct API calls. Do not use on hosted page redirects.	M/O	20 max.	A

Note: Merchants who wish to conduct transactions using Tokenised Card details must contact Monek to obtain a ValidityId.

Secure Hosting Card Link Request Fields

For merchant migrating from Secure Hosting TransactDirect provides the facility to directly reference previous transactions by their Secure Hosting Transaction ID.

Transaction responses will include a new TransactDirect CrossReference which should then be used for all future processing.

Field Name	Description	Req'd	Size	Type
shReference	Your Secure Hosting account reference number e.g. SH212345	O	8	A
shCheckCode	Your Secure Hosting Check Code. This can be found in the settings menu in your Secure Hosting account.	O	6	N
shTransactionId	The numeric Transaction ID of the Secure Hosting transaction you wish to recharge or refund	O	10 max.	N

3-D Secure Transaction Request Fields

Field Name	Description	Req'd	Size	Type
Ret3DSAddress	If ThreeDSAction = REDIRECT is used, this is the address (URL) to which the web client will be redirected with ACS information. The fields required to perform payer authentication are appended to this address as query string fields.	O	V	A
PurchaseDescription	Summary description of purchase. Passed to 3-D Secure.	O	125 max.	A
ThreeDSAction	Used to indicate requirement of 3-D Secure processing and to tell TransactDirect which method to use for the return of ACS data. Options are: - NONE (default) - HTMLQS - XML - REDIRECT - ACSDIRECT	M	V	A
ThreeDSPAContinueOnError	Options are YES or NO (default). If set to YES, TransactDirect will allow a transaction to continue if an error occurred processing payer authentication details.	O	2 or 3	A
ThreeDSVEContinueOnError	Options are YES or NO (default). If set to YES, TransactDirect will allow a transaction to continue if an error occurred verifying card enrolment details.	O	2 or 3	A

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Cardholder Detail Request Fields

Field Name	Description	Req'd	Size	Type
CardholderName	Customer's name. Note: Mandatory for 3DS v2 transactions.	O	30 max.	A
QAAddress	Required for AVS check. Customer's address. Note: Deprecated in favour of Billing fields.	O	100 max.	A
QAPostcode	Required for AVS check. Customer's postcode. Note: Deprecated in favour of Billing fields.	O	10 max.	A
EmailAddress	Customer's email address. Note: email or phone number is mandatory for Visa 3-D Secure.	O	50 max.	A
PhoneNumber	Customer's telephone number. Note: email or phone number is mandatory for Visa 3-D Secure.	O	30 max.	A
BillingName	Customer's name for billing purposes.	O	200 max.	A
BillingCompany	Company name for billing purposes.	O	200 max.	A
BillingLine1	Billing address line 1	O	200 max.	A
BillingLine2	Billing address line 2	O	200 max.	A
BillingLine3	Billing address line 3	O	200 max.	A
BillingCity	Billing city	O	100 max.	A
BillingCounty	Billing county	O	100 max.	A
BillingPostcode	The billing postcode	O	20 max.	A
BillingCountry	The billing country name	O	100 max.	A
BillingCountryCode	The 3 digit country code for billing country	O	3	A
DeliveryIsBilling	Indicates if the delivery address is also the billing address. YES or NO (default)	O	3	A
DeliveryName	Customer's name for delivery purposes.	O	200 max.	A
DeliveryCompany	Company name for delivery purposes.	O	200 max.	A
DeliveryLine1	Delivery address line 1	O	200 max.	A
DeliveryLine2	Delivery address line 2	O	200 max.	A
DeliveryLine3	Delivery address line 3	O	200 max.	A
DeliveryCity	Delivery city	O	100 max.	A
DeliveryCounty	Delivery county	O	100 max.	A
DeliveryPostcode	The delivery postcode	O	20 max.	A
DeliveryCountry	The delivery country name	O	100 max.	A
DeliveryCountryCode	The 3 digit country code for delivery country	O	3	A

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Additional Transaction Request Fields

Field Name	Description	Req'd	Size	Type
AcceptCOF	Indicates if the cardholder has been informed and has accepted that their card details will be stored for future use. Options are YES or NO (default).	O	2 or 3	A
AuthorisationCode	Required when MessageType is prefixed with PAYMENT_ONLY_ (ignored if sent with any other MessageType) indicating that prior authorisation has been given by the merchant's acquiring bank. e.g. following a referral when the merchant has contacted the bank's voice authorisation centre.	O	8 max.	A
Basket	Contains basket details for this transactions. Replaces Line Item structures noted in Accepting Amex. See Basket Details for further infomation.	O	1000 max.	A
CAType	Specifies the type of cardholder agreement in place for the transaction. see Cardholder Agreement Types for details.	O	15 max.	A
COFInitiatedBy	Indicates if a Credentials on File (COF) transaction was initiated by the cardholder or by the merchant. Options are CARDHOLDER or MERCHANT.	O	10 max.	A
CV2	Card Verification Value normally printed after the card number on the card's magnetic strip. Note: The CV2 value must not be stored under any circumstances.	O	3 or 4	N
DispatchLaterAmount	The total amount of the transaction. Numeric, minor currency i.e. pence/cents etc. No decimal point e.g. £10.02 = 1002 Note: Deprecated. Dispatch later transaction should authorise for the full amount or utilise Account Verification.	M	10 Max	N
EchoReceiptInformation	Passes back all the information that a merchant needs to produce a customer's receipt. Options are YES or NO (default). If set to YES, the receipt information is returned as the additional field ReceiptInformation.	O	2 or 3	A
FailureUrl	If ResponseAction = REDIRECT is used, this is the address (URL) to which the web client will be redirected following an unsuccessful transaction. If not supplied SuccessUrl will be used for all responses. Replaces RetNotOkAddress.	O	V	A
IdempotencyToken	Specifies a merchant wide unique identifier for this transaction. Note: Use with caution. See Transaction Idempotency for details. Note: IdempotencyToken should be kept private and only used on direct API calls or Prepared Payments.	O	50 max.	A
IntegritySecret	Provides a secret only known to the merchant. Used to support the Integrity Digest functionality	O	50 max.	A
IsDebtRepayment	Indicates if the payment forms part of a debt repayment. Options are YES or NO (default).	O	2 or 3	A
OperatorId	The operator identifier for the user intiating this transaction. Used to allow a merchant to track which user initiated transactions.	O	100 max.	A
OperatorName	The operator name for the user initiating this transaction. Used to allow a merchant to track which user initiated transactions.	O	100 max.	A
OriginId	GUID used by Monek to provide additional insight and support for key integration partners and solutions. Contact Monek for more information	O	40 max.	A
SuccessUrl	If ResponseAction = REDIRECT is used, this is the address (URL) to which the web client will be redirected following a successful transaction. If FailureUrl is not specified SuccessUrl will be used for all results. Replaces RetOkAddress.	O	V	A
WebhookUrl	The secure URL (https) to send a transaction summary to on completion of the transaction. See Webhooks for more information.	O	100 max.	A

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Additional Form Fields

Additional merchant specific data should be sent in the PaymentDetail or MerchantData field.

Use of this field for merchant data ensures there are no clashes with fieldnames that may be required to support future functionality on the TransactDirect API.

This field can be used to store a simple value, complex encoded data (such as JSON) or raw binary data. In all cases the supplied value should be Base64 encoded.

Field Name	Description	Req'd	Size	Type
PaymentReference	ID created by the merchant to identify the transaction. Replaces TransactionIdentifier.	O	50 max.	A
PaymentChannel	Payment channel description as required by the merchant.	O	50 max.	A
PaymentDetail	Additional custom payment details for this transaction.	O	500 max.	A
MerchantData	Additional custom merchant data for this transaction.	O	1024max	Base 64

Base64 encoding supports the following key goals:

• Supports any underlying data format required by the merchant.
• Data can be returned unaltered without encoding complications.
• Ensures maximum compatibility with security mechanisms.

Additional Form Fields – Legacy Functionality

warning

Support for additional form or query string fields sent to TransactDirect using custom names has been removed. Please use the PaymentDetail or MerchantData fields.

TransactDirect Message Types

MessageType	Description
ESALE_KEYED	E-Commerce (Internet) sale transaction, card keyed by cardholder.
EVERIFY_KEYED	E-Commerce (Internet) account verification transaction, card keyed by cardholder. Note: Transaction amount must be ZERO (0).
SALE_CNP_MO	Sale transaction, cardholder not present, mail order. Replaces SALE_CNP.
SALE_CNP_TO	Sale transaction, cardholder not present, telephone order. Replaces SALE_CNP.
VERIFY_CNP	Account verification transaction, cardholder not present (typically from call-centre i.e. telephone, mail order, etc.). Note: Transaction amount must be ZERO (0).
SALE_CA	Sale transaction with continuous authority.
REFUND_CNP	Refund transaction, cardholder not present (typically from call-centre or merchant back-office i.e. telephone, mail order, etc.).
REVERSAL_KEYED	Reverses a previous transaction. Note: Must be performed by Cross Reference. Original transaction MUST be from same day.

Notes:

• The following transactions are only acceptable when accompanied by a ValidityId.

  • Transactions conducted using the original transaction's Cross Reference in lieu of card details.
  • Refunds and reversals.
  • Transactions prefixed with PAYMENT_ONLY.

• Certain message types, for example, continuous authority (SALE_CA etc.) are only available by prior arrangement with the merchant's acquiring bank.

• Standard Internet-based sale transactions such as purchasing from a web site/on-line store will usually be flagged as ESALE_KEYED. If the Internet is used purely for the transport of information from the merchant directly to the gateway, then the appropriate cardholder present or not present message type should be used.

Payment Only Transactions

TransactDirect Message Types can be prefixed with PAYMENT_ONLY_ to indicate that no authorisation is required. Such transactions are not forwarded to the bank for authorisation and are sent for settlement on the assumption that the merchant has obtained authorisation from some other source. Typical scenarios where this may be appropriate are:

• The original transaction resulted in a referral and the settlement confirmation is being sent following a call to the bank's voice authorisation centre.
• When presenting transactions to TransactDirect following a period of communications failure.
• Where the original transaction was sent as DISPATCH = LATER and is now ready for settlement.

The following standard fields have particular importance for a PAYMENT_ONLY_ transaction:

Field Name	Description	Req'd	Size	Type
AuthorisationCode	Must contain the authorisation code obtained during the referral process or original authorisation.	M	8 max.	A
CrossReference	When processing a PAYMENT_ONLY_ request following an authorisation only or referral transaction the CrossReference from the original transaction should always be used. Not required when a presenting an offline transaction following a period of communications failure. In this scenario the full card details would be required.	O	50 max.	A
ValidityID	Used by TransactDirect in conjunction with MerchantID to provide additional security. ValidityID will be issued by Monek and can also be used to authenticate repeat transactions and refunds performed by Cross Reference. Note: ValidityID must be kept private and should only be used on direct API calls. Do not use on hosted page redirects.	M/O	20 max.	A

Cardholder Agreement Types

TransactDirect allows a transaction to be identified as part of a continuous authority agreement with the cardholder.

This should be specified as appropriate in the CAType field in the transaction request for the initiating transaction and all subsequent payment requests.

CA Type	Usage	Description
A or Reauthorisation	Additional Only	Indicates a reauthorisation made after the original purchase. Common scenarios include delayed/split shipments and extended stays/rentals.
C or Unscheduled	Additional Only	Indicates a transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.
D or Delayed	Additional Only	Indicates a delayed charge. Typically used in hotels, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.
I or Instalment	Initiating or Additional	Indicates that this transaction is part of an instalment agreement. Instalment transactions should be used to charge a predictable amount at regular intervals.
L or Incremental	Additional Only	Indicates an incremental authorisation. Typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract.
N or NA	Initiating or Additional	Indicates that no specific cardholder agreement is in place.
R or Recurring	Initiating or Additional	Indicates that this transaction is part of a recurring agreement. Recurring payment transactions may be recharged as required by the merchant to satisfy future purchases. Note: For PayPal Express Checkout integrations this must be set to indicate the requirement for a PayPal recurring payment billing agreement.
S or Resubmission	Additional Only	Indicates a resubmission for a transaction that occurred with the original purchase, but where the card acceptor was not able to get authorisation at the time the goods or services were provided.
X or NoShow	Additional Only	Indicates a transaction where the cardholder entered into an agreement to purchase but did not meet the terms of the agreement.

Common Currency Codes

Currency	ISO-4217 Code
Australian Dollar	036
Canadian Dollar	124
Czech Koruna	203
Danish Krone	208
Hong Kong Dollars	344
Icelandic Krona	352
Japanese Yen	392
Norwegian Krone	578
Singapore Dollars	702
Swedish Krona	752
Swiss Franc	756
Pound Sterling	826
US Dollars	840
Euro	978

Note:

• Merchants must have obtained prior clearance from their UK acquiring bank (acquirer) before accepting multi-currency transactions.
• Certain acquirers will require separate merchant numbers to be issued.
• Not all acquirers accept all of these currencies whilst some accept many more.
• Multi-currency transactions must be identified by their numeric three-digit currency code, as per ISO-4217.

3-D Secure API Response

If the ThreeDSAction field was set and the Transact.ashx has determined that user authentication is required, then an appropriate 3-D Secure response will be returned and must be processed by the merchant. Otherwise a standard Transaction Response will be returned.

In most cases the [Checkout Page](checkout-page.mdx) flow is more appropriate for Ecommerce transactions with 3-D Secure

XML

If the ThreeDSAction field was set to XML the response fields are sent to the client as XML 1.0 formatted tags and values in the body of the HTTP where the HTML is normally found e.g.

<?xml version="1.0" encoding="UTF-8"?>
<veresponse>
    <md>[ENCODEDDATA]</md\> 
    <enrolled>Y</enrolled> 
    <pareq>[ENCODEDDATA]</pareq> 
    <acsurl>https://dropit.3dsecure.net:9443/PIT/ACS</acsurl>
</veresponse>

HTMLQS

If the ThreeDSAction field was set to HTMLQS the response fields are sent to the client as a list of field names and values in the body of the HTTP response where the HTML is normally found e.g.

MD=<ENCODEDDATA>&PaReq=<ENCODEDDATA>&ACSURL=https%3a%2f%2fdropit.3dsecure.net%3a9443%2fPIT%2fACS

REDIRECT

If the ThreeDSAction field was set to REDIRECT TransactDirect issues a re-direct to the web client, redirecting it to the Ret3DSAddress with the response fields sent as query string attachments to the re-direct URL e.g.

http://www.myurl.com/3ds.asp?md=[ENCODEDDATA]&pareq=[ENCODEDDATA]&acsurl== https%3a%2f%2fdropit.3dsecure.net%3a9443%2fPIT%2fACS

ACSDIRECT

If the ThreeDSAction field was set to ACSDIRECT then TransactDirect will automatically redirect the client to the appropriate ACS URL for authentication. The ACS request will be configured to automatically redirect back to TransactDirect (TransactACS.ashx) on completion.

Note: This method provides for the simplest implementation of 3-D Secure and requires no additional coding or communication with the Web Client due to the automatic redirect handling, however this flow is more appropriate when using the Checkout Page transaction flow.

3-D Secure ACS Response Fields

If the ThreeDSAction was set to HTMLQS, XML or REDIRECT the response will include the following fields to allow the Web Client to handle the ACS redirection. For example, if the Web Client needs to embed the ACS prompt within a branded web page.

Field Name	Description	Size	Type
ACSURL	Access Control Server URL. Used in redirecting the client browser to the card issuer's 3-D Secure authentication host.	V	A
MD	Merchant Data. All transaction data is retained by the Transact.ashx page. The MD field is used to allow this data to be retrieved and must be included unaltered in the subsequent calls to the ACSURL and TransactACS.ashx.	V	A
PAReq	The full 3-D Secure request as returned by the card scheme enrolment verification server. This should be passed in its entirety to the issuer's ACS.	V	A

Redirect to Card Issuer's ACS

The web client must redirects the cardholder to the 3-D Secure web server at ACSURL by sending the following fields as an HTTP POST request. Note: The ACSURL will not accept transactions redirected using the HTTP GET method.

Field Name	Description	Req'd	Size	Type
MD	Merchant Data. This field should be passed unaltered from the Transact.ashx response.	M	V	A
PaReq	The full 3-D Secure request. This field should be passed unaltered from the Transact.ashx response.	M	V	A
TermUrl	Termination URL. This is the address that the issuer's ACS will call after payer authentication is complete.	M	50 max.	A

The TermUrl field can be used to direct the ACS response back to the Web Client or directly to TransactACS.ashx to complete the transaction.

ACS Response Fields

If TermUrl is set to direct responses to the merchant web site, then the following fields will be returned. All fields should be forwarded in their entirety and unaltered to TransactACS.ashx to complete the transaction.

Field Name	Description	Req'd	Size	Type
MD	Merchant Data.	M	V	A
PaRes	The full 3-D Secure response as returned by the cardholder's issuer.	M	V	A

If TermUrl is set to direct to TransactACS.ashx then these fields will be passed automatically.

Payment API Response

warning

Please note that all request and response fields are considered case insensitive and may vary depending on response type and TransactDirect version.

Please ensure any response handling does not limit field processing to a specific character casing.

The response format will depend on the ResponseAction requested when initiating the transaction.

JSON

If the ResponseAction field was set to JSON the response fields are sent to the client as a JSON formatted structure. The new JSON return format is recommended and contains a much richer level of details for the completed transaction.

{
    "transactionDateTime": "2024-04-01T10:11:12.9798042+01:00",
    "requestDateTime": "2024-04-01T10:11:12.4217561+01:00",
    "amount": "2500",
    "currencyCode": "826",
    "countryCode": "826",
    "result": {
        "paymentMethod": "TransactDirect",
        "crossReference": "240401101112457459X2R",
        "responseCode": "00",
        "responseMessage": "AUTHCODE:457459",
        "authorisationCode": "457459",
        "avsCv2Code": "244100",
        "avsCv2Message": "SECURITY CODE MATCH ONLY",
        "threeDSecure": {
            "enrolled": "Y",
            "authenticated": "Y",
            "eci": "05",
            "cavv": "AAACAkl2BRkiFiFSYHYFEwAAAAA=",
            "transactionId": "83726342788159100000"
        },
        "terminalId": "22080001",
        "messageNumber": "2903"
    },
    "merchant": {
        "monekId": "0000893",
        "merchantNumber": "123456789",
        "name": "Monek Test Account",
        "location": "Lichfield"
    },
    "cardholder": {
        "address": "155",
        "postcode": "16"
    },
    "card": {
        "maskedCard": "401200******1112",
        "expiryDate": "2412",
        "cardType": "VC",
        "cardDescription": "Visa Credit"
    }
}

HTMLQS

If the ResponseAction field was set to HTMLQS the response fields are sent to the client as a list of field names and values in the body of the HTTP response. e.g.

ResponseCode=00&Message=AUTHCODE:01223&CrossReference=03050711535801223303

XML

If the ResponseAction field was set to XML the response fields are sent to the client as XML 1.0 formatted tags and values. e.g.

<?xml version="1.0" ?>
<transactionresponse>
    <responsecode>00</responsecode>
    <message>AUTHCODE:06166</message>
    <crossreference>03050711584106166163</crossreference>
</transactionresponse>

REDIRECT

If the ResponseAction field was set to REDIRECT TransactDirect issues a re-direct to the web client with the response fields sent as query string attachments to the redirect URL e.g.

http://www.myURL.com/SuccessUrl.asp?ResponseCode=00&Message=AUTHCODE%3A01223&CrossReference=03050711535801223303

Redirecting to the RetOKAddress or RetNotOKAddress depends upon the transaction outcome:

Transaction Outcome	Redirection URL
Successful transaction	SuccessUrl
Card referred	FailureUrl
Card declined	FailureUrl
Problem with card. e.g. invalid card number, expired card, etc.	FailureUrl
Processing error	FailureUrl

Standard Response Fields

The result of the transaction is passed back in the following fields.

Field Name	Contents	Size	Type
Amount	Amount sent with transaction request to acquiring bank or, in the event of a payment only transaction, accepted by TransactDirect. Value returned in minor currency i.e. pence/cents etc.	10 max.	N
AuthorisationCode	The authorisation code issued for a successful transaction. Normally this is 2 digits for American Express and 6 for other card schemes. Note: An authorisation code is strictly alphanumeric. While typically numeric an authorisation code may also contain letters.	2-8	A
AVSCV2Check	AVS/CV2 check response. See following table.	30 max.	A
AVSCV2ResponseCode	The raw AVS/CV2 code returned by the acquiring bank. See following tables.	6	N
CardToken	The unique character string supplied by TransactDirect to identify this card. Optional: Will be returned where the merchant is configured to support card tokens.	50 max.	A
CardType	The card type code indicating the card type used for the transaction. See following table.	2	A
CrossReference	The unique character string supplied by TransactDirect to identify this transaction.	50 max.	A
CurrencyCode	The currency code used for the transaction.	3	N
DuplicateIndicator	Contains the reason for a duplicate transaction response. DUPLICATE or IDEMPOTENCY	20 max.	A
ErrorCode	May contain an additional error detail code where standard response code indicate and error "30". This code can be used by Monek to further diagnose the cause of an error.	4	N
Message	The transaction message either as delivered by the bank or by TransactDirect. This is the message that should be displayed to the merchant on an EPOS system or call centre application and to the cardholder on an Internet web site implementation. Typical examples are: AUTHCODE:123456 CARD EXPIRED CARD REFERRED CARD DECLINED CARD DECLINED – KEEP CARD AVS CV2 DECLINED ERROR XXXX	80 max.	A
PaymentMethod	The payment method used to process the transaction: TransactDirect or PayPal	50 max.	A
ReferralTelephoneNumber	The referral telephone number passed to TransactDirect by the merchant's acquirer in the event of a transaction being referred. Note: In most circumstances the merchants will have been provided with a standard referral telephone number by their acquiring bank and should primarily use that number in the event of a referral.	16 max.	N
RequestTime	The time the transaction request was initiated in ISO 8601 format.	33	A
ResponseCode	The TransactDirect response code. See following table.	2	N
TrackingToken	A unique tracking token for the payment card used. Note: Only returned by prior partner arrangement.	32	A

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric

Response Code Values

Response Code	Description
00	Transaction successful / authorised
02	Card referred
03	Retailer unknown
04	Keep card decline
05	Card declined
11	Invalid card details
12	Invalid request
30	Exception

AVS/CV2 Response Values

AVS/CV2 Response Code Values

The AVS/CV2 Response Code is made up of six characters and is sent back in the raw form that is received from the acquiring bank.

Position 1

Position 1 Value	Position 1 Description
0	No additional information available
1	CV2 not checked
2	CV2 matched
4	CV2 not matched
8	Reserved

Position 2

Position 2 Value	Position 2 Description
0	No additional information available
1	Postcode not checked
2	Postcode matched
4	Postcode not matched
8	Postcode partially matched

Position 3

Position 3 Value	Position 3 Description
0	No additional information available
1	Address not checked
2	Address matched
4	Address not matched
8	Address partially matched

Position 4

Position 4 Value	Position 4 Description
0	Authorising entity not known
1	Authorising entity – Merchant host
2	Authorising entity – Acquirer host
4	Authorising entity – Card Scheme
8	Authorising entity – Issuer

Position 5

Position 5 Value	Position 5 Description
0	Reserved
1	Reserved
2	Reserved
4	Reserved
8	Reserved

Position 6

Position 6 Value	Position 6 Description
0	Reserved
1	Reserved
2	Reserved
4	Reserved
8	Reserved

Note:

• Values other than 0, 1, 2, 4 or 8 are not valid in character positions 1 to 4.
• A value of zero in any character position indicates that no additional information is available.
• If the Authorising Entity is not known, then character position 4 is set to zero and the authoriser is assumed to be the issuer.

AVS/CV2 Check Response Values

AVS and CV2 checks are supported by most major card issuers including Visa, MasterCard, Maestro and American Express.

AVS / CV2 Response Message	Description
ALL MATCH	AVS and CV2 match.
SECURITY CODE MATCH ONLY	CV2 match only.
ADDRESS MATCH ONLY	AVS match only.
NO DATA MATCHES	No matches for AVS and CV2.
DATA NOT CHECKED	Supplied data not checked.
SECURITY CHECKS NOT SUPPORTED	Card scheme does not support checks.
UNKNOWN RESPONSE	Unrecognised AVS/CV2 response from issuer.

As part of the AVS/CV2 design, responses are passed back along with the authorisation outcome. This can result in a situation where the transaction has been authorised by the card issuer, but the AVS/CV2 checks have returned negative results. At this point, the merchant may decide not to proceed with the transaction. In these circumstances, under normal UK banking practice, a merchant would need to cancel, reverse or refund the transaction. This is often not practical to achieve in situations where the merchant is not present for the transaction, such as Internet retailers.

TransactDirect removes the necessity for the merchant to explicitly carry out the cancellation, reversal or refund by providing the merchant with AVS/CV2 acceptance parameters governing what action to take dependent upon the AVS/CV2 result.

Card Type Values

The following card type codes are currently supported. This list is subject to change as new card types are added.

Card Type Code	Card Type
AM	American Express
DI	Diners Club
DS	Discover
EL	Electron
JC	JCB
MA	Maestro (International)
MC	MasterCard
MD	MasterCard Debit
SW	Maestro (UK issued)
VC	Visa Credit
VD	Visa Debit
VP	Visa Purchasing

3-D Secure Result Fields

Field Name	Description	Size
Emv3DS	The EMV 3-D Secure details as returned from the authentication process. Comma separated.	150 max.
ThreeDS	The 3-D Secure details as returned from the verify enrolment and payer authentication stages. Comma separated in Monek 2.1 compliant form.	60 max.
ThreeDSErrorCode	Code issued by 3-D Secure if either enrolment verification or 3-D Secure authentication failed with an error.	V
ThreeDSErrorDetail	Error description issued by 3-D Secure if either enrolment verification or 3-D Secure authentication failed with an error.	V

Structure of the ThreeDS Information field

The ThreeDS information field is comma delimited list with the following fields

warning

This field is deprecated with the introduction of EMV 3-D Secure and the Emv3DS response field.

For compatibility, 3-D Secure v1 compliant codes will always be returned for Enrolled and Authenticated fields when 3-D Secure v2 is used.

No	Field Name and Contents	Req'd	Size	Type
1	Enrolled	M	1	A
2	Authenticated	M	1	A
3	ECI	M	2	N
4	CAVV	M	32 max.	A
5	Transaction Identifier	M	20	N

Note: The number of fields in these structures are variable. Please ensure any field validation is tolerant.

Structure of the Emv3DS Information field

The Emv3DS information field is comma delimited list with the following fields

No	Field Name and Contents	Req'd	Size	Type
1	EMV 3-D Secure Status	M	1	A
2	3-D Secure Version used. e.g. 2.2.0	M	10 max.	A
3	ECI	M	2	A
4	CAVV	M	32 max.	A
5	Directory Server Transaction Identifier	M	36	Guid
6	Monek 3-D Secure Transaction Reference	M	36	Guid

Note: The number of fields in these structures are variable. Please ensure any field validation is tolerant.

Receipt Information

Field Name	Description	Size
ReceiptInformation	This returns all the information that a merchant needs to produce a customer receipt. Please contact Monek to enable this facility. Returned if transaction request field EchoReceiptInformation was set to YES. Not returned if TransactDirect ResponseCode = 30	387 max.

Structure of the Receipt Information field

No	Field Name and Contents	Req'd	Size	Type
1	Bank Merchant Number	M	15 max.	A
2	Unit Separator US – ASCII character code 31	M	1
3	Card Type Description	M	50 max.	A
4	Unit Separator US	M	1
5	Merchant Name	M	50 max.	A
6	Unit Separator US	M	1
7	Merchant Location	M	50 max.	A
8	Unit Separator US	M	1
9	Date – "YYMMDD"	M	6	N
10	Unit Separator US	M	1
11	Time – "HHMM"	M	4	N
12	Unit Separator US	M	1
13	Transaction Type	M	20 max.	A
14	Unit Separator US	M	1
15	Card Number – First 4 and last 4 digits	M	20 max.	N
16	Unit Separator US	M	1
17	Start Date – "YYMM"	O	0 or 4	N
18	Unit Separator US	M	1
19	Expiry Date – "YYMM"	M	4	N
20	Unit Separator US	M	1
21	Issue Number (discontinued)	O	n/a	N
22	Unit Separator US	M	1
23	Card Details Entry Method	M	20 max.	A
24	Unit Separator US	M	1
25	Terminal Identifier	M	8	N
26	Unit Separator US	M	1
27	Message Number	M	4	N
28	Unit Separator US	M	1
29	Response Message Text	M	80 max.	A
30	Unit Separator US	M	1
31	Transaction Amount – minor currency units	M	11 max.	N
32	Unit Separator US	M	1
33	Cashback Amount - minor currency units	O	11 max.	N
34	Unit Separator US	M	1
35	Gratuity Amount - minor currency units	O	11 max.	N

M = Mandatory, O = Optional, V = Variable Length, A = Alpha-Numeric, N = Numeric