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.
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://evopaymentsmexico.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
gatewayCardSecurityCodeDigits 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
gatewayRedirectDisplayBackgroundColorAlphanumeric 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)"
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.
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+.
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=
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
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)
MAESTRO
Maestro
MASTERCARD
Mastercard
VISA
Visa
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.
Existence
Conditional
Validation Rules
Value must be a member of the following list. The values are case sensitive.
BANAMEX_COSTCO
Banamex Costco (Mexico)
CARNET
Carnet (Mexico)
CARTE_BANCAIRE
Carte Bancaire (France)
ELO
Elo (Brazil)
FARMERS
Farmers Card (New Zealand)
LASER
Laser (Ireland)
Q_CARD
Q Card (New Zealand)
SORIANA
Soriana (Mexico)
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
Validation Rules
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.
The session identifier returned by the response from the APICreate Session operation.
This value must be appended to the Hosted Payment Session Service URL as the action on your form.
e.g. action="https://evopaymentsmexico.gateway.mastercard.com/form/SESSION000112345678901234567890"
Type
Alphanumeric
Data must be of the format: "SESSION" followed by 24 digits (0-9),
e.g. SESSION000112345678901234567890