Marketplace PSD2

1 Wprowadzenie

W celu otrzymania wszelkich informacji związanych z warunkami współpracy jako marketplace prosimy o kontakt z nami pod adresem tech@payu.pl.

1.1 Formularz rejestracyjny sprzedawców

Po procesie rejestracji firmy markeplace udostępniony zostanie specjalny adres pozwalający na rejestrację sprzedawców współpracujących z danym marketplacem. Ma on następującą postać:

https://secure.payu.com/boarding/#/form?lang=pl&nsf=true&partnerId=<MARKETPLACE_ID>&marketplaceExtCustomerId=<EXT_CUSTOMER_ID>

MARKETPLACE_ID jest unikalnym identyfikatorem marketplacu.

EXT_CUSTOMER_ID jest unikalnym identyfikatorem sprzedawcy nadawanym przez marketplace.

Każdy sprzedawca musi zostać zweryfikowany przez PayU. Jeżeli sprzedawca nie zostanie zweryfikowany nie będzie możliwe składanie zamówień zawierających produkty od tego sprzedawcy.

2 Marketplace API

Komunikacja odbywa się zgodnie z protokołem REST API 2.1. Na potrzeby marketplacu wprowadzone zostały rozszerzenia, które dostępne są tylko dla firm współpracujących z PayU jako marketplace.

Opis metod uwierzytelnienia znajduje się w: Uwierzytelnienie użytkownika API

2.1 Status sprzedawców

Sprawdzenie statusu sprzedawcy odbywa się poprzez wysłanie następującego żądania:
                    curl -v -X GET https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/status?currencyCode=PLN \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer <AUTH_TOKEN>"
                
EXT_CUSTOMER_ID jest identyfikatorem sprzedawcy.

Parametry żądania są następujące:

Parametr Wymagalność Komentarz
currencyCode tak Kod waluty zgodny z ISO-4217.

Przykładowa odpowiedź:
                    {
                        "customerVerificationStatus": "Verified"
                    }
                
Pola odpowiedzi są następujące:
Parametr Komentarz
customerVerificationStatus Status sprzedawcy. Przyjmuje wartości:
  • Verified sprzedawca zweryfikowany przez PayU, możliwe jest tworzenie zamówień dla tego sprzedawcy
  • NotVerified sprzedawca nie zweryfikowany przez PayU lub sprzedawca nie istnieje

2.2 Tworzenie zamówienia

Tworzenie zamówienia dla marketplacu oparte jest na standardowej integracji z PayU poprzez REST API: Tworzenie nowego zamówienia. Poniżej znajduje się lista zmian specyficznych dla marketplacu.

Sekcja shoppingCarts

Złożony element shoppingCarts określa podział produktów z zamówienia na poszczególnych sprzedawców.

    ...
    "shoppingCarts": [
        {
            "extCustomerId": "ext-customer-1",
            "amount": 1800,
            "fee": 20,
            "shippingMethods": [
                {
                    "country": "PL",
                    "price": 1500,
                    "name": "Shipping Method 1"
                }
            ],
            "products": [
                {
                    "name": "product-x",
                    "unitPrice": 100,
                    "quantity": 3
                }
            ]
        },
        {
            "extCustomerId": "ext-customer-2",
            "amount": 2700,
            "fee": 27,
            "shippingMethods": [
                {
                    "country": "PL",
                    "price": 2000,
                    "name": "Shipping Method 2"
                }
            ],
            "products": [
                {
                    "name": "product-y",
                    "unitPrice": 700,
                    "quantity": 1
                }
            ]
        }
    ]
    ...
                
Pole Wymagalność Komentarz
shoppingCarts/extCustomerId tak Identyfikator sprzedawcy.
shoppingCarts/amount tak Sumaryczna kwota zakupów u danego sprzedawcy.
shoppingCarts/fee nie Prowizja dla marketplacu. Wartość powinna zawierać się w przedziale <0, amount>
shoppingCarts/products tak Produkty.
shoppingCarts/products/name tak Nazwa produktu.
shoppingCarts/products/unitPrice tak Cena jednostkowa produktu.
shoppingCarts/products/quantity tak Ilość produktów.
shoppingCarts/shippingMethods nie Metoda dostawy.
shoppingCarts/shippingMethods/name tak, jeżeli pole shippingMethods jest wypełnione Nazwa metody dostawy.
shoppingCarts/shippingMethods/price tak, jeżeli pole shippingMethods jest wypełnione Koszt dostawy.
shoppingCarts/shippingMethods/country tak, jeżeli pole shippingMethods jest wypełnione Kraj dostawy zgodny z ISO-3166.

Suma wartości pól amount z wszystkich elementów listy shoppingCarts powinna być równa wartości pola totalAmount w zamówieniu.

Pole buyer/extCustomerId

