Skip to main content

Request Fields

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.

Field NameMandatory?Description
merchantIDYesYour Gateway Merchant Account ID.
merchantPwdNo[1]

Any password used to secure this account.

Refer to the Password Authentication section for details.

signatureYes[2]

Any hash used to sign this request.

Refer to the Message Signing section for details.

actionYes

The action requested.

Refer to the Supported Actions section for details.

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.

amountYes[3]The amount of the transaction.
typeYes[3]

The type of transaction.

Refer to the Transaction Types section for details.

Possible values are:

1 – E-commerce (ECOM)

2 – Mail Order/Telephone Order (MOTO) or Card Not Present (CNP)

9 – Continuous Authority (CA)

countryCodeYes[3]The country where the transaction takes place.
currencyCodeYes[3]Transaction currency.
paymentMethodNoThe payment method required. For card payments either omit this field or use the value card.
cardNumberYes[3,4]The primary account number (PAN) as printed on the front of the payment card. Digits and spaces only.
cardExpiryMonthYes[3,4]Payment card’s expiry month from 1 to 12.
cardExpiryYearYes[3,4]Payment card’s expiry year from 00 to 99.
cardExpiryDateNo[3,4]Payment card’s expiry date in MMYY format as an alternative to sending a separate cardExpiryMonth and cardExpiryYear.
cardCVVYes[3,4]Payment card’s security number. The 3-digit number printed on the signature strip.
transactionUniqueNo[3]You can supply a unique identifier for this transaction. This is an added security feature to combat transaction spoofing.
orderRefNo[3]Free format text field to store order details, reference numbers, etc for the Merchant’s records.
orderDateNoOptional date to record with the transaction.
captureDelayNo

Number of days to wait between authorisation of a payment and subsequent settlement.

Refer to the Duplicate Transaction Checking section for details.

xrefNo[5]

Reference to a previous transaction.

Refer to the Payment Tokenisation section for details.

redirectURLNo[6]

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 the Redirect URL section for details.

callbackURLNo[6]

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 the Callback URL section for details.

deviceIpAddressNo[7]IP address of client making the transaction using dotted decimal notation (eg. 1.12.123.255) or an IP v6 address using colon hexadecimal notation (eg 2011:0db8:85a3:0101: 0101:8a2e:0370:7334). This should be provided where possible to aid fraud prevention.
rtAgreementTypeNo[8]

Agreement between Merchant and Cardholder for the storage of, or subsequent use of, payment details.

Refer to the Credentials on File section further details.

Footnotes

  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.