Payment Facilitator

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.

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

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

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 (zob. Parametry w celu sprawdzenia szczegółowego omówienia pól i ich walidacji).

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

Aktywacja submerchantów jest przeprowadzana tak szybko jak to możliwe, kiedy przeprowadzone zostaną niezbędne weryfikacje wymagane przez organizacje płatnicze.

Żą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,
  "debtRepayment": false,
  "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,
  "debtRepayment": false,
  "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 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.

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

Aby móc pośredniczyć płatnościom jako Payment Facilitator musisz zintegrować się z PayU poprzez protokół REST API. Muisz także rozszerzyć zakres przesyłanych danych o specyficzny dla PF obiekt submerchant i zawsze określać metodę płatności za pomocą obiektu card lub pola payMethod.value.

W przypadku płatności innych niż kartą, takich jak przelewy online pay-by-link (PBL), zapoznaj się z sekcją Transparentna integracja, aby zobaczyć przykład obiektu payMethods.

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

Pierwsza oznacza metodę płatności dostępną za pośrednictwem linku (w tym przekierowanie do strony płatności kartą hostowanej przez PayU). Druga 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ą:

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