Masterpass

The wallet is available through PayU:

• as a payment method on the PayU payment page
• in direct integration with Masterpass („Masterpass transparent”)

Masterpass is available from the PayU payment page and it does not require any changes in integration - it is simply another payment method available for payer.

Masterpass button is displayed via PayU card payment form. It becomes visible after enabling Masterpass payment method (List of enabled payment methods can be found in PayU panel - Online payments/My shops/POS).

Button invokes screen where the payer logs in to the wallet and chooses previously saved card. Card data is passed to PayU and used for creating payment.

Further proccesing of the request is carried out as standard and is described in REST API and Classic API documentation.

Transaction will be settled as a standard card payment. To verify if card data originated from Masterpass, you need to check payment flow parameter value obtained through: payment/get (Classic API) and Transaction Data Retrieve (REST API).

You can invoke Masterpass screen directly - then there is no need for payer to click on Masterpass payment method button on the PayU payment page. Description of this method can be found in point 2.1.

Another method is to enable Masterpass transparent service which uses Masterpass digital wallet. Merchant integrates with "Masterpass by Mastercard" in digital wallet handling matters and with PayU (via REST API) in the scope of order creation. This way, merchant can freely shape purchasing process on his website.

More information about testing this service can be found inSandbox section.

More information about service can be found on the Masterpass official site.

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

In case of direct redirection to the PayU payment page with Masterpass requires method to be specified in the order request.

In case of REST API integration, the following object must be added to the OrderCreateRequest request.

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

For Classic API you need to specify pay_type field value as "ma" in NewPayment form.

OrderCreateRequest with extOrderId field and payMethods section are required for creating order request with Masterpass transparent:

                
                "extOrderId": "<transaction id wykorzystane w ramach usługi 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:

                
                {
                    "cardId" : "<cardId z portfela Masterpass by Mastercard>",
                    "cardIssuingTokens": "<issue token dla transakcji kartowej zwrócony przez usługę Masterpass by Mastercard>,
                    "merchantName" : "<nazwa merchanta  w usłudze Masterpass by Mastercard>”
                }
                
            

Further proccesing of the request is carried out as standard and is described in REST API documentation.

To process standard order in Masterpass transparent, Merchant:

1. Retrieves cardIssuingTokens for given cardId from Masterpass by Mastercard system.

2. Authenticates order by retrieving accessToken from the PayU.

   
   
   

   Request:

                           
                           curl -X POST https://secure.snd.payu.com/pl/standard/oauth/authorize \
                           -d 'client_id=>clientId<&client_secret=>clientSecret<&grant_type=client_credentials'
                           
                       

3. W odpowiedzi dostaje accessToken:

   
   
   

   Response:

                           
                           {
                               "access_token": "e5e55002-c534-4d43-b9a3-affb84b0386d",
                               "token_type": "bearer",
                               "expires_in": 43199,
                               "grant_type": "client_credentials"
                           }
                           
                       

4. Creates order in PayU system for Masterpass by Mastercard transaction, passed in extOrderId field.

   
   
   

   Request:

                           
                           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 authorization code field before base64 encryption looked as follows:

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

5. Receives response depending if the transaction was successful:

   
   
   

   Response:

                           
                           {
                               "status": {
                                   "statusCode": "SUCCESS",
                                   "statusDesc": "Request successful"
                               },
                               "orderId": "BB97J7Z2DT190909GUEST000P01"
                           }
                           
                       

Transparent integration is not available for testing on the sandbox.