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
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.
https://secure.payu.com/boarding/#/form?lang=pl&nsf=false&partnerId=someid
| 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:
|
Regulamin
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:
Rejestracja poprzez API
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:
- Weryfikację merchanta poprzez procedurę KYC (ang. Know-Your-Customer) w tym kontrolę AML (ang. Anti-Money-Laundering).
- Zawieranie umów handlowych, zazwyczaj przez Internet za pośrednictwem panelu merchanta.
- 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ą:
- Firma - osoba prawna (nazwa, adres, identyfikator podatkowy itp.).
- Adres strony URL - adres internetowy sklepu, działalności charytatywnej lub innego płatnego serwisu.
- Sklep - na tym poziomie, zdefiniowane są: waluta płatnicza, saldo oraz szczegóły dotyczące wypłat (wraz z numerem konta merchanta).
- 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.
API rejestracyjne jest również dostępne na środowisku sandbox.
Zanim uzyskasz klucze produkcyjne, możesz użyć poniższych kluczy testowych:
client_id = egmcvdo5
client_secret = 9e0cad643b2d4f0bc1fe1750b9b706ec
Pełen proces rejestracji nowego merchanta w PayU wygląda następująco:
- Uzyskanie ogólnego tokena dostępowego OAuth w celu stworzenia Firmy.
- Stworzenie nowej firmy, otrzymanie publicznego
firmId. - Uzyskanie tokena dostępowego w kontekście danej Firmy dla tworzenia kolejnych encji dla Firmy.
- Stworzenie URL dla Firmy, uzyskanie publicznego
urlId. - Stworzenie Sklepu przypisanego do URL, uzyskanie publicznego
shopId. - Stworzenie POSa dla sklepu, uzyskanie publicznego
posId. - Uzyskanie danych konfiguracyjnych POSa i dodanie ich do twojej paltformy SaaS w celu tworzenia transakcji płatniczych w imieniu merchanta.
- Uzyskanie tokena dostępowego OAuth2 w celu pobrania metod płatności z POSa.
- 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
- Czeska firma
curl -X POST https://secure.snd.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"
}
}'
curl -X POST https://secure.snd.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.
{
"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ń.
Ta metoda uwierzytelniania będzie używana do tworzenia każdego podmiotu w zakresie firmy:
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.
W ścieżce endpointa zawiera się parametr firmId.
curl -X POST 'https://secure.snd.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ść | 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 |
mccJeż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.
{
"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.
W ścieżce endpointu zawiera się parametr firmId.
curl -X POST 'https://secure.snd.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.
{
"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.
W ścieżce endpointa powinien być zawarty parameter shopId.
curl -X POST https://secure.snd.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.
{
"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.
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
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.
curl -X GET 'https://secure.snd.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.
{
"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.
W ścieżce endpointa powinien być zawarty parameter shopId.
curl -X POST 'https://secure.snd.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": "2e629a11-8add-49c5-bf27-a7f684721b86"
}
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.