Masterpass

1 Masterpass by Mastercard

Masterpass by Mastercard to cyfrowy portfel w którym można zapisać dane karty płatniczej oraz inne dane, takie jak np. adres wysyłki.

Portfel dostępny jest poprzez PayU:

  • Jako metoda płatności na stronie płatniczej PayU.
  • Jako lightbox wywołany bezpośrednio przez merchanta.
  • W bezpośredniej integracji z Mastercard („Masterpass transparent”).

Masterpass jest dostępny z poziomu strony płatniczej PayU i nie wymaga żadnych zmian w integracji z PayU - jest po prostu kolejną metodą płatności dostępną dla płatnika.

Przycisk Masterpass jest wyświetlany za pośrednictwem formularza płatności kartą, serwowanego przez PayU. Przycisk jest widoczny kiedy metoda płatności Masterpass jest włączona (listę włączonych metod można znaleźć w panelu PayU, w zakładce Płatności Elektroniczne/Moje sklepy/Punkty płatności).

Przycisk wywołuje okno (lightbox), w którym płacący loguje się do portfela i wybiera zapisaną kartę. Dane karty są następnie w bezpieczny sposób przekazywane do PayU i użyte do przeprowadzenia płatności.

Dalsze przetwarzanie płatności podlega standardowemu procesowi, opisanemu w dokumentacji REST API i Classic API.

Płatność zostanie rozliczona jak standardowa płatność kartą, dlatego aby sprawdzić, czy dane karty zostały pobrane z Masterpass, należy sprawdzić wartość parametru "payment flow", dostępną poprzez payment/get (Classic API) i Transaction Data Retrieve (REST API).

Merchant może też wywołać lightbox bezpośrednio – wówczas nie ma konieczności klikania przez płacącego metody płatności Masterpass na stronie płatniczej PayU. Opis tej metody znajduje sie poniżej w punkcie 2.1.

Ostatnim sposobem jest włączenie usługi Masterpass transparent, wykorzystującej cyfrowy portfel Masterpass. Merchant samodzielnie integruje się z usługą „Masterpass by Mastercard” w zakresie obsługi portfela elektronicznego, a z PayU(za pomocą REST API) w zakresie zlecania zamówienia klienta. Dzięki temu merchant może dowolnie kształtować proces zakupowy na swojej stronie.

Informacje dotyczące testowania usługi zawarte zostały w sekcji Sandbox.

Więcej informacji można znaleźć na oficjalnej stronie Masterpass.

Ponieważ zamówienia z metodą płatności Masterpass będą rozliczane tak jak standardowe płatności kartą, warto rozważyć integrację usługi pobrania danych transakcji. Taka integracja pomoże rozróżnić karty wpisane przez formularz PayU od kart wybranych przez płacącego bezpośrednio z portfela "Masterpass by Mastercard".

2 Integracja

2.1 Bezpośrednie wywołanie lightboxa

Bezpośrednie przekierowanie na ekran płatności PayU z wywołanym już lightboxem Masterpass wymaga podania tej metody w żądaniu tworzącym płatność.

W przypadku integracji z REST API poniższy obiekt musi zostać dodany do komunikatu OrderCreateRequest.

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

Dla Classic API należy podać pole pay_type o wartości "ma" w formularzu NewPayment.

2.2 Masterpass transparent

Ta forma integracji dostępna jest tylko w REST API i wymaga dodatkowej konfiguracji ze strony PayU.

Zlecanie zamówienia w trybie Masterpass transparent, polega na przygotowaniu komunikatu OrderCreateRequest, zawierającego pole extOrderId oraz sekcję payMethods:

                
                "extOrderId": "<transaction id wykorzystane w ramach usługi Masterpass by Mastercard>",
                "payMethods": {
                    "payMethod" : {
                        "type": "PBL",
                        "value": "ma",
                        "authorizationCode": "<masterpassToken>"
                    }
                }
                
            

Wartość pola authorizationCode kodowana jest base64 i zawiera masterpassToken o następującej strukturze:

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

Dalsze przetwarzanie żądania podlega standardowemu procesowi opisanemu w dokumentacji REST API.

3 Przykładowe zamówienie w usłudze Masterpass transparent

Aby obsłużyć standardowe zamówienie w usłudze Masterpass transaparent, Merchant:

  1. Pobiera cardIssuingTokens dla danej cardId z systemu Masterpass by Mastercard.

  2. Uwierzytelnia się pobierając accessToken z systemu 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. Tworzy zamówienie w systemie PayU dla transakcji z Masterpass by Mastercard, przekazanej w polu extOrderId.



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

    Gdzie pole authorization code przed kodowaniem base64 wyglądało następująco:

                            {
                                "cardId":"55332",
                                "cardIssuingTokens":"eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiI4NGQxNmFlZC0yMGI2LTRmNmEtODE3MC1jNTBlMzg1MzczMDUiLCJzdWIiOiI4NGQxNmFlZC0yMGI2LTRmNmEtODE3MC1jNTBlMzg1MzczMDUiLCJpYXQiOjE1NjgwMjUzMTgsImV4cCI6MTU2ODAyNjIxOCwiaXNPbmVUaW1lQ2FyZFRva2VuIjp0cnVlfQ.sq-lBvG6a3fk_42uUjgs87pw0LkixGGT8-UzprFnukPES0J76HxRsP8wfvv308LSKaqyS2AFlrjE8WGaTj3zgQ",
                                "merchantName":"NazwaMerchanta"
                            }
                            
                        
  5. Otrzymuje odpowiedź w zależności od powodzenia transakcji:



    Response:

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

4 Kody zwracanych błędów w usłudze Mastercard transparent

HTTP Status ErrorCode CodeLiteral Opis
500 ERROR_INTERNAL SERVICE_TEMPORARY_
UNAVAILABLE
Usługa płatności Masterpass chwilowo niedostępna lub problem z tokenizacją danych karty.
400 ERROR_VALUE_INVALID MASTERPASS_INVALID_DATA Niepoprawne dane związane z systemem Masterpass:
  • niepoprawne dane karty,
  • niepoprawny cardId,
  • niepoprawny cardIssuingTokens,
  • wartość extOrderId została już użyta.
400 ERROR_VALUE_INVALID INVALID_CURRENCY_CODE Nieobsługiwana waluta.
400 ERROR_AUTHORIZATION_CODE AUTH_CODE_INVALID Niepoprawny authorizationCode

5 Sandbox

Integracja w trybie bezpośredniego wywołania lightbox oraz transparent nie są dostępne na sandbox.