Marketplace PSD2

1 Wprowadzenie

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

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=false&partnerId=MARKETPLACE_ID&marketplaceExtCustomerId=EXT_CUSTOMER_ID

MARKETPLACE_ID jest unikalnym identyfikatorem marketplacu nadawanym przez PayU.

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.

1.2 Testowanie Marketpalce

Funkcjonalność marketplace można przetestować na środowisku sandbox. Konto testowe jest ogólnodostępne wszystkim, którzy aktualnie testują usługę przez to salda submerchantów jak i samego marketplace mogą ulegać zmianie.

Konto sandbox

                    
                    Id punktu płatności (pos_id):       341009
                    Drugi klucz (MD5):                  289c28ec590ba6940746266c5d64932f
                    Protokół OAuth (client_id):         341009
                    Protokół OAuth (client_secret):     ff9994baa59b73c7ca56a5480e608f02

Lista ext_customer_id

                    
                    //ext_customer_id submerchantów
                    submerchant_A
                    submerchant_B
                    submerchant_C
                    submerchant_unverified -- submerchant w statusie ‘niezatwierdzony’ - nie można wykonać wypłaty itp.

Uwaga! Aby móc wykonać payout z konta testowego, musisz ustawić wartość parametru shopId na 0pKb1aqC.

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

Ta funkcja dostępna jest tylko dla marketplace’u rejestrującego sprzedawców przez formularz opisany w punkcie 1.1. Nie jest dostępna dla marketplacu korzystającego z API rejestracyjnego (SF).

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",
                        "name": "Example Company",
                        "taxId": "123123123",
                        "regon": "123123123"
                    }

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
name	Nazwa firmy
taxId	NIP firmy. Dla firm zagranicznych pole zawiera wartość: Tax ID lub VAT UE.
regon	REGON firmy

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,
                    "virtual": false,
                    "listingDate": "2020-09-28T08:17:52Z"
                }
            ]
        },
        {
            "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,
                    "virtual": false,
                    "listingDate": "2020-10-22T08:17:52Z"
                }
            ]
        }
    ]
    ...

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.products.virtual	nie	Produkt może być wirtualny lub materialny; przyjmuje wartości `true` i `false`.
shoppingCarts.products.listingDate	nie	Data wystawienia produktu, przykład: "2016-01-26T17:35:37+01:00".
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	Dwuliterowy kod kraju 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.

W przypadku otrzymania następującej odpowiedzi do zamówienia:

                {
                    "iFrameAllowed": false,
                    "status": {
                        "statusCode": "DATA_NOT_FOUND",
                        "code": "9999",
                        "codeLiteral": "CUSTOMER_NOT_FOUND"
                    }
                }

Należy sprawdzić poprawność parametru extCustomerId.

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,
                                        "virtual": false,
                                        "listingDate": "2020-09-28T08:17:52Z"
                                    }
                                ]
                            },
                            {
                                "extCustomerId": "marketplace-submerchant-2",
                                "amount": 1300,
                                "products": [
                                    {
                                        "name": "product B",
                                        "quantity": 2,
                                        "unitPrice": 200,
                                        "virtual": false,
                                        "listingDate": "2020-09-12T08:17:52Z"
                                    },
                                    {
                                        "name": "product C",
                                        "quantity": 3,
                                        "unitPrice": 300,
                                        "virtual": false,
                                        "listingDate": "2018-09-28T08:17:52Z"
                                    }
                                ]
                            },
                            {
                                "extCustomerId": "marketplace-submerchant-3",
                                "amount": 3500,
                                "fee":350,
                                "products": [
                                    {
                                        "name": "product D",
                                        "quantity": 1,
                                        "unitPrice": 3500,
                                        "virtual": false,
                                        "listingDate": "2018-09-28T05:17:52Z"
                                    }
                                ]
                            }
                        ]
                    }'

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

