Program partnerski

Rekomendacyjny program partnerski skierowany jest do wszystkich, którzy chcą współpracować z PayU w zakresie polecania klientów. W szczególności dotyczy to operatorów wszelkiego rodzaju platform sklepowych i web-developerów integrujących usługi płatnicze.

W celu otrzymania wszelkich informacji związanych z warunkami współpracy i tym jak zostać partnerem PayU, wyślij wiadomość pod adres partnerzy@payu.pl.

Poniżej znajdują się informacje o tym jak zarejestrować poleconego klienta ("merchanta") w systemie PayU.

Rejestracja poprzez link

Notatka

Link do rejestracji to najprostszy sposób rejestracji poleconych klientów w systemie PayU. Obecnie poprzez link możesz rejestrować tylko sklepy internetowe zamierzające działać na polskim rynku.

Link możesz wysyłać potencjalnym sprzedawcom za pośrednictwem wiadomości e-mail lub osadzić go na swojej stronie internetowej. Możesz go użyć wielokrotnie, a każdy, kto na niego kliknie, zostanie przekierowany do procesu rejestracji PayU. Każda firma, która ukończy proces rejestracji, zostanie oznaczona jako polecona przez Ciebie.

Przykład linku rejestracyjnego

https://secure.payu.com/boarding/#/form?lang=pl&nsf=false&partnerId=someid

Parametry query linku rejestracyjnego

Parametr	Wymagalność	Opis
nsf	Nie	Użyty z wartością true, informuje o rejestracji merchanta z pominięciem akceptacji umowy elektronicznej. Ta opcja może być użyta jeśli polecani merchanci nie kwalifikują się do zawarcia standardowej umowy z PayU.
partnerId	Tak	ID partnera nadane przez PayU.
lang	No	Określa język formularza rejestracyjnego. Jeżeli nie zostanie użyty, przyjęta zostaje domyślna wartość. Możliwe wartości: en (angielski, domyślny), pl (polski).

Regulamin

Notatka

Regulamin Programu Rekomendacyjnego PayU obowiązujący od 1 kwietnia 2017 znajdziesz tutaj.

Poprzednią wersję regulaminu znajdziesz tutaj.

Materiały graficzne

Materiały graficzne do pobrania:

Standardowe

Alternatywne

Rejestracja poprzez API

Notatka

API służy do rejestracji merchantów w systemie PayU bezpośrednio ze strony partnera.

Merchant Registration API pozwala partnerom rejestrować merchantow bezpośrednio w systemie PayU. API jest skierowane w szczególności do integratorów usług płatniczych i operatorów platform typu SaaS (ang. Software as a Service).

Pomimo automatycznego utworzenia merchanta (wspomaganego przez partnera), Merchant Registration API zakłada, że PayU wykonuje następujące procesy:

1. Weryfikację merchanta poprzez procedurę KYC (ang. Know-Your-Customer) w tym kontrolę AML (ang. Anti-Money-Laundering).
2. Zawieranie umów handlowych, zazwyczaj przez Internet za pośrednictwem panelu merchanta.
3. Aktywację merchanta w celu umożliwienia akceptowania płatności.

Dla celów tej dokumentacji "merchant" oznacza zestaw podmiotów wyznaczających rodzaj klienta, który generuje płatności i otrzymuje zapłaty od płatników. W skrócie tymi podmiotami są:

1. Firma - osoba prawna (nazwa, adres, identyfikator podatkowy itp.).
2. Adres strony URL - adres internetowy sklepu, działalności charytatywnej lub innego płatnego serwisu.
3. Sklep - na tym poziomie, zdefiniowane są: waluta płatnicza, saldo oraz szczegóły dotyczące wypłat (wraz z numerem konta merchanta).
4. POS (ang. point of sale) - punkt płatności, na którym konfigurowane są dostępne metody płatności. Zlecenia płatności są generowane na tym poziomie.

Wprowadzenie

Aby móc korzystać z "Registration API", musisz zarejestrować się jako "partner" (tj. zapisać się do programu partnereskiego PayU) i otrzymać własne klucze client_id i client_secret umożliwiające uwierzytelnienie połączenia z API.

Notatka

API rejestracyjne jest również dostępne na środowisku sandbox.

Zanim uzyskasz klucze produkcyjne, możesz użyć poniższych kluczy testowych:

Klucze testowe

client_id = egmcvdo5
client_secret = 9e0cad643b2d4f0bc1fe1750b9b706ec

Pełen proces rejestracji nowego merchanta w PayU wygląda następująco:

1. Uzyskanie ogólnego tokena dostępowego OAuth w celu stworzenia Firmy.
2. Stworzenie nowej firmy, otrzymanie publicznego firmId.
3. Uzyskanie tokena dostępowego w kontekście danej Firmy dla tworzenia kolejnych encji dla Firmy.
4. Stworzenie URL dla Firmy, uzyskanie publicznego urlId.
5. Stworzenie Sklepu przypisanego do URL, uzyskanie publicznego shopId.
6. Stworzenie POSa dla sklepu, uzyskanie publicznego posId.
7. Uzyskanie danych konfiguracyjnych POSa i dodanie ich do twojej paltformy SaaS w celu tworzenia transakcji płatniczych w imieniu merchanta.
8. Uzyskanie tokena dostępowego OAuth2 w celu pobrania metod płatności z POSa.
9. Pobranie metod płatności wraz z ich statusami. Początkowo POS ma dostępną jedynie testową płatność i nie ma włączonych automatycznych wypłat. Dodanie aktywnych metod płatności oznacza aktywację merchanta przez PayU.

Tworzenie firmy

Uwierzytalnianie żądania

Aby móc komunikować się z systemem PayU, należy uwierzytelnić żądanie za pomocą tokenu OAuth wygenerowanego w trybie client_credentials.

Więcej informacji na temat uwierzytelniania na serwerach PayU znajdziesz w sekcji Uwierzytelnianie żądań.

Żądanie stworzenia firmy

Poniżej znajdują się przykłady żądań zawierających minimum danych koniecznych do utworzenia czeskiej i polskiej firmy.

Polska firma

curl -X POST https://secure.payu.com/api/v2_1/firms \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
    -d '{
            "name": "Testowa sp. z o.o.",
            "type": "SO",
            "taxId": "3771910486",
            "taxIdType": "NIP",
            "cin": "138237420",
            "bankAccount": "PL92906300080597567560803897",
            "partnerId": "egmcvdo5",
            "businessArea": {
                "origin": "PL"
            },
            "users": [
                {
                    "name": "Jan",
                    "surname": "Nowak",
                    "email": "jan.nowak@testowa.pl",
                    "phone": "123123123",
                    "role": "manager"
                }
            ],
            "representatives": [
                {
                    "name": "Jan",
                    "surname": "Nowak",
                    "nin": "80010104578",
                    "countryCode": "PL"
                }
            ],
            "contactData": {
                "phone": "123123123",
                "email": "biuro@@testowa.pl"
            },
            "address": {
                "street": "Grunwaldzka",
                "houseNo": "186",
                "apartmentNo": "1",
                "postalCode": "61-166",
                "city": "Poznań",
                "countryCode": "PL"
            }
       }'

Czeska firma

curl -X POST https://secure.payu.com/api/v2_1/firms \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer a9a4536e-62ba-4f60-8017-6053211d3f47" \
    -d '{
            "name": "e-shop a.s.",
            "type": "AS",
            "cin": "138237420",
            "taxIdType": "VAT_EU",
            "bankAccount": "2000145399/0800",
            "partnerId": "egmcvdo5",
            "businessArea": {
                "origin": "CZ"
            },
            "users": [
                {
                    "name": "Jana",
                    "surname": "Nováková",
                    "email": "jana@e-shop.cz",
                    "role": "MANAGER"
                }
            ],
            "representatives": [
                {
                    "name": "Jana",
                    "surname": "Nováková",
                    "countryCode": "CZ",
                    "birthDate": "1990-01-01"
                }
            ],
            "contactData": {
                "phone": "123123123",
                "email": "office@@e-shop.cz"
            },
            "address": {
                "street": "Antala Staška",
                "houseNo": "2027",
                "apartmentNo": "77",
                "postalCode": "140 00",
                "city": "Praha",
                "countryCode": "CZ"
            }
        }'

W odpowiedzi otrzymasz parametr firmId, który powinien być przechowywany w twoim systemie. Zostanie on użyty w celu stworzenia kolejnych podmiotów należących do danej firmy.

Parametr firmId odebrany w odpowiedzi

{
  "firmId": "nZzFT4I5"
}

Szczegóły parametrów znajdziesz w sekcji Create a Firm w naszej referencji API.

Uwierzytelnianie firmy (OAuth)

Aby utworzyć kolejne podmioty w ramach wcześniej utworzonej firmy, musisz wygenerować token OAuth specyficzny dla firmy. Aby to zrobić, należy uwierzytelnić się przy użyciu standardu OAuth, uzyskując token z grant_type="partner". Konieczne będzie również dodanie parametru firm_id do żądania.

Więcej informacji na temat uwierzytelniania na serwerach PayU znajdziesz w sekcji Uwierzytelnianie żądań.

Notatka

Ta metoda uwierzytelniania będzie używana do tworzenia każdego podmiotu w zakresie firmy:

