Hosted Payment Session: Fields Reference

Hosted Payment Session fields are used to collect card details from the payer - the form when submitted is posted directly to the Hosted Payment Session Service via HTTPS POST. This is a pre-requisite for performing payment or storage transactions with a session.

Submitting the payment page does not initiate a payment transaction.

Before submitting the payment page, you must create a session using the Create Session operation.

Create Session API Reference[REST][NVP]

This operation returns a session identifier, which you must embed in the Hosted Payment Session Service URL when submitting the payment page.

The form response together with the request parameters are returned in the validated form to you. This allows you to perform an operation using the session identifier in place of card details. For more information, see Perform an Operation Using the Session.

HTTPS Method POST
Form URL https://na.gateway.mastercard.com/form/<formSessionIdentifier>
Authentication Verification of the session using the session identifier.

Request Parameters

If the request parameter value is erroneous, then an error is returned in the field value (see Error Handling) or the payer (or integration tester) is redirected to a page detailing the error.
gatewayReturnURL  URL = (COMPULSORY)
The URL to which you want to redirect the payer after submitting the card details. If the URL is missing or invalid, then a page will be displayed in the browser detailing the error. This field must be tagged as hidden (<input type="hidden"/>) in the payment form.
Existence
COMPULSORY
Validation Rules
Must be a fully qualified URL starting with HTTP:// or HTTPS://, preferably the latter as it's recommended that the browser is returned to an SSL secured page. This will prevent the browser pop-up indicating that the payer is being returned to an insecure site.
minimum length
8
maximum length
2000
gatewayCardNumber Digits, space, hyphen and mask characters = (OPTIONAL)
Credit card number of the payer as printed on the card.
  • Masking: When returned in the form response, the card number will be masked according to merchant's masking settings or 6.4, whichever is more restrictive (e.g. 000000xxxxxx0000). If the payer enters any masked characters on the initial submit, the value will be rejected as invalid.
  • Stripping: Any spaces or hyphens found in payer's input will be removed from the response.
  • Truncation: If the input exceeds the maximum length, the response will be truncated to the maximum length and an error will be indicated on the response field.
  • Errors: If the field value is invalid, you can redisplay the form (with masked card number) indicating that the field is in error.
  • Resubmitting: If the form is resubmitted with the response values and the masked card number is submitted unchanged, Hosted Payment Session will accept this as the originally entered card number.
  • Mask Characters: The default mask character is 'x'. You may replace the mask character with 'X' or '*' on resubmission and it will be recognized as valid masking.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, ' ' (space), '-' (hyphen).
Mask characters ('x', 'X', and '*') are valid only on resubmission.
minimum length
1
maximum length
30
gatewayCardSecurityCode Digits and mask characters = (OPTIONAL)
Card security code of the payer, as printed on the back or front of the card.
  • Masking: When returned in the form response, the card security code will be fully masked (e.g. xxxx). If the payer enters any masked characters on the initial submit, the value will be rejected as invalid.
  • Truncation: If the input exceeds the maximum length, the response will be truncated to the maximum length and an error will be indicated on the response field.
  • Errors: If the field value is invalid, you can redisplay the form (with masked card security code) indicating that the field is in error.
  • Resubmitting: If the form is resubmitted with the response values and the masked CSC is submitted unchanged, Hosted Payment Session will accept this as the originally entered CSC.
  • Mask Characters: The default mask character is 'x'. You may replace the mask character with 'X' or '*' on resubmission and it will be recognised as valid masking. Any masked characters will be considered invalid on initial submit.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consist of the characters 0-9.
Mask characters ('x', 'X', and '*') are valid only on resubmission.
minimum length
0
maximum length
10
gatewayCardExpiryDateMonth  Digits = (COMPULSORY)
Expiry month, as shown on the card. Months are numbered JAN=1, through to December=12. If the field value is invalid, you can redisplay the form indicating that this field is in error.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
minimum length
1
maximum length
2
gatewayCardExpiryDateYear  Digits = (COMPULSORY)
Expiry year, as shown on the card. The Common Era year is 2000 plus this value. If the field value is invalid, you can redisplay the form indicating that the field is in error.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consist of the characters 0-9. The value must be between 2000 and 2099 or 00 and 99.
minimum length
2
maximum length
4
gatewayRedirectDisplayBackgroundColor Alphanumeric and other characters = (OPTIONAL)
Background colour of the page rendered in the payer's browser before the form response is posted back to the merchant integration. It's recommended that the color you specify blends well with the color scheme of your website to provide a seamless experience to the payer. This field must be tagged as hidden (<input type="hidden"/>) in the payment form.
Existence
OPTIONAL
Validation Rules
The following CSS representations are considered valid.
Invalid values will be removed from input and the default value used.
  • Hexadecimal: The format of an RGB value in hexadecimal notation is a '#' immediately followed by either three or six hexadecimal characters. E.g. #F00, #FF0000
  • Color names: Color names such as "red", "white" etc
  • RGB value: "rgb" followed by 3 numerical values in parentheses. e.g. "rgb(255,0,0)"
default value
#000000 (white)
minimum length
3
maximum length
30
gatewayRedirectDisplayTitle Alphanumeric = (OPTIONAL)
Title of the page rendered in the payer's browser before the form response is posted back to the merchant integration. It's recommended that the title you specify provides a feeling of continuity to the payer thus enhancing the shopping experience. This field must be tagged as hidden (<input type="hidden"/>) in the payment form.
Existence
OPTIONAL
Validation Rules
Text
default value
Submitted Payment Details
minimum length
0
maximum length
255
gatewayRedirectDisplayContinueButtonText Alphanumeric = (OPTIONAL)
Title of the button that will be rendered in the payer's browser if JavaScript is disabled. It's recommended that the text you specify for the button blends well with the shopping experience for the payer. Clicking the button will post the form response back to the merchant integration. This field must be tagged as hidden (<input type="hidden"/>) in the payment form.
Existence
OPTIONAL
Validation Rules
Text
default value
Click here to continue
minimum length
0
maximum length
255

Response Parameters

All parameters submitted in the request will be returned in the response. In addition, the following parameters will be returned.

The fields gatewayCardBrand, gatewayCardLocalBrand, and gatewayCardFundingMethod are returned only if you use the Create Session request in version 15+.
gatewayFormResponse  Enumeration = (Always Returned)
Indicates the overall result of the form submission.
Existence
Always Returned
Validation Rules
A general response code in the format R~D, where R is a single character code indicating the result, and D is an English description. This value must be checked before processing other fields in the form response.
Value must be a member of the following list. The values are case sensitive.
0~OK
Indicates the form is valid — returned when no form errors are found.
2~Session identifier invalid or closed for updates
Indicates invalid session — returned when session is missing, expired, closed, or invalid.
3~Field Errors
Indicates field errors — returned if any form field fails validation.
4~System Error
Indicates system error — returned if a Payment Gateway error or other failure occurs.
gatewayCardScheme  Enumeration =
The card scheme determined from the supplied card.
Existence
Always Returned
Validation Rules
Value must be a member of the following list. The values are case sensitive.
AMEX
American Express
DINERS_CLUB
Diners Club
DISCOVER
Discover
JCB
JCB (Japan Credit Bureau)
MASTERCARD
Mastercard
UATP
UATP (Universal Air Travel Plan)
VISA
Visa
OTHER
The scheme of the card used in the transaction could not be identified.
gatewayCardBrand  Enumeration =