Przykład kompletnego żądania utworzenia zamówienia z wybraną metodą płatności

                     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,
                                             "virtual": false,
                                             "listingDate": "2020-09-28T08:17:52Z"
                                         }
                                     ]
                                 },
                                 {
                                     "extCustomerId": "marketplace-submerchant-2",
                                     "amount": 1300,
                                     "products": [
                                         {
                                             "name": "product B",
                                             "quantity": 2,
                                             "unitPrice": 200,
                                             "virtual": false,
                                             "listingDate": "2020-09-28T08:18:52Z"
                                         },
                                         {
                                             "name": "product C",
                                             "quantity": 3,
                                             "unitPrice": 300,
                                             "virtual": false,
                                             "listingDate": "2020-02-28T09:47:52Z"
                                         }
                                     ]
                                 },
                                 {
                                     "extCustomerId": "marketplace-submerchant-3",
                                     "amount": 3500,
                                     "fee":350,
                                     "products": [
                                         {
                                             "name": "product D",
                                             "quantity": 1,
                                             "unitPrice": 3500,
                                             "virtual": false,
                                             "listingDate": "2021-09-28T08:17:52Z"
                                         }
                                     ]
                                 }
                             ],
                             "payMethods": {
                                 "payMethod":{
                                     "type":"PBL",
                                     "value":"m",
                                     "amount":5000
                                 }
                             }
                         }'

Wyjaśnienia pól sekcji `payMethods`

Pole	Wymagalność	Komentarz
payMethod.type	Tak	Typ metody płatności.
payMethod.value	Tak	Symbol typu płatności.
payMethod.amount	Tak	Całkowita kwota zamówienia. Powinna być równa polu `totalAmount`, jak również sumie wszystkich pól `amount` w sekcji `shoppingCarts`.

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	CodeLiteral	Code	Opis
BUSINESS_ERROR	TRANS_NOT_ENDED	9101	Transakcja nie jest zakończona.
BUSINESS_ERROR	NO_BALANCE	9102	Sprzedawca nie ma wystarczających środków na koncie.
ERROR_VALUE_INVALID	AMOUNT_TO_BIG	9103	Zbyt duża kwota zwrotu.
BUSINESS_ERROR	MARKETPLACE_CUSTOMER _IS_NOT_ACTIVE	9104	Sprzedawca jest nieaktywny.
BUSINESS_ERROR	MARKETPLACE_CUSTOMER _IS_LOCKED	9106	Sprzedawca jest zablokowany.
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": "my_payout_id_123"
                        },
                        "account": {
                            "extCustomerId": "ext-customer-id-1"
                        }
                    }'

Aby dokonać wypłaty na konto sandbox marketplace należy użyć parametru extCustomerId: MARKETPLACE_K2_FEE

Pole	Wymagalność	Komentarz
shopId	Tak	Publiczne id sklepu pozyskane z panelu PayU.
payout.amount	Nie	Jeżeli pole nie jest wypełnione wtedy wszystkie dostępne środki zostaną wypłacone.
payout.currencyCode	Tak	Waluta, w której dokonano wypłaty.
payout.description	Tak	Opis wypłaty.
payout.extPayoutId	Nie	Identyfikator Zewnętrzny Wypłaty, nadany przez klienta. Klient może zlecić tylko jedną wypłatę o zadanym identyfikatorze zewnętrznym. Wymagana jest unikalność `extPayoutId` w obrębie wypłat tego samego sklepu.
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	CodeLiteral	Code	Opis
BUSINESS_ERROR	NOT_ENOUGH_FUNDS	8325	Sprzedawca nie ma wystarczających środków na koncie.
BUSINESS_ERROR	PAYOUT_ALREADY_EXISTS	8356	Payout już istnieje: payoutId=[7b52a5b922a34b978bc112cd64b09caf].
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	AMOUNT_TO_BIG	9103	Zbyt duża kwota wypłaty.
BUSINESS_ERROR	MARKETPLACE_CUSTOMER _IS_NOT_ACTIVE	9104	Sprzedawca jest nieaktywny.
BUSINESS_ERROR	MARKETPLACE_CUSTOMER _IS_LOCKED	9106	Sprzedawca jest zablokowany.
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 -X GET \
                        'https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/operations?eventDateFrom=<EVENT_DATE_FROM>&eventDateTo=<EVENT_DATE_TO>' \
                        -H 'Authorization: Bearer <AUTH_TOKEN>' \
                        -H 'Content-Type: application/json' \
                        -H 'cache-control: no-cache'

