Masterpass

Masterpass is a digital wallet that enables users to securely store card information. PayU's version of Masterpass is currently aimed only for users with a Polish phone number.

Masterpass is accessible through PayU in two distinct ways:

1. As a payment method integrated into the PayU payment page.
2. Through direct integration with Masterpass, which also offers a white label solution.

Using PayU Payment Page

In the standard integration approach, Masterpass is accessible directly from the PayU payment page, and it doesn't necessitate any supplementary configuration. It seamlessly functions as an additional payment option for the payer.

The Masterpass button is showcased through the PayU card payment form. It becomes visible once the Masterpass payment method is enabled. This list of enabled payment methods can be located in the management panel under "Online payments" > "My shops" > "POS". When the button is clicked, it triggers a screen where the payer can log into their wallet and select a pre-saved card. The card information is then transmitted to PayU and utilized for initiating the payment process.

Further proccesing of the request is carried out as standard and is described in Payment Flows section of this documentation.

The transaction will be settled similar to a typical card payment. To confirm if the card data was sourced from Masterpass, it's necessary to inspect the value of the paymentFlow parameter. This value can be obtained through the Transaction Data Retrieve service.

You can also invoke Masterpass screen directly - then the payer doesn't need to click on the Masterpass payment method button on the PayU payment page. This method is described in point Direct Invocation section.

White Label Solution

An alternative approach is to construct your own checkout page and activate Masterpass within it. By integrating with Masterpass by Mastercard for digital wallet management and using PayU's REST API for order creation, you can tailor the purchasing process on your website according to your preferences.

For more information about the service, visit the Masterpass official website.

You may want to consider

Orders with Masterpass payment method are settled as standard, so it is worth considering integrating a transaction data retrieval. Such integration will help to distinguish between cards entered via the PayU form and cards selected by the payer directly from the Masterpass by Mastercard wallet.

---

Transparent integration is not available for testing on the sandbox environment.

Direct Invocation

As mentioned earlier, Masterpass is accessible directly from the PayU payment page, requiring no adjustments to the integration. However, if you wish to redirect the payer directly to the PayU payment page with Masterpass pre-selected as the payment method, you must specify the payment method in the order request.

Order Request Extension for Direct Invocation of Masterpass

{
    "payMethods": {
        "payMethod": {
            "type": "PBL",
            "value": "ma"
        }
    }
}

White Label Solution for Masterpass

This integration form requires additional configuration by the PayU.

To facilitate Masterpass support on your checkout page, you must extend standard order request with extOrderId field and payMethods section.

Fields Required for Masterpass Payment from Your Checkout Page

"extOrderId": "<transaction id used in Masterpass by Mastercard>",
"payMethods": {
    "payMethod" : {
        "type": "PBL",
        "value": "ma",
        "authorizationCode": "<masterpassToken>"
    }
}

authorizationCode field value is encrypted with base64 and contains masterpassToken of the following structure:

masterpassToken Value Before base64 Encryption

{
    "cardId": "<cardId from the Masterpass by Mastercard wallet>",
    "cardIssuingTokens": "<issue token for card transaction returend by the Masterpass by Mastercard service>",
    "merchantName": "<your name in Masterpass by Mastercard service>"
}

Further proccesing of the request is carried out as standard and is described in Payment Flows section.

Creating an Order for White Label Solution

To facilitate the processing of an order on your checkout page while utilizing Masterpass as the chosen payment method, you need to first retrieve two essential pieces of information:

• cardIssuingTokens for given cardId from Masterpass by Mastercard system,
• accessToken with grant_type set to the client_credentials , to authenticate the request.

Subsequently, you can proceed to create an order within the PayU system for the Masterpass by Mastercard transaction, passing the relevant transaction details within the extOrderId field.

curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H 'Authorization: Bearer e5e55002-c534-4d43-b9a3-affb84b0386d' \
-H 'Content-Type: application/json' \
-d '{
    "currencyCode": "PLN",
    "totalAmount": 2099,
    "description": "TEST_4cd6ce05-4f4e-4edb-8631-d7dc88e761db",
    "notifyUrl": "https://notify.pl",
    "customerIp": "193.17.41.0",
    "merchantPosId": "2334121",
    "extOrderId": "PayU-UAT-1871fdaa-0ada-4455-84ae-b8a823de2c9d",
    "products": [
        {
            "name": "Wireless Mouse for Laptop",
            "unitPrice": "2099",
            "quantity": "1"
        }
    ],
    "payMethods": {
        "payMethod": {
            "type": "PBL",
            "value": "ma",
            "authorizationCode": "eyJjYXJkSWQiOiI1NTY1NyIsImNhcmRJc3N1aW5nVG9rZW5zIjoiZXlKaGJHY2lPaUpJVXpVeE1pSjkuZXlKcWRHa2lPaUk0TkdReE5tRmxaQzB5TUdJMkxUUm1ObUV0T0RFM01DMWpOVEJsTXpnMU16Y3pNRFVpTENKemRXSWlPaUk0TkdReE5tRmxaQzB5TUdJMkxUUm1ObUV0T0RFM01DMWpOVEJsTXpnMU16Y3pNRFVpTENKcFlYUWlPakUxTmpnd01qVXpNVGdzSW1WNGNDSTZNVFUyT0RBeU5qSXhPQ3dpYVhOUGJtVlVhVzFsUTJGeVpGUnZhMlZ1SWpwMGNuVmxmUS5zcS1sQnZHNmEzZmtfNDJ1VWpnczg3cHcwTGtpeEdHVDgtVXpwckZudWtQRVMwSjc2SHhSc1A4d2Z2djMwOExTS2FxeVMyQUZscmpFOFdHYVRqM3pnUSIsIm1lcmNoYW50TmFtZSI6Ik11bHRpS2lubyJ9"
        }
    }
}'

Where authorizationCode field before base64 encryption looked as follows:

authorizationCode Field Value Before base64 Encryption

{
    "cardId": "55332",
    "cardIssuingTokens": "eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiI4NGQxNmFlZC0yMGI2LTRmNmEtODE3MC1jNTBlMzg1MzczMDUiLCJzdWIiOiI4NGQxNmFlZC0yMGI2LTRmNmEtODE3MC1jNTBlMzg1MzczMDUiLCJpYXQiOjE1NjgwMjUzMTgsImV4cCI6MTU2ODAyNjIxOCwiaXNPbmVUaW1lQ2FyZFRva2VuIjp0cnVlfQ.sq-lBvG6a3fk_42uUjgs87pw0LkixGGT8-UzprFnukPES0J76HxRsP8wfvv308LSKaqyS2AFlrjE8WGaTj3zgQ",
    "merchantName": "NazwaMerchanta"
}

After sending a request you will receive response depending if the transaction was successful.

Error Codes Specific for White Label Masterpass Solution

Error Codes for White Label Masterpass Solution

HTTP Status	ErrorCode	CodeLiteral	Descritpion
500	ERROR_INTERNAL	SERVICE_TEMPORARY_UNAVAILABLE	Masterpass service is temporary unavailable or there is a problem with card data tokenization.
400	ERROR_VALUE_INVALID	MASTERPASS_INVALID_DATA	Incorrect data related to Masterpass system: incorrect card data, incorrect cardId, incorrect cardIssuingTokens, extOrderId value has been used already.
400	ERROR_VALUE_INVALID	INVALID_CURRENCY_CODE	Currency is not supported.
400	ERROR_AUTHORIZATION_CODE	AUTH_CODE_INVALID	Incorrect authorizationCode.