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 ¹

Description

Any password used to secure this account. Refer to section 1.8.1 for details.

Field Name

signature

Mandatory?

Yes ²

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 ³

Description

The amount of the transaction.

Field Name

type

Mandatory?

Yes ³

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 ³

Description

Merchant’s location.

Field Name

currencyCode

Mandatory?

Yes ³

Description

Transaction currency.

Field Name

paymentMethod

Mandatory?

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 ³

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 ³

Description

Free format text field to store order details, reference numbers, etc. for the Merchant’s record.

Field Name

orderDate

Mandatory?

Description

Optional date to record with the transaction.

Field Name

captureDelay

Mandatory?

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 ⁵

Description

Reference to a previous transaction. Refer to appendix A-16 for details.

Field Name

redirectURL

Mandatory?

No ⁶

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 ⁶

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 ⁷

Description

IP address of client making the transaction. This should be provided where possible to aid fraud prevention.

Field Name

rtAgreementType

Mandatory?

No ⁸

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.