Meest Paywall poprzez przekierowanie

Integracja z Paywallem przy użyciu przekierowania HTTP.

Opis działania

Meest Paywall jest możliwy do obsłużenia poprzez przekierowanie na bezpieczną stronę płatności. Klientowi zostanie wyświetlona strona, w której będzie mógł wybrać metodę płatności i przejść cały proces obciążenia. Następnie zostanie przekierowany z powrotem na stronę sprzedawcy.

Krok 1 — Utwórz sesję płatności

Nim klient przejdzie do procesu płatności, sprzedawca musi zainicjować nową sesję płatności w systemie MeestPay. Aby to zrobić, musi wywołać z serwera zapytanie POST na ścieżkę /api/payment_sessions. Szczegółowe informacje na temat inicjacji sesji płatności znajdują się w podrozdziale Dokumentacja API poniżej.

POST/api/payment_sessions

Przykładowy CURL

POST /api/payment_sessions

curl -i https://sandbox.meestpay.com/api/payment_sessions \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.meest.v3+json' \
  -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
  -d '{
    "amount": "10.00",
    "currency": "PLN",
    "external_id": "example123",
    "description": "New payment session",
    "user_profile": {
      "first_name": "John",
      "last_name": "Kowal",
      "email": "example@example.pl",
      "external_id": "example123"
    },
    "redirect_url": "https://www.example.com"
  }'

Przykładowa odpowiedź

201 Created

{
  "id": "ps_9682gcqFSqvN8oAZV",
  "amount": "10.00",
  "currency": "PLN",
  "description": "New payment session",
  "state": "new",
  "created_at": 1723145262,
  "external_id": "example123",
  "user_profile": {
    "id": "up_968O86wHhRX9OLm71",
    "external_id": "example123"
  },
  "redirect_url": "http://sandbox.meestpay.com/meest/paywall/ps_9682gcqFSqvN8oAZV"
}

Krok 2 — Przekieruj na stronę płatności

Po otrzymaniu odpowiedzi należy przekierować użytkownika na otrzymany redirect_url. Klientowi wyświetli się strona płatności, w której dokona wyboru metody płatności oraz przejdzie przez cały proces obciążenia.

Krok 3 — Zwrócenie rezultatu płatności

Po udanej próbie płatności następuje automatyczne przekierowanie użytkownika na przypisany do sesji płatności adres URL (wysłany w request redirect_url). W przypadku nieudanej płatności użytkownik zostanie cofnięty do kroku poprzedniego — czyli ponownego wyboru metody płatności.

Krok 4 — Szczegółowe dane sesji płatności

Po każdej próbie płatności, bez względu na jej wynik końcowy, wysłany jest back request z aktualnym stanem sesji płatności (w tym samym formacie co odpowiedź na zapytanie Odpytanie o stan sesji płatności).

Zatwierdzenie płatności przez back request

Faktyczne zatwierdzenie informacji o udanej płatności powinno być dokonane wyłącznie na podstawie otrzymanego back requestu (webhook), a nie jedynie na podstawie przekierowania użytkownika.

Dokumentacja API

Szczegółowe opisy endpointów i parametrów sesji płatności.

Utworzenie sesji płatności

Sesja płatności zawiera wszystkie podstawowe informacje o planowanym obciążeniu. Pojedyncza sesja pozwala na wykonywanie wielu płatności różnymi metodami — aż do pierwszej zakończonej sukcesem. Tworząc nową sesję, należy jednocześnie utworzyć nowy profil użytkownika lub skorzystać z istniejącego.

Profil użytkownika

Pojedynczy profil powinien być odzwierciedleniem konta użytkownika w sklepie. Profil przechowuje dane użytkownika i pozwala zapisywać karty płatnicze oraz zapamiętywać ostatnio wybrane metody płatności.

POST/api/payment_sessions

Parametry żądania

Pole	Typ	Opis	Wymagane
amount	number	Kwota transakcji, liczba dziesiętna (np. 123.45, 0)	Tak
currency	string	Waluta ISO 4217, 3 znaki (np. PLN, EUR)	Tak
description	string	Opis sesji płatności, 5–99 znaków	Tak
external_id	string	Własny, unikalny identyfikator sesji płatności, max 50 znaków	Tak
user_profile	object / string	Nowy profil użytkownika (obiekt) lub identyfikator istniejącego (string). Wymagany gdy nie podano external_user_profile_id	Nie
external_user_profile_id	string	Zewnętrzny identyfikator istniejącego profilu użytkownika. Wymagany gdy nie podano user_profile	Nie
locale	string	Język sesji płatności. Dozwolone wartości: pl, en, uk, ru	Nie
redirect_url	string	Adres URL, na który przekierowany zostanie użytkownik po zakończeniu płatności	Tak

Parametry obiektu `user_profile`

Pole	Typ	Opis	Wymagane
first_name	string	Imię użytkownika, max 50 znaków	Tak
last_name	string	Nazwisko użytkownika, max 50 znaków	Tak
email	string	Adres e-mail użytkownika, 3–50 znaków	Nie
external_id	string	Własny, unikalny identyfikator profilu użytkownika, max 50 znaków	Tak

Przykładowy CURL

POST /api/payment_sessions

