Direct Implementation
Masterpass transactions require you to display the Masterpass Pay Wallet to your Customer as part of the transaction flow. The transaction must be done in two stages, with the Wallet being displayed between the stages. They can optionally also be done in three stages, allowing you to display an order confirmation after the Wallet and before authorising the transaction. You can change the amount at this stage to allow for shipping costs when you know the confirmed delivery address the Customer selected from the Wallet.
To customise the Masterpass Wallet experience, you may send various options in the masterPassCheckoutOptions field in your initial request.
Additional information available from the Masterpass Wallet will be made available in the masterPassCheckoutDetails response field.
The contents of the masterPassCheckoutOptions, masterPassCheckoutDetails fields are formatted using the record format, the masterPassCheckoutOptions field also supports being provided using the serialised record format.
Initial Request (Checkout Preparation)
To request that a transaction be processed using details selected from the Customer’s Masterpass Wallet, the request must contain a paymentMethod of ‘masterpass’ and a masterPassCallbackURL containing the URL of a page on your server to return to when the Wallet is closed. In addition, you must send masterPassCheckoutOptions to specify that Masterpass v7 with Click to Pay is used (refer to Wallet Options - Direct and Hosted section). When the Gateway receives these two fields, assuming there are no other errors with the request, it will attempt to find a suitable Masterpass enabled Merchant Account in the current account mapping group (refer to the Merchant Account Routing section).
If the Gateway is unable to find a suitable account, then the transaction will be aborted and it will respond with a responseCode of 65569 (MASTERPASS_NOT_SUPPORTED).
Otherwise, the Gateway will respond with a responseCode of 65572 (MASTERPASS_CHECKOUT REQUIRED) and the response will include a masterPassCheckoutURL field containing the URL required to load the Masterpass Wallet and a masterPassCheckoutOptions containing any data required to be sent to the Wallet. The response will also contain a unique masterPassData field that must be echoed back in the continuation requests. No transaction will have been created by the Gateway at this stage and this request will not appear in the Merchant Management System.
At this point your server must redirect the Customer’s browser to the Masterpass Wallet at the provided masterPassCheckoutURL. Alternatively, the masterPassCheckoutURL can be used in conjunction with the Masterpass JavaScript code to implement a lightbox style Wallet that allows the Merchants website to remain visible in the background. Further details on how to use the Masterpass JavaScript SDK can be obtained from Mastercard.
Continuation Request (Checkout Details and Authorise)
On completion of the Masterpass Wallet, it will redirect the Customer’s browser to the masterPassCallbackURL provided, including an OAuth token, OAuth verifier and status URL parameters. If the checkout was successful, the status will be ‘success’. Alternatively, if the checkout was cancelled the status will be ‘cancel’.
These URL parameters should be sent to the Gateway in the masterPassToken, masterPassVerifier, masterPassStatus fields of a new request. The new request must contain the masterPassData received in the initial response. This new request will retrieve the Customer’s chosen payment and delivery details from Masterpass and then send the transaction to the Acquirer for authorisation, returning the result similarly to a normal card-based authorisation transaction.
If the continuation request contains any details that would normally be read from the Masterpass y Wallet, then these will take precedence and overwrite the Wallet details. Note: in such cases, the transaction will no longer class as being a Masterpass transaction and will be treated by the Acquirers as if the Wallet was not used.
If the chosen details cannot be retrieved or if the masterPassStatus field indicated that the Wallet was cancelled, then the Gateway will return a responseCode of 65570 (MASTERPASS_CHECKOUT_FAILURE).
Separate Checkout Details and Authorisation Requests
You can choose to obtain the Wallet details before sending the transaction for authorisation by sending the masterPassOnly field in the above continuation request. If this field is sent with a value of ‘Y’, then the Gateway will load the Wallet details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges appropriate to the received delivery address. You should then send a new request, containing the masterPassData received, to continue the transaction and authorise it.
If the continuation request contains any details that would normally be read from the Masterpass Wallet, then these will be ignored, and the Wallet details returned. Note: this is different from usual processing, where incoming fields usually take precedence.
The outcome of this request will depend on the value of the masterPassStatus field and the ability to communicate with Masterpass. On success, the Gateway will return a responseCode of 65571 (MASTERPASS_CHECKOUT_SUCCESS) and response will include the chosen payment card and address details. If the Wallet was cancelled or if the chosen details cannot be retrieved, then the Gateway will return a responseCode of 65570 (MASTERPASS_CHECKOUT_FAILURE).
This stage can be repeated multiple times by including the masterPassOnly field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the masterPassOnly field or it must not have a value of ‘Y’.
\