Hosted Payment Form: Fields Reference
Hosted Payment Form fields are used to collect card details from the payer - the form when submitted is posted directly to the Hosted Payment Form 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 Form 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://tyro.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.
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.
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 Form
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.
Data is a string that consists of the characters 0-9, ' ' (space), '-' (hyphen).
Mask characters ('x
', 'X
', and '*
') are valid only on resubmission.
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 Form 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.
Data is a string that consist of the characters 0-9.
Mask characters ('x
', 'X
', and '*
') are valid only on resubmission.
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.
Data is a number between 1 and 12 represented as a string.
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.
Data is a string that consist of the characters 0-9. The value must be between 2000 and 2099 or 00 and 99.
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.
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)
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.
Text
default value
Submitted Payment Details
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.
Text
default value
Click here to continue
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+.
gatewayCardScheme
Enumeration
=
The card scheme determined from the supplied card.
Existence
Always Returned
Value must be a member of the following list. The values are case sensitive.
JCB
JCB (Japan Credit Bureau)
UATP
UATP (Universal Air Travel Plan)
OTHER
The scheme of the card used in the transaction could not be identified.
gatewayCardBrand
Enumeration
=
The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see gatewayCardLocalBrand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Existence
Always Returned
Value must be a member of the following list. The values are case sensitive.
JCB
JCB (Japan Credit Bureau)
UATP
UATP (Universal Air Travel Plan)
LOCAL_BRAND_ONLY
The card does not have a global brand.
UNKNOWN
The brand of the card used in the transaction could not be identified.
gatewayCardLocalBrand
Enumeration
=
The brand name used to describe a card that is recognized and accepted within its country/region of origin. The card may also be co-branded with a brand name that is recognized and accepted globally (see gatewayCardBrand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Value must be a member of the following list. The values are case sensitive.
BANAMEX_COSTCO
Banamex Costco (Mexico)
CARTE_BANCAIRE
Carte Bancaire (France)
FARMERS
Farmers Card (New Zealand)
Q_CARD
Q Card (New Zealand)
TRUE_REWARDS
True Rewards (New Zealand)
gatewayCardFundingMethod
Enumeration
=
The method used by the payer to provide the funds for the payment.
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Existence
Always Provided
Value must be a member of the following list. The values are case sensitive.
CHARGE
The payer has a line of credit with the issuer which must be paid off monthly.
CREDIT
The payer has a revolving line of credit with the issuer.
DEBIT
Funds are immediately debited from the payer's account with the issuer.
UNKNOWN
The account funding method could not be determined.
URL Parameters
The session identifier returned by the response from the Web Services Integration
Create Session operation.
This value must be appended to the Hosted Payment Form Service URL as the action on your form.
e.g.
action="https://tyro.gateway.mastercard.com/form/SESSION000112345678901234567890"
Data must be of the format: "SESSION" followed by 24 digits (0-9),
e.g. SESSION000112345678901234567890