• Adresy URL,
• Sklepy,
• Punktu płatności.

Tworzenie adresu URL

Po stworzeniu firmy i uzyskaniu tokena OAuth w zakresie firmy, musisz stworzyć adres URL.

URL powinien być prawdziwym adresem, z którego rozpoczynana jest "podróż klienta" (np. strona sklepu internetowego albo organizacji charytatywnej itp.).

Przy tworzeniu URL musisz wskazać pożądane usługi płatnicze.

Notatka

W ścieżce endpointa zawiera się parametr firmId.

Przykład żądania utworzenie adresu URL

curl -X POST 'https://secure.payu.com/api/v2_1/firms/{firmId}/urls' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
    -d '{
            "value":"http://www.test-url.com",
            "mcc": "0742",
            "services":[
                {
                    "type":"TRANSFERS"
                },
                {
                    "type":"CARD"
                }
            ]
        }'

Wartości parametru mcc

Wartość	Opis
4511	Linie lotnicze
4722	Wycieczki i biura podróży
4789	Transport
4812	Telefony komórkowe
4816	Sieci i usługi komputerowe
4900	Dostawa prądu, wody i gazu
5047	Artykuły medyczne
5200	Dom i ogród
5262	Marketplace
5300	MLM (Marketing wielopoziomowy)
5499	Artykuły spożywcze
5533	Sprzedaż pojazdów i części
5651	Odzież, obuwie i akcesoria
5732	Komputery, RTV i AGD
5812	Gastronomia
5815	E-booki, cyfrowa muzyka i film
5816	Gry
5912	Leki i suplementy
5941	Artykuły sportowe
5942	Książki i czasopisma
5944	Biżuteria
5977	Kosmetyki
5993	Tytoń i e-papierosy
5999	Erotyka
6050	Usługi finansowe
6300	Ubezpieczenia
7011	Hotele, apartamenty, noclegi
7273	Portale randkowe
7311	Reklama i ogłoszenia
7333	Fotografia i grafika
7512	Wynajem pojazdów
7922	Wydarzenia i konferencje
7995	Hazard
8099	Usługi medyczne
8299	Edukacja i szkolenia online
8398	Fundacje i działalność charytatywna
8651	Zbiórki pieniędzy

Notatka

Domyślne mcc

Jeżeli działalność wymaga innego MCC niż podane na liście, należy podać wartość 8999.

W odpowiedzi otrzymasz parameter urlId, który powinien być zachowany w twoim systemie. Zostanie on wykorzystany do stworzenia sklepu.

Parametr urlId odebrany w odpowiedzi stworzenia adresu URL

{
  "urlId": "PItR5x0v"
}

Szczegóły parametrów znajdziesz w sekcji Create a URL for the Partner's Firm w naszej referencji API.

Tworzenie sklepu

Po stworzeniu firmy i adresu URL, you need to create a shop.

Sklep wymaga odwołania do adresu URL. Jest on wykorzystywany do przechowywania salda konta płatniczego, dlatego jego najważniejszym parametrem jest currency.

Notatka

W ścieżce endpointu zawiera się parametr firmId.

Przykład żądania tworzenia sklepu

curl -X POST 'https://secure.payu.com/api/v2_1/firms/{firmId}/shops' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-d '{
      "name":"Shop name",
      "description":"Shop description",
      "currencyCode":"EUR",
      "urlId":"PItR5x0v"
  }'

W odpowiedzi otrzymasz parametr shopId, który powinien być przechowywany w twoim systemie i zostanie użyty przy tworzeniu POS.

Parametr shopId odebrany w odpowiedzi do żądania stworzenia sklepu

{
  "shopId": "ycmGyfCv"
}

Szczegóły parametrów znajdziesz w sekcji Create a Shop for the Partner w naszej referencji API.

Tworzenie punktu sprzedaży

POS (punkt sprzedaży) jest ostatnim bytem, który musisz stworzyć.

POS jest zakładany w ramach sklepu, po którym dziedziczy waluty. Dane uwierzytelniające płatności są przechowywane na danym punkcie płatności.

Notatka

W ścieżce endpointa powinien być zawarty parameter shopId.

Przykład żądania tworzenia POSa

curl -X POST https://secure.payu.com/api/v2_1/shops/{shopId}/poses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-d '{
      "name":"Test POS",
      "type":"REST"
  }'

W odpowiedzi otrzymasz parametr posId, który powinien być przechowywany w twoim systemie, w celu pobrania danych POS.

Przykład parametru podId otrzymanego w odpowiedzi

{
  "posId": "JyoMIVTY"
}

Szczegóły parametrów znajdziesz w sekcji Create POS for Partner w naszej referencji API.

