Payment Facilitator

Introduction

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.

Uzgodnienia i obowiązki

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.

Submerchanci

Zanim submerchanci mogą zostać rejestrowani, konieczna jest konfiguracja po stronie PayU.

W celu odszukania, rejestracji bądź aktualizacji danych submerchantów musisz najpierw pobrać token OAuth.

Notatka

Aby uzyskać token możesz użyć jakiegokolwiek REST API POS ID.

Rejestracja różni się w zależności o typów płatności wskazanych dla danego submerchanta. Obecnie możliwe jest wybranie następujących typów: CARD i PBL (przelewy online). Typy należy wskazać w polu payTypeCategories. Jeśli pole to nie zostanie przekazane, domyślna wartość to CARD.

Wszyscy submerchanci mają parametr status. W zależności od tego parametru, niektóre lub wszystkie płatności mogą być zablokowane.

Możliwe statusy submerchantów

Status	Możliwe płatności
ACTIVE	Wszystkie płatności możliwe.
NOT_ACTIVE	Płatności CARD niemożliwe, PBL możliwe.
BLOCKED	Żadne płatności niemożliwe.

W rzadkich przypadkach, kiedy wykryta zostanie podejrzana aktywność, submerchant może otrzymać status BLOCKED. Pozostałe statusy ustawiane są na podstawie danych submerchanta, jak wskazano w tabeli poniżej, pokazującej typy rejestracji w zależności o wartości payTypeCategory.

Wymagalność pól w zależności od statusu

payTypeCategories	Wymagalność danych	Status po rejestracji
CARD, PBL	Wszystkie pola wymagane.	NOT_ACTIVE
CARD	Wszystkie pola wymagane.	NOT_ACTIVE
PBL	Niektóre pola niewymagane.	ACTIVE

Szczegóły parametrów znajdziesz w sekcji Payment Facilitator w naszej referencji API.

Notyfikacje dotyczące zmiany statusu są wysyłane na adres URL podany w parametrze notifyUrl.

Aktywacja submerchantów jest przeprowadzana jak tylko zakończone zostaną niezbędne weryfikacje wymagane przez organizacje płatnicze.

Rejestracja submerchantów

W celu rejestracji submerchanta musisz wysłać żądanie HTTP POST na endpoint https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants. Gdzie parametr firmId jest publicznym identyfikatorem firmy w formacie alfnumerycznym.

Notatka

Parametr firmId

Identyfikator firmId znajdziesz w panelu menedżerskim.

Poniżej znajduje się przykład ciała żądania rejestracji z wszystkimi dostępnymi polami.

Przykład ciała żądania rejestracji

{
  "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"]
}

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

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.

Przykład odpowiedzi na żądanie rejestracji

{
  "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",
  "payTypeCategories": ["CARD", "PBL"]
}

Powiadomienia

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.

Aktualizowanie danych submerchanta

Aby zaktualizować dane submerchanta należy wysłać żądanie HTTP PUT na endpoint https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}. Gdzie parametr firmId jest identyfikatorem firmy w formacie alfanumerycznym (widoczny w panelu menedżerskim), a submerchantId jest identyfikatorem submerchanta nadanym przez PayU w trakcie jego rejestracji.

Odpowiedź i kody statusów HTTP zwracane po użyciu tego endpointa są takie same jak te zawarte w sekcji Rejestracja submerchantów.

Żądanie aktualizacji danych jest podobne jak te przesyłane w celu rejestracji submerchanta.

Pamiętaj, że zmiany parametrów: mcc, riskClass, representatives lub dodanie CARD do payTypeCategories spowodują zmianę statusu submerchanta na NOT_ACTIVE do czasu przeprowadzenia dodatkowej weryfikacji. Przy czym taka zmiana statusu nie blokuje płatności typu PBL.

Notatka

Zmiana statusu na NOT_ACTIVE nie zablokuje płatności PBL.

Przykład ciała żądania aktualizacji danych submerchanta

{
  "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",
  "payTypeCategories": ["CARD", "PBL"]
}

Szczegóły parametrów znajdziesz w sekcji Update Submerchants Data w naszej referencji API.

Pobieranie danych submerchanta

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 submerchanta należy wysłać żądanie HTTP GET na endpoint https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}. Gdzie firmIdjest identyfikatorem firmy w formacie alfanumerycznym (widoczny w panelu menedżerskim), asubmerchantId` jest identyfikatorem submerchanta nadanym przez PayU w trakcie jego rejestracji.

W przypadku udanego żądnia zwrócony zostanie kod **HTTP 200 (OK). W odpowiedzi na błędne żądanie zostanie zwrócony kod **HTTP 404 (Not Found).

Odpowiedź zwracana po użyciu tego endpointa są takie same jak te zawarte w sekcji Rejestracja submerchantów.

Rozszerzenie integracji

Aby móc pośredniczyć płatnościom jako Payment Facilitator musisz zintegrować się z PayU poprzez protokół REST API, a następnie rozszerzyć standardowe zamówienie o zakres przesyłanych danych specyficzny dla PF:

W przypadku płatności innych niż kartą, takich jak przelewy online pay-by-link (PBL), zapoznaj się z sekcją Create an Order w naszej referencji API. W tej sekcji znajdziesz przykład obiektu payMethods.

Notatka

Zwróć uwagę na różnicę między wartością PBL jako payMethods.payMethod.type i PBL jako payTypeCategories.

Pierwszy oznacza metodę płatności dostępną za pośrednictwem linku (w tym przekierowanie do strony płatności kartą hostowanej przez PayU), drugi oznacza alternatywne metody płatności określane jako przelewy pay-by-link. Te ostatnie obejmują następujące metody: czeskie PBL, polskie PBL, słowackie PBL.

W przypadku, gdy sekcja payMethod użyta dla danego submerchanta nie pasuje do pola payTypeCategories tego submerchanta, zwrócona zostanie odpowiedź ze statusem HTTP 400 i z polem status.codeLiteral ustawionym na SUBMERCHANT_PAYTYPE_NOT_ALLOWED.

Poniżej przedstawiono przykładowe żądanie płatności kartą. Oprócz pola submerchant, zwróć uwagę na inne dane specyficzne dla płatności kartą:

• obiekt buyer z imieniem, adresem e-mail i adresem dostawy,
• obiekt threeDsAuthentication z sekcją browser i billingAddress,
• obiekt payMethods z pełnymi danymi kartowymi (możesz także użyć tokenizacji).

Aby dowiedzieć się więcej na temat danych z poniższego żądania, zapoznaj się ze stronami Tokenizacja kart i 3DS 2 (SCA).

Przykład ciała żądania płatności kartą jako PF

{
  "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"
      }
    }
  }
}