Payment Facilitator

1 Wstęp

Payment Facilitator jest specjalnym rodzajem merchanta, który pośredniczy płatnościom i rozlicza swoich submerchantów.

Definicja

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.

2 Submerchanci

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.

2.1 Rejestracja

Żądanie rejestracji submerchanta

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

Odpowiedź na żądanie rejestracji

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

2.2 Notyfikacje

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.

2.3 Aktualizacja

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

2.4 Pobranie danych

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).

2.5 Parametry

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

3 Usprawnienia płatności

Aby móc pośredniczyć płatnościom jako Payment Facilitator musisz zintegrować się z PayU poprzez protokół REST API, a następnie rozszerzyć zakres przesyłanych danych o specyficzny dla PF obiekt 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"
            }
        }
    }
}