Żądanie zawiera parametry name i type konkretnego POS. Parametr type domyślnie przyjmuje wartość REST i pozwala to na integrację płatności przez REST API.

POS rodzaju Classic

W rzadkich przypakach, w których wymagane będzie użycie typu CLASSIC. W celu uzyskania dalszych wskazówek prosimy o kontakt z obsługą techniczą PayU.

Pobieranie danych POS

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

Aby pobrać dane POSa musisz wywołać endpoint /api/v2_1/poses/{posId} przy użyciu metody GET.

Przykład pobrania danych POSa

curl -X GET 'https://secure.payu.com/api/v2_1/poses/{posId}' \
-H 'Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47'

W odpowiedzi otrzymasz pełen zestaw danych, które pozwolą ci na uwierzytelnienie płatności, zwrotów, a także umożliwią sprawdzenie powiadomień o statusie płatności.

Retrieving POS credentials response

{
  "posId": "JyoMIVTY",
  "type": "REST",
  "name": "Test POS",
  "encoding": "UTF-8",
  "authorization": {
    "standard": {
      "merchantPosId": "385234",
      "key": "9c0041e05fdee99749de4c2d2ce4c66e",
      "secondKey": "f096a39d78fbe03b8d23dde43b728cfd",
      "authKey": "uHcZ9Ly"
    }
  }
}

Szczegóły parametrów znajdziesz w sekcji Retrieve Partner's POS Data w naszej referencji API.

Tworzenie użytkownika

Po skonfigurowaniu firmy i uzyskaniu firmowego tokena dostępu OAuth, możesz utworzyć dodatkowych użytkowników firmy. Wysyłając żądanie utworzenia nowego użytkownika możesz przypisać mu rolę (menedżer lub użytkownik). Jednak aby określić jego szczegółowe uprawnienia, musisz zalogować się do Panelu Menadżera.

Notes

W ścieżce endpointa powinien być zawarty parameter shopId.

Tworzenie nowego użytkownika

curl -X POST 'https://secure.payu.com/api/v2_1/firms/{firmId}/users' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-d '{
  "user": {
    "name": "John",
    "surname": "Doe",
    "email": "john.doe@test.com",
    "role": "manager"  // manager/user
  }
}'

Szczegóły parametrów znajdziesz w sekcji Create a User w naszej referencji API.

W odpowiedzi na pomyślne żądanie utworzenia użytkownika otrzymasz parametr userId wraz z odpowiedzią HTTP 201. Obecnie parametr ten nie jest wykorzystywany w żadnym API PayU.

userId Parameter Example Przykład parametru userId

{
  "userId": "2e629a11-8add-49c5-bf27-a7f684721b86"
}

Typy firm

Dostępne typy firm

Type	Polish Name	English Name	Czech Name
PP	jednoosobowa działalność gospodarcza	sole trader	podnikající fyzická osoba tuzemská
SO	spółka z ograniczoną odpowiedzialnością	limited liability company	společnost s ručením omezeným
SC	spółka cywilna	civil law partnership	občanské sdružení
SJ	spółka jawna	general partnership	komora (hospodářská, agrární)
SA	spółka akcyjna	joint-stock company	akciová společnost
FU	fundacja	foundation	nadace
SK	spółka komandytowa	limited liability partnership	společnost komanditní
ST	stowarzyszenie	association	spolek
SP	spółka partnerska	professional partnership	samosprávná stavovská organizace (profesní komora)
SD	spółka komandytowo-akcyjna	limited joint-stock partnership	společnost komanditní na akcie
PO	placówka oświaty	educational institution	školská právnická osoba
SPOL	spółdzielnia	cooperative	družstvo
KOP	kościelna osoba prawna lub jej jednostka organizacyjna	church legal person	evidované církevní právnické osoby
JST	jednostka samorządu terytorialnego	local government unit	obec, kraj, městská část, městský obvod
IB	instytut badawczy	research institute	veřejná výzkumná instituce
PPZ	przedstawicielstwo przedsiębiorstwa zagranicznego	agency of foreign company	odštěpný závod zahraniční právnické osoby
PRPA	przedsiębiorstwo państwowe	state company	státní podnik
SIK	publiczna instytucja kultury	public culture institution	veřejná kulturní instituce
FZ	zagraniczna osoba prawna	foreign legal body	zahraniční spolek

Dalsze działania

Po otrzymaniu danych POSa możesz rozważyć wykorzystanie ich, nie tylko w kontekście integracji usług płatniczych określonych w REST API, ale także do wywołań API niezwiązanych bezpośrednio z płatnościami, np.

• Pobranie dostępnych metod płatności (metody płatności są zwracane tylko w przypadku aktywowanych merchantów).
• Pobranie salda merchanta.
• Ułatwienie wypłat.