Payment Facilitator jest specjalnym rodzajem merchanta, który pośredniczy płatnościom i rozlicza swoich submerchantów.
Payment Facilitator (PF) jest zaawansowaną formą partnerstwa, w której PayU przekazuje niektóre ze swoich obowiązków na PF. Do tych obowiązków należą między innymi: wsparcie klienta, rozliczenia (wypłaty), proces weryfikacji czy "Know Your Customer" (KYC).
PF jest konfigurowany jako merchant PayU, jednak może podpisywać własnych merchantów (nazywanych "submerchantami" lub "sponsored merchants")
PayU świadczy usługi płatnicze dla PF i nie zawiera bezpośrednio umów ani nie rozlicza się z submerchantami.
Przetwarzanie płatności jest działalnością regulowaną, dlatego istnieją pewne niezbędne ustalenia prawne i biznesowe, które należy spełnić, zanim PayU będzie mogło przekazać część swoich obowiązków stronie trzeciej.
Szczegółowy opis tych ustaleń wykracza poza zakres niniejszej dokumentacji, ważne jest jednak to, że PayU nie rozlicza, ani nie kontaktuje się bezpośrednio z submerchantami. Mimo to, wszyscy submerchanci w danym momencie muszą być znani PayU, a każda transakcja płatnicza musi być dokonana na rzecz jednego, konkretnego submerchanta wskazanego przez PF pośredniczącego w płatności.
Systemy kart płatniczych takie jak Visa i Mastercard wymagają od PayU (które jest członkiem obu systemów) cyklicznego raportowania submerchantów oraz podawania ich danych podczas autoryzacji płatności kartą.
Dlatego też jest istotne, aby submerchant był zarejestrowany przed dokonaniem jakiejkolwiek płatności, a wymagane dane submerchanta były aktualizowane za każdym razem, gdy ulegną zmianie.
Zanim będziesz mógł rejestrować submerchantów, PayU musi przeprowadzić wstępną konfigurację.
W celu odszukania, rejestracji bądź aktualizacji danych submerchantów musisz najpierw pobrać token OAuth.
Aby uzyskać token możesz użyć jakiegokolwiek REST API POS ID.
Wstępnie wszyscy submerchanci rejestrowani są ze statusem NOT_ACTIVE. Płatności natomiast mogą być pośredniczone jedynie dla submerchantów ze statusem ACTIVE.
Notyfikacje dotyczące zmiany statusu są wysyłane na adres URL podany w parametrze
notifyUrl (szczegóły poniżej).
Aktywacja submerchanta następuje w możliwie najkrótszym czasie, po przeprowadzeniu niezbędnych kontroli i rejestracji w systemach kartowych.
W rzadkich przypadkach, kiedy wykryta zostanie podejrzana aktywność, submerchant może otrzymać status BLOCKED.
W celu rejestracji submerchanta musisz wysłać żądanie HTTP POST z nagłówkiem
Content-Type
application/json na adres URL
https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants. Gdzie parametr
firmId jest publicznym identyfikatorem firmy w formacie
alfnumerycznym.
Identyfikator może zostać pobrany poprzez panel merchanta.
Poniżej znajduje się przykład żądania rejestracji. Objaśnienia parametrów możesz znaleźć w sekcji Parametry.
{
"externalId": "your_submerchant_id",
"notifyUrl": "https://notification-when-status-changes.will-be-sent.here",
"legalName": "Submerchant Ltd",
"dbaName": "superstore.com",
"address": {
"street": "1 Flower St",
"city": "Flowerton",
"postalCode": "00-000",
"countryCode": "PL"
},
"phone": "+48 123 123 123",
"websiteUrl": "https://www.superstore.com",
"mcc": 5999,
"riskClass": "LOW",
"taxId": "123123123",
"representatives": [
{
"name": "Store Owner",
"phone": "+48 123 123 123"
}
],
"legalForm": "SO",
"agreementDate": "2021-03-01",
"payTypeCategories": ["CARD","PBL"]
}
Kod odpowiedzi dla udanego żądania to HTTP 200 (OK).
W przypadku błędów walidacji, zwracany jest kod HTTP 400 (Bad Request) wraz z opisem błędu walidacji określonym w treści odpowiedzi w formacie JSON.
Poniżej znajduje się przykład odpowiedzi na żądanie rejestracji. Objaśnienia parametrów możesz znaleźć w sekcji Parametry.
{
"id": "2578ed95-5b69-411d-9a52-743f80504ebe",
"externalId": "your_submerchant_id",
"status": "NOT_ACTIVE",
"lastUpdated": "2021-03-27T10:57:59+00:00",
"notifyUrl": "https://notification-when-status-changes.will-be-sent.here",
"legalName": "Submerchant Ltd",
"dbaName": "superstore.com",
"address": {
"street": "1 Flower St",
"city": "Flowerton",
"postalCode": "00-000",
"countryCode": "PL"
},
"phone": "+48 123 123 123",
"websiteUrl": "https://www.superstore.com",
"mcc": 5999,
"riskClass": "LOW",
"taxId": "123123123",
"representatives": [
{
"name": "Store Owner",
"phone": "+48 123 123 123"
}
],
"legalForm": "SO",
"agreementDate": "2021-03-01"
}
Za każdym razem, gdy nastąpi zmiana statusu, wysyłane jest powiadomienie w formie
HTTP
POST na adres notifyUrl określony dla danego submerchanta.
Na te żądanie należy odpowiedzieć statusem HTTP 200 (OK) a następnie pobrać aktualny status.
Aby zaktualizować dane submerchanta należy wysłać żądanie HTTP PUT z nagłówkiem
Content-Type
application/json na adres URL
https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}.
Gdzie parametr {firmId} jest identyfikatorem firmy w formacie
alfanumerycznym (widoczny w panelu merchanta), a {submerchantId}
jest identyfikatorem submerchanta nadanym przez PayU w trakcie jego rejestracji.
Odpowiedź i kody statusów HTTP zwracane po użyciu tego endpointu są takie same jak te zawarte w sekcji Rejestracja.
Żądanie aktualizacji danych jest podobne jak te przesyłane w celu rejestracji submerchanta.
Pamiętaj, że zmiany parametrów: mcc, riskClass,
representatives spowodują zmianę statusu submerchanta na
BLOCKED do czasu przeprowadzenia dodatkowych kontroli.
Poniżej znajduje się przykład żądania rejestracji. Objaśnienia parametrów możesz znaleźć w sekcji Parametry.
{
"externalId": "your_submerchant_id",
"notifyUrl": "https://notification-when-status-changes.will-be-sent.here",
"legalName": "Submerchant Ltd",
"dbaName": "superstore.com",
"address": {
"street": "1 Flower St",
"city": "Flowerton",
"postalCode": "00-000",
"countryCode": "PL"
},
"phone": "+48 123 123 123",
"websiteUrl": "https://www.superstore.com",
"taxId": "123123123",
"legalForm": "SO",
"agreementDate": "2021-03-01"
}
Aby pobrać dane submerchanta należy wysłać żądanie HTTP GET na adres URL
https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}.
Gdzie {firmId} jest identyfikatorem firmy w formacie
alfanumerycznym (widoczny w panelu merchanta), a {submerchantId}
jest identyfikatorem submerchanta nadanym przez PayU w trakcie jego rejestracji.
W przypadku udanego żądnia zwrócony zostanie kod HTTP 200 (OK).
Otrzymywana w tym przypadku odpowiedź jest taka sama jak ta w sekcji Rejestracja.
Innym możliwym kodem odpowiedzi jest HTTP 404 (Not Found).
| Parametr | Opis | Wymagane |
|---|---|---|
| id | Identyfikator nadany przez PayU wymagany w OrderCreateRequest. | Występuje jedynie w odpowiedzi |
| status | Status submerchanta. Możliwe wartości: NOT_ACTIVE, ACTIVE, BLOCKED. | Występuje jedynie w odpowiedzi |
| lastUpdated | Data stworzenia zasobu bądź jego ostatniej aktualizacji (jeżeli dotyczy) w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss±hh:mm, e.g. "2021-03-27T10:57:59+00:00"). | Występuje jedynie w odpowiedzi |
| notifyUrl | Pole określające na jaki adres URL będą wysyłane Notyfikacje dotyczące zmiany statusu submerchanta. | Tak |
| externalId | Identyfikator nadany submerchantowi przez PF. | Tak |
| legalName | Pełna nazwa prawna (przy rejestracji). | Tak |
| dbaName | Zwykle uproszczony, adres strony internetowej, która jest rozpoznawalna przez klienta (np. wyświetlona na wyciągu z karty). | Tak |
| address | Sekcja zawierająca adres submerchanta. | Tak |
| address.street | Nazwa ulicy razem z numerem domu/mieszkania (jeżeli dotyczy). | Tak |
| address.postalCode | Kod pocztowy | Tak |
| address.city | Miasto | Tak |
| address.countryCode | Kod kraju - musi to być prawidłowy dwuliterowy kod w formacie ISO 3166-1. | Tak |
| phone | Kontaktowy numer telefonu. | Tak |
| websiteUrl | Aktualny dres URL strony submerchanta. | Tak |
| mcc | Prawidłowy kod MCC submerchanta ustalony przez PF podczas procesu KYC. | Tak |
| payTypeCategories | Tablica enumerowanych wartości: CARD, PBL. Wymagana min. 1 wartość. | Nie (domyślnie: CARD) |
| riskClass | Klasa ryzyka nadana przez PF (bazującego na wymaganiach podanych przez PayU). Możliwe wartości: LOW, NORMAL, HIGH. | Tak |
| taxId | Identyfikator podatkowy (np. w Polsce numer NIP) lub identyfikator biznesowy (np. w Czechach IČ). | Tak |
| representatives | Tablica zawierająca dane reprezentatów lub właścicieli przedsiębiorstwa (w zależności od formy prawnej). Wymagana jest co najmniej jedna osoba. | Tak |
| representatives.name | Imię reprezentanta. | Tak |
| representatives.phone | Kontaktowy numer telefonu do reprezentanta. | Tak |
| legalForm | Wartość słownikowa - typ osoby prawnej. Wartości dla poszczególnego pochodzenia można znaleźć tutaj. | Tak |
| agreementDate | Data (format: yyyy-mm-dd, e.g. "2021-05-25") kiedy zostało podpisane porozumienie pomiędzy PF a submerchantem (wymagane przez Visa dla celów raportowych). | Tak |
submerchant do OrderCreateRequest:
buyer z imieniem, adresem e-mail i adresem dostawy;threeDsAuthentication z sekcją browser i
billingAddress;payMethods z pełnymi danymi kartowymi (możesz także użyć
tokenizacji).Więcej informacji na temat pól użytych w poniższym przykładzie znajdziesz w sekcjach Tokenizacja kart i 3DS 2
{
"continueUrl": "https://after.payment.com/thankyoupage",
"notifyUrl": "https://your.eshop.com/notify",
"customerIp": "216.72.35.5",
"merchantPosId": "1111111",
"submerchant": {
"id": "2578ed95-5b69-411d-9a52-743f80504ebe"
},
"description": "Order with submerchant ID",
"currencyCode": "PLN",
"totalAmount": 300,
"products": [
{
"name": "a product",
"unitPrice": 300,
"quantity": 1
}
],
"buyer": {
"firstName": "John",
"lastName": " ",
"phone": "+48 555555555",
"email": "john@doe.pl",
"delivery": {
"street": "Delivery St. 1",
"postalCode": "55033",
"city": "Delivery Town",
"state": "30",
"countryCode": "PL"
}
},
"threeDsAuthentication": {
"browser": {
"acceptHeaders": "*/*",
"screenWidth": "1536",
"javaEnabled": false,
"timezoneOffset": "-120",
"screenHeight": "864",
"requestIP": "216.72.35.5",
"language": "en",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0",
"colorDepth": "24"
},
"cardholder": {
"billingAddress": {
"street": "Billing St. 1",
"postalCode": "33055",
"city": "Billington",
"state": "30",
"countryCode": "PL"
}
}
},
"payMethods": {
"payMethod": {
"card": {
"number": "4444333322221111",
"expirationMonth": "02",
"expirationYear": "2025",
"cvv": "536"
}
}
}
}