EXT_CUSTOMER_ID jest identyfikatorem sprzedawcy.

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

Parametr	Wymagalność	Komentarz
eventDateFrom	tak	Początek zakresu wyszukiwania dla "eventDate". Format: 2019-01-30T20%3A59%3A00%2B02%3A00 Data musi być zakodowana na url.
eventDateTo	tak	Koniec zakresu wyszukiwania dla "eventDate". Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Data musi być zakodowana na url.
creationDateFrom	nie	Początek zakresu wyszukiwania dla "creationDate". Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Data musi być zakodowana na url.
creationDateTo	nie	Koniec zakresu wyszukiwania dla „creationDate”. Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Data musi być zakodowana na url.
type	nie	Typ operacji do wyszukania. Możliwe wartości: PAYMENT_SENT PAYMENT_RECEIVED PAYOUT REFUND_SENT REFUND_RECEIVED RETURN ADMIN_TRANSFER_SENT ADMIN_TRANSFER_RECEIVED FEE_TRANSFER_SENT FEE_TRANSFER_RECEIVED Możesz podać wiele wartości, oddzielając kolejne wpisy przecinkiem.
currencyCode	nie	Kod waluty operacji zgodny z ISO-4217. Możesz podać wiele wartości, oddzielając kolejne wpisy przecinkiem.
sortBy	nie	Pole do sortowania. Dodatkowo znak `+` lub `-` przez nazwą pola określa kierunek sortowania. Domyślny kierunek sortowania jest rosnący. Do posortowania historii operacji można użyć parametrów: `eventDate` `creationDate` `type` `currencyCode` Np. `sortBy=-eventDate` sortuje wynik po wartości pola `eventDate` 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",
                                "creationDate": "2016-04-20T11:05:54+02:00",
                                "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: PAYMENT_SENT PAYMENT_RECEIVED PAYOUT REFUND_SENT REFUND_RECEIVED RETURN ADMIN_TRANSFER_SENT ADMIN_TRANSFER_RECEIVED FEE_TRANSFER_SENT FEE_TRANSFER_RECEIVED CHARGEBACK ADMIN_CORRECTION
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.creationDate	Moment zlecenia operacji. Format: 2019-11-30T20:33:44+02:00
operations.eventDate	Moment zakończenia operacji. Format: 2019-11-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.feeAmount	Kwota prowizji marketplace.
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.

Dodatkowe pola odpowiedzi dla operacji typu CHARGEBACK i ADMIN_CORRECTION:

Pole	Komentarz
operations.details.correctionId	Identyfikator korekty.

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.

2.7 Przemieszczanie środków pomiedzy saldami

W modelu marketplace, w przypadku zaistnienia takiej potrzeby, możliwe jest przesyłanie środków pomiędzy saldami marketplace i submerchantów.

Do włączenia tej funkcjonalności wymaganana jest konfiguracja po stronie PayU i zgoda działu Compliance. W celu jej włączenia prosimy o kontakt.

Przelew z salda submerchanta na saldo marketplace

Dla wymienionych metod wymagane jest pobranie acces token client_credentials dla danego marketplace.

                    
                    curl -X POST https://secure.snd.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/feeDebitTransfer \
                     -H 'Authorization: Bearer 4b29a650-82b7-4c1b-8b6f-2786edd6d2bd' \
                     -H 'Content-Type: application/json' \
                     -H 'Postman-Token: dc779a1e-07d4-4998-bbb6-bb7e0bbbf45b' \
                     -H 'cache-control: no-cache' \
                     -d '{
                         "amount": 25, 
                         "currencyCode": "PLN",
                         "description": "Get fee for order XX2ORD2",
                         "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734"
                     }'

