Skip to main content

Request Fields

Initial Request (Hosted and Direct Integrations)​

These fields should be sent in addition to the Basic Request Fields excluding any card details.

Field NameMandatory?Description
paymentMethodYes[1]Must contain the value ‘masterpass’ in lower case letters only.
masterPassCallbackURLYes[2]URL on Merchant’s server to return to when the Masterpass Wallet is closed.
masterPassCheckoutOptionsNoRecord containing options used to customise the Masterpass Wallet. Refer to the Checkout Options - Hosted and Direct Integrations section.
masterPassCheckoutIDNoMerchant’s unique checkout identifier as provided by Masterpass.

Continuation Request (Direct Integration)​

Field NameMandatory?Description
masterPassDataYesUnique reference returned in the initial response.
masterPassStatusYes[3]The Wallet status returned to the Merchant.
masterPassTokenYes[3]The OAuth token returned to the Merchant.
masterPassVerifierYes[3]The OAuth verifier returned to the Merchant.
masterPassResourceURLYes[3]An optional resource URL (Masterpass v6 only).
masterPassOnlyNoPass Y to complete the processing as far as the next Wallet stage and then return with the loaded Wallet details.

Wallet Options (Hosted and Direct Integrations)​

The following options may be set in the masterPassCheckoutOptions field to customise the Masterpass Wallet. The options must be formatted using the record or serialised record formats.

Field NameDescription
version

Masterpass version required. Must be set to v7.

Possible values are:

v6 – use version 6 of the Masterpass API (default / deprecated).

v7 – use version 7 of the Masterpass API (required).

suppressShippingAddress

Suppress the requirement for the Customer to select a shipping address as well as payment card details. If passed as 'true' then no attempt will be made to return the delivery address fields. Any delivery address fields passed in the transaction will be echoed back unaltered.

Possible values are:

false – shipping address must be selected.

true – shipping address need not be selected.

merchantCheckoutIdMerchant’s unique checkout identifier as provided by Masterpass. Either as passed in the initial request or as configured on the Gateway for your account.
clickToPayMust be set to Y if the merchantCheckoutId is included in the options.
allowedCardTypesList of Masterpass card types to allow selection from within the Wallet. if not provided in the request it will be determined from the card types configured for your Merchant Account and returned in the response.
warning

For backward compatibility with older integrations the Gateway will default to the decommissioned Masterpass v6 without support for Click to Pay.

To enable the correct support for Click to Pay the masterPassCheckoutOptions field must be sent requesting that version v7 be used with clickToPay set to Y.

Footnotes

  1. Optional for Hosted Integration.
  2. Not required for Hosted Integration.
  3. These fields should be initialised with values received by your website when the wallet redirects to your masterPassCallbackURL URL. If the checkout was cancelled, then only the masterPassStatus field need be sent to the Gateway.