Sekcja buyer została rozszerzona o pole extCustomerId, które określa identyfikator kupującego nadany przez marketplace:
                    ...
                    "buyer": {
                        "extCustomerId": "buyer-id-1234",
                        "email": "buyer-id-1234@email.com",
                        ...
                    }
                    ...
                
Pole Wymagalność Komentarz
buyer/extCustomerId tak Identyfikator kupującego. Kupujący o takim identyfikatorze nie musi być wcześniej utworzony lub zweryfikowany - przy pierwszym użyciu zostanie automatycznie założony w systemie PayU.

Przykład kompletnego żądania utworzenia zamówienia

                curl -v -X POST https://secure.payu.com/api/v2_1/orders \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer <AUTH_TOKEN>" \
                -d '{
                        "merchantPosId":"199022",
                        "customerIp": "127.0.0.1",
                        "continueUrl": "http://your.eshop.com/continue",
                        "notifyUrl": "https://your.eshop.com/notify",
                        "currencyCode": "PLN",
                        "totalAmount": 5000,
                        "extOrderId": "marketplace-order-xyz-123",
                        "description": "order XYZ-123",
                        "additionalDescription": "additional description",
                        "buyer": {
                            "email": "john.doe@email.com",
                            "phone": "(012)1234567",
                            "firstName": "John",
                            "lastName": "Doe",
                            "language": "pl",
                            "extCustomerId": "john-doe-12345"
                        },
                        "shoppingCarts": [
                            {
                                "extCustomerId": "marketplace-submerchant-1",
                                "amount": 200,
                                "fee": 20,
                                "products": [
                                    {
                                        "name": "product A",
                                        "quantity": 2,
                                        "unitPrice": 100
                                    }
                                ]
                            },
                            {
                                "extCustomerId": "marketplace-submerchant-2",
                                "amount": 1300,
                                "products": [
                                    {
                                        "name": "product B",
                                        "quantity": 2,
                                        "unitPrice": 200
                                    },
                                    {
                                        "name": "product C",
                                        "quantity": 3,
                                        "unitPrice": 300
                                    }
                                ]
                            },
                            {
                                "extCustomerId": "marketplace-submerchant-3",
                                "amount": 3500,
                                "fee":350,
                                "products": [
                                    {
                                        "name": "product D",
                                        "quantity": 1,
                                        "unitPrice": 3500
                                    }
                                ]
                            }
                        ]
                    }'
            
W momencie pozytywnego autoryzowania transakcji dla powyższego zamówienia środki zostaną przypisane w następujący sposób:
  • marketplace-submerchant-1: +1.80 PLN
  • marketplace-submerchant-2: +13.00 PLN
  • marketplace-submerchant-3: +31.50 PLN
  • marketplace: +3.70 PLN

Dodatkowe kody błędów tworzenia zamówienia

StatusCode Code CodeLiteral Opis
DATA_NOT_FOUND CUSTOMER_NOT_FOUND 9999 Sprzedający nie istnieje w systemie PayU.

2.3 Zwrot

Obsługa zwrotów dla marketplacu oparta jest na standardowej integracji z PayU poprzez REST API: Zwroty. Poniżej znajduje się lista zmian specyficznych dla marketplacu.

Istnieje możliwość wykonania zwrotu całościowego lub częściowego dla wybranego sprzedawcy za pomocą następującego żądania:
curl -X POST https://secure.payu.com/api/v2_1/orders/<ORDER_ID>/refunds \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <AUTH_TOKEN>" \
    -d '{
        "refund": {
            "description": "Refund",
            "amount": 1000
            "extCustomerId": "ext-customer-1",
            "extRefundId": "ext-refund-id-1"
        }
    }'
                
ORDER_ID jest identyfikatorem zamówienia, dla którego tworzony jest zwrot.
Pole Wymagalność Komentarz
refund/extRefundId tak Zewnętrzny identyfikator zwrotu.
refund/amount tak Kwota zwrotu. Podanie wartości pola równej wartości pola totalAmount w zamówieniu spowoduje utworzenie pełnych zwrotów do wszystkich sprzedających z zamówienia.
refund/extCustomerId tak, jeżeli wartość pola amount jest różna od wartości pola totalAmount w zamówieniu Identyfikator sprzedawcy.
Przykładowa odpowiedź:
                    {
                        "status": {
                            "statusCode":"SUCCESS",
                            "statusDesc": "Refund queued for processing"
                        },
                        "orderId":"47FD97QSPL140325GUEST000P01",
                        "refund":{
                            "dispositions": {
                                "instrumentAmount": "1000",
                                "walletAmount": "0",
                                "couponAmount": "0"
                            },
                            "refundId": "R84FWMHX6K150901abjtwtchP01",
                            "extRefundId": "ext-refund-id-1"
                        }
                    }
                