EXT_CUSTOMER_ID jest unikalnym identyfikatorem submerchanta.

Parametry żądania:

Parametr	Opis
amount	Kwota transferu.
currencyCode	Kod waluty zgodny z ISO-4217.
description	Opis operacji.
extTransferId	Unikalny dla danego marketplace identyfikator przelewu.

Przykładowa odpowiedź dla żądania transferu środków

                    
                    {
                        "extCustomerId": "<extCustomerId>",
                        "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734",
                        "status": {
                            "statusCode": "SUCCESS"
                        }
                    }

Parametry odpowiedzi:

Parametr	Opis
extCustomerId	Unikalny identyfikator submerchanta.
extTransferId	Unikalny dla danego marketplace identyfikator przelewu.
status.statusCode	Status odpowiedzi.

Przelew z salda marketplace na saldo submerchanta

                    
                curl -X POST https://secure.snd.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/feeCreditTransfer \
                 -H 'Authorization: Bearer 4b29a650-82b7-4c1b-8b6f-2786edd6d2bd' \
                 -H 'Content-Type: application/json' \
                 -H 'Postman-Token: 9f9a1496-1864-4856-9b50-699fc1e0ef1f' \
                 -H 'cache-control: no-cache' \
                 -d '{
                     "amount": 25, 
                     "currencyCode": "PLN",
                     "description": "Return fee for order XXX1ORD",
                     "extTransferId": "credit-63a3e837-ba7e-45a0-b1b5-267e2c237cd6"
                 }'

EXT_CUSTOMER_ID jest unikalnym identyfikatorem submerchanta.

Parametry żądania:

Parametr	Komentarz
amount	Kwota transferu.
currencyCode	Kod waluty zgodny z ISO-4217.
description	Opis operacji.
extTransferId	Unikalny dla danego marketplace identyfikator przelewu.

Przykładowa odpowiedź dla żądania transferu środków

                    
                    {
                        "extCustomerId": "<extCustomerId>",
                        "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734",
                        "status": {
                            "statusCode": "SUCCESS"
                        }
                    }

Parametry odpowiedzi:

Parametr	Komentarz
extCustomerId	Unikalny identyfikator submerchanta.
extTransferId	Unikalny dla danego marketplace identyfikator przelewu.
status.statusCode	Status odpowiedzi.

Potencjalne kody błędów przy transferze środków pomiędzy saldami

HttpStatus	StatusCode	CodeLiteral
400	BUSINESS_ERROR	MARKETPLACE_TRANSFER_EXISTS
400	BUSINESS_ERROR	MARKETPLACE_NO_BALANCE
400	BUSINESS_ERROR	MARKETPLACE_FEE_TRANSFER_LIMITS_EXCEEDED

Marketplace PSD2

1 Wprowadzenie

1.1 Formularz rejestracyjny sprzedawców

1.2 Testowanie Marketpalce

Konto sandbox

Lista ext_customer_id

2 Marketplace API

2.1 Status sprzedawców

2.2 Tworzenie zamówienia

Sekcja shoppingCarts

Pole buyer/extCustomerId

Przykład kompletnego żądania utworzenia zamówienia

Przykład kompletnego żądania utworzenia zamówienia z wybraną metodą płatności

Wyjaśnienia pól sekcji payMethods

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

2.3 Zwrot

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

2.4 Wypłata

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

2.5 Historia operacji

2.6 Saldo sprzedawcy

2.7 Przemieszczanie środków pomiedzy saldami

Przelew z salda submerchanta na saldo marketplace

Przykładowa odpowiedź dla żądania transferu środków

Przelew z salda marketplace na saldo submerchanta

Przykładowa odpowiedź dla żądania transferu środków

Potencjalne kody błędów przy transferze środków pomiędzy saldami

Wyjaśnienia pól sekcji `payMethods`