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:
- As a payment method integrated into the PayU payment page.
- 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.
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.
{
"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.
"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:
{
"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 givencardId
from Masterpass by Mastercard system,accessToken
withgrant_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:
{
"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
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:
|
400 | ERROR_VALUE_INVALID | INVALID_CURRENCY_CODE | Currency is not supported. |
400 | ERROR_AUTHORIZATION_CODE | AUTH_CODE_INVALID | Incorrect authorizationCode . |