curl -i https://sandbox.meestpay.com/api/payment_sessions \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.meest.v3+json' \
  -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
  -d '{
    "amount": 10,
    "currency": "PLN",
    "external_id": "example123",
    "description": "docs test charge init",
    "external_user_profile_id": "12312341",
    "redirect_url": "https://www.example.com"
  }'

Przykładowa odpowiedź

201 Created

{
  "id": "ps_9682gcqFSqvN8oAZV",
  "amount": "10.25",
  "currency": "PLN",
  "description": "New payment session",
  "state": "new",
  "created_at": 1723145262,
  "external_id": "example123",
  "user_profile": {
    "id": "up_968O86wHhRX9OLm71",
    "external_id": "456480516135"
  },
  "redirect_url": "http://sandbox.meestpay.com/meest/paywall/ps_9682gcqFSqvN8oAZV"
}

Parametry odpowiedzi

Parametry odpowiedzi są identyczne jak w zapytaniu Odpytanie o stan sesji płatności opisanym poniżej.

Odpytanie o stan sesji płatności

Aby otrzymać pełne informacje o pojedynczej sesji płatności, wykonaj poniższe zapytanie.

GET/api/payment_sessions/(:id)

Parametry zapytania

Pole	Typ	Opis	Wymagane
(:id)	string	URL param — identyfikator sesji płatności lub zewnętrzny identyfikator sesji	Tak
id_name	string	Wartość "external_id" — wymagane gdy (:id) jest zewnętrznym identyfikatorem	Nie

Parametry odpowiedzi

Pole	Typ	Opis	Wymagane
id	string	Identyfikator sesji płatności	Nie
amount	string	Kwota transakcji, liczba dziesiętna	Nie
currency	string	Waluta ISO 4217, 3 znaki	Nie
description	string	Opis sesji płatności	Nie
state	string	Stan sesji: "new" (nowa) lub "executed" (zrealizowana)	Nie
created_at	integer	Czas utworzenia sesji w formacie unixowym	Nie
used_payment_means	string	Wykorzystana metoda płatności	Nie
external_id	string	Własny identyfikator sesji, max 50 znaków	Nie
user_profile	object	Identyfikatory profilu użytkownika (id oraz external_id)	Nie
redirect_url	string	Link umożliwiający wyświetlenie strony płatności (przeznaczony do testowania)	Nie
successful_payment	object	Informacja o płatności zakończonej sukcesem, zawierająca id, state oraz obiekt card	Nie
attempts	array	Informacje o płatnościach zakończonych niepowodzeniem lub niezakończonych (id, state, card)	Nie
card	object	Dane karty zagnieżdżone w successful_payment lub attempts. Null dla metod innych niż karta	Nie

Przykład odpowiedzi

200 OK

{
  "id": "ps_9cegY29viJZtaS0RH",
  "amount": "123.45",
  "currency": "PLN",
  "description": "Example payment session",
  "state": "executed",
  "created_at": 1760349914,
  "used_payment_means": "card",
  "external_id": "example123",
  "user_profile": {
    "id": "user_profile_id",
    "external_id": "example123"
  },
  "redirect_url": "https://www.example.com",
  "successful_payment": {
    "id": "pay_9ceSWynm1zVYo69O",
    "state": "executed",
    "card": {
      "company": "VI",
      "last4": "0000",
      "year": 2030,
      "month": 1,
      "first_name": "John",
      "last_name": "Doe",
      "authorized": null,
      "created_at": 1760350040,
      "bin": "000000"
    }
  },
  "attempts": [
    {
      "id": "pay_9ceqfMER8gor7s3S",
      "state": "rejected",
      "card": {
        "company": "VI",
        "last4": "0000",
        "year": 2030,
        "month": 1,
        "first_name": "John",
        "last_name": "Doe",
        "authorized": null,
        "created_at": 1760350040,
        "bin": "000000"
      }
    }
  ],
  "subject": "payment_session"
}

Odpytanie o stan wielu sesji płatności

Aby pobrać pełne informacje o wielu sesjach płatności, wykonaj poniższe zapytanie.

GET/api/payment_sessions

Parametry zapytania

Pole	Typ	Opis	Wymagane
page	integer	Numer strony wyników, domyślnie 1	Tak
per	integer	Liczba sesji na stronie, domyślnie 30	Tak
user_profile_id	string	Identyfikator profilu użytkownika, do którego należą sesje	Nie
external_user_profile_id	string	Zewnętrzny identyfikator profilu użytkownika	Nie

Parametry odpowiedzi

Odpowiedź zawiera pole count (liczba zwróconych obiektów) oraz pole payment_sessions — tablicę obiektów sesji płatności w tym samym formacie co zapytanie o pojedynczą sesję.

Meest Paywall poprzez przekierowanie

Krok 1 — Utwórz sesję płatności

Przykładowy CURL

Przykładowa odpowiedź

Krok 2 — Przekieruj na stronę płatności

Krok 3 — Zwrócenie rezultatu płatności

Krok 4 — Szczegółowe dane sesji płatności

Dokumentacja API

Utworzenie sesji płatności

Parametry żądania

Parametry obiektu user_profile

Przykładowy CURL

Przykładowa odpowiedź

Odpytanie o stan sesji płatności

Parametry zapytania

Parametry odpowiedzi

Przykład odpowiedzi

Odpytanie o stan wielu sesji płatności

Parametry zapytania

Parametry obiektu `user_profile`