Masterpass

1 Masterpass by Mastercard

Masterpass is a digital wallet in which the user may store card data and other information like shipping address.

The wallet is available through PayU:

  • as a payment method on the PayU payment page
  • as a lightbox directly invocated by the merchant
  • 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 lightbox via which payer logs in to his 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 lightbox 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.

2 Integration

2.1 Direct lightbox invocation

In case of direct redirection to the PayU payment page with lightbox already invoked, 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.

2.2 Masterpass transparent

This integration form requires additional configuration by the PayU and is available only in REST API.

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.

3 Order example with Masterpass transparent

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"
                            }
                            
                        

4 Error codes in Mastercard transparent

HTTP Status ErrorCode CodeLiteral Description
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.

5 Sandbox

Direct lightbox invocation and transparent integration are not available for testing on the sandbox.