Dodatkowe kody błędów tworzenia zwrotów

StatusCode Code CodeLiteral Opis
BUSINESS_ERROR AMOUNT_EXCEEDED 9109 Kwota zwrotu przekracza kwotę dla danego sprzedającego w zamówieniu.
BUSINESS_ERROR AMBIGUOUS_REFUND_SOURCE 9110 Zwrot nie może być z realizowany z więcej niż jednego źródła.
BUSINESS_ERROR AMOUNT_MISSING 9114 Kwota nie została podana.
BUSINESS_ERROR AMOUNT_INVALID 9115 extCustomerId nie został podany, a kwota zwrotu nie jest równa kwocie zamówienia.
BUSINESS_ERROR EXT_REFUND_ID_MISSING 9116 Pole extRefundId nie zostało podany.
BUSINESS_ERROR NO_SHOPPING_CARTS_IN_ORDER 9118 Brak produktów w zamówieniu.
DATA_NOT_FOUND MARKETPLACE_TRANSACTION_NOT_FOUND 9119 Zamówienie o podanym identyfikatorze nie istnieje.
DATA_NOT_FOUND CUSTOMER_NOT_FOUND 9999 Sprzedający nie istnieje w systemie PayU.

2.4 Wypłata

Obsługa wypłat dla marketplacu oparta jest na standardowej integracji z PayU poprzez REST API: Wypłaty. Poniżej znajduje się lista zmian specyficznych dla marketplacu.

Zlecając wypłatę środków dla wybranego sprzedawcy należy wysłać następujące żądanie:
                    curl -X POST https://secure.payu.com/api/v2_1/payouts \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer <AUTH_TOKEN>" \
                    -d '{
                        "shopId":"shop-id",
                        "payout": {
                            "amount": "1000",
                            "currencyCode": "PLN",
                            "description": "Some payout",
                            "extPayoutId": "PAYOUT-1234567890"
                        },
                        "account": {
                            "extCustomerId": "ext-customer-id-1"
                        },
                        "customerAddress": {
                            "name":"John Doe"
                        }
                    }'
                
Pole Wymagalność Komentarz
payout/amount nie Jeżeli pole nie jest wypełnione wtedy wszystkie dostępne środki zostaną wypłacone.
payout/extPayoutId tak Zewnętrzny identyfikator wypłaty.
account/extCustomerId tak Identyfikator sprzedawcy.
Przykładowa odpowiedź:
                {
                    "payout": {
                        "payoutId": "b3e4fc98c6894239864a9d6941f0fe76",
                        "extPayoutId": "PAYOUT23423423423",
                        "extCustomerId": "12345678",
                        "status": "PENDING"
                    },
                    "status": {
                        "statusCode": "SUCCESS"
                    }
                }
                

Dodatkowe kody błędów tworzenia wypłat

StatusCode Code CodeLiteral Opis
BUSINESS_ERROR MISSING_EXTERNAL_CUSTOMER_ID 8362 Brakujące pole extCustomerId.
BUSINESS_ERROR MISSING_EXTERNAL_PAYOUT_ID 8363 Brakujące pole extPayoutId.
ERROR_VALUE_INVALID MARKETPLACE_CUSTOMER_NOT_VERIFIED 9132 Sprzedający nie został jeszcze zweryfikowany przez PayU.
ERROR_VALUE_INVALID PROVIDING_BANK_ACCOUNT_IS_FORBIDDEN 9133 Podanie numeru konta do wypłaty jest zabronione.
DATA_NOT_FOUND CUSTOMER_NOT_FOUND 9999 Sprzedający nie istnieje w systemie PayU.

2.5 Historia operacji

Pobranie historii operacji dla danego sprzedawcy odbywa się poprzez wysłanie następującego żądania:
                    curl -v -X GET https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/operations?dateFrom=<DATE_FROM>&dateTo=<DATE_TO> \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer <AUTH_TOKEN>"
                
EXT_CUSTOMER_ID jest identyfikatorem sprzedawcy.
Parametry żądania są następujące:
Parametr Wymagalność Komentarz
dateFrom tak Data początkowa wyszukiwania. Format: 2017-01-30T20:59:00+02:00
dateTo tak Data końcowa wyszukiwania. Format: 2017-01-30T20:59:00+02:00
type nie Typ operacji do wyszukania. Możliwe wartości:
  • PAYMENT_RECEIVED
  • PAYOUT
  • REFUND_SENT
  • RETURN
currencyCode nie Kod waluty operacji zgodny z ISO-4217.
sortBy nie Pole do sortowania. Dodatkowo znak + lub - przez nazwą pola określa kierunek sortowania. Domyślny kierunek sortowania jest rosnący. Np. sortBy=-amount sortuje wynik po wartości pola amount malejąco.
limit nie Maksymalna liczba rekordów zwróconych na stronie.
offset nie Numer strony. Numeracja rozpoczyna się od 0.
Przykładowa odpowiedź:
                    {
                        "operations": [
                            {
                                "type": "PAYMENT_RECEIVED",
                                "amount": "1500",
                                "currencyCode": "PLN",
                                "description": "operation description",
                                "status": "COMPLETED",
                                "eventDate": "2016-04-20T12:05:54+02:00",
                                "details": {
                                    "orderId": "CWDBL3KD6G170110GUEST000P01",
                                    "extOrderId": "105877825874b0c0b47a0",
                                    "counterparties": [
                                        {
                                            "extCustomerId": "35463545",
                                            "name": "Alice",
                                            "email": "alice@email.com",
                                            "products": [
                                                {
                                                    "name": "product-x",
                                                    "unitPrice": "1500",
                                                    "quantity": "1"
                                                }
                                            ]
                                        }
                                    ],
                                    "funds": []
                                }
                            }
                        ],
                        "pageResponse": {
                            "records": "1",
                            "size": "1",
                            "pageCount": "1"
                        }
                    }
                
Pola odpowiedzi są następujące:
Pole Komentarz
operations Lista operacji spełniających zadane kryteria.
operations/type Typ operacji. Możliwe wartości:
  • PAYOUT
  • REFUND_SENT
  • PAYMENT_RECEIVED
  • RETURN
operations/amount Kwota operacji (zamówienia, zwrotu, wypłaty).
operations/currencyCode Kod waluty operacji zgodny z ISO-4217.
operations/description Opis operacji.
operations/status Status operacji.
operations/eventDate Czas zarejestrowania operacji. Format: 2017-01-30T22:33:44+02:00
operations/details Dodatkowe informacje o operacji. Mogą się różnić w zależności od typu operacji. Szczegóły znajdują się poniżej.
pageResponse/records Sumaryczna ilość znalezionych operacji.
pageResponse/size Ilość zwróconych operacji.
pageResponse/pageCount Ilość stron.

Dodatkowe pola odpowiedzi dla operacji typu PAYMENT_RECEIVED:

Pole Komentarz
operations/details/orderId Identyfikator zamówienia.
operations/details/extOrderId Zewnętrzny identyfikator zamówienia.
operations/details/counterparties Elementy zamówienia.
operations/details/counterparties/extCustomerId Identyfikator kupującego.
operations/details/counterparties/name Nazwa kupującego.
operations/details/counterparties/email Email kupującego.
operations/details/counterparties/products Lista produktów w zamówieniu.
operations/details/counterparties/products/name Nazwa produktu.
operations/details/counterparties/products/unitPrice Cena jednostkowa produktu.
operations/details/counterparties/products/quantity Ilość produktów w zamówieniu.

Dodatkowe pola odpowiedzi dla operacji typu REFUND_SENT:

Pole Komentarz
operations/details/orderId Identyfikator zamówienia.
operations/details/extOrderId Zewnętrzny identyfikator zamówienia.
operations/details/refundId Identyfikator zwrotu.
operations/details/extRefundId Zewnętrzny identyfikator zwrotu.
operations/details/counterparties Elementy zamówienia.
operations/details/counterparties/extCustomerId Identyfikator kupującego.
operations/details/counterparties/name Nazwa kupującego.
operations/details/counterparties/email Email kupującego.

Dodatkowe pola odpowiedzi dla operacji typu PAYOUT:

Pole Komentarz
operations/details/payoutId Identyfikator wypłaty.
operations/details/extPayoutId Zewnętrzny identyfikator wypłaty.

Dodatkowe pola odpowiedzi dla operacji typu RETURN:

Pole Komentarz
operations/details/payoutId Identyfikator wypłaty.
operations/details/extPayoutId Zewnętrzny identyfikator wypłaty.

2.6 Saldo sprzedawcy

Sprawdzenie salda sprzedawcy odbywa się poprzez wysłanie następującego żądania:
                    curl -v -X GET https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/balances?currencyCode=PLN \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer <AUTH_TOKEN>"
                
EXT_CUSTOMER_ID jest identyfikatorem sprzedawcy.

Parametry żądania są następujące:

Parametr Wymagalność Komentarz
currencyCode tak Kod waluty zgodny z ISO-4217.

Przykładowa odpowiedź:
                    {
                        "balance": {
                            "availableAmount": "5494",
                            "totalAmount": "5500"
                        },
                        "status": {
                            "statusCode": "SUCCESS"
                        }
                    }
                

Pola odpowiedzi są następujące:

Pole Komentarz
balance/availableAmount Dostępne środki.
balance/totalAmount Wszystkie środki sprzedającego (wliczając środki zablokowane).
status/statusCode Status odpowiedzi.