Poniższa instrukcja dotyczy konfiguracji płatności marketplace.
Instrukcja obsługi płatności marketplace z informacjami, jak obsługiwać płatności marketplace, znajdziesz tutaj.
Tworzenie transakcji
Link do dokumentacji API jest dostępny tutaj.
Przygotowanie do utworzenia transakcji
Po uruchomieniu funkcjonalności marketplace dla Twojego konta, przygotuj dane do utworzenia transakcji:
- identyfikatory ID sprzedawców,
- identyfikator ID dodanego wcześniej POS.
Identyfikatory danych sprzedawców uzyskasz za pomocą metody listującej konta sprzedawców przypisanych do Twojego marketplace GET /accounts. Natomiast identyfikator POS-a, na który chcesz założyć transakcję, znajdziesz za pomocą metody /accounts/pos, która listuje POS-y Twojego marketplace.
Żądanie utworzenia transakcji
Posiadając potrzebne identyfikatory, możesz wysłać żądanie metodą POST na adres /marketplace/v1/transaction. Pełen opis parametrów oraz ich wartości znajdziesz w dokumentacji API online partnera.
Po poprawnym przetworzeniu żądania, system wysyła na adres e-mail płatnika wiadomość o założeniu nowej transakcji.
Przykładowe żądanie
Poniżej znajdziesz przykładowe żądanie tworzące zamówienie z dwoma transakcjami podrzędnymi dla sprzedawców o identyfikatorach 01G6WAPZFNNX4CXBPKQH5MYD4R oraz 01GGA49YQ9NGN0YQV0HW1VHDV3 na łączną kwotę 55 złotych.
{
"currency": "PLN",
"description": "Example description",
"hiddenDescription": "Example hidden description",
"languageCode": "PL",
"preSelectedChannelId": null,
"pos": {
"id": "01G6WAS5MNGQ2X728AW53D8JPR"
},
"billingAddress": {
"email": "[email protected]",
"name": "Name",
"phone": "660660660",
"street": "Street",
"postalCode": "12-123",
"city": "City",
"country": "PL",
"houseNo": "1",
"flatNo": "23"
},
"childTransactions": [
{
"amount": 1500,
"description": "Item no1",
"merchant": {
"id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
}
},
{
"amount": 4000,
"description": "Item no2",
"merchant": {
"id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
}
}
],
"transactionCallbacks": [
{
"type": 1,
"value": "https://success.url.com"
},
{
"type": 2,
"value": "https://error.url.com"
}
]
}
Odpowiedź
Jeśli transakcja została utworzona prawidłowo, w odpowiedzi otrzymasz identyfikator i tytuł transakcji oraz link do panelu transakcyjnego.
{
"transactionId": "01G5EDNEPPNWBJAX8AR5QAMGVA",
"title": "M-DW123DWX",
"paymentUrl": "https://payment-panel.example/01G5EDNEPPNWBJAX8AR5QAMGVA"
}
Powyższe dane możesz wykorzystać do opłacenia transakcji za pomocą API lub przekierować płatnika na zwrócony link do panelu transakcyjnego. Opisy do powyższej oraz innych możliwych odpowiedzi dla żądania utworzenia transakcji znajdziesz w dokumentacji API.
Opłacanie transakcji
Dostępność metod płatności
Dostępne metody płatności zależą od ustawień sprzedawców przypisanych do Twojego marketplace. Jako dostępne możesz wyświetlić kanały, które są włączone na koncie sprzedawcy.
Ważne:w ramach funkcjonalności marketplace możesz korzystać z następujących metod płatności: BLIK, przelew Pay By Link, Raty Pekao i Alior Raty oraz płatności odroczone Twisto.
W przypadku transakcji koszyka płatności dla klienta końcowego dostępne są tylko te metody płatności, które są wspólne dla wszystkich sprzedawców w ramach danej transakcji.
Wyświetlić kanały płatności dostępne dla sprzedawcy lub grupy sprzedawców możesz za pomocą metody /marketplace/v1/bank-groups.
Możliwości opłacenia transakcji
Po wysłaniu żądania utworzenia otrzymasz w odpowiedzi dane niezbędne do opłacenia transakcji – identyfikator transakcji oraz link do panelu transakcyjnego.
Panel transakcyjny
Jeśli decydujesz się na wykorzystanie linku, przekieruj na niego płatnika. W następnym kroku płatnik w panelu transakcyjnym Tpay wybierze kanał płatności oraz będzie mieć możliwość opłacenia transakcji.
Ważne: w przypadku przesłania identyfikatora kanału w żądaniu utworzenia transakcji (parametr preSelectedChannelId), system pominie krok z wyborem kanału przez płatnika.
Po dokonanej przez płatnika próbie płatności system przekieruje go na przesłany w żądaniu utworzenia adres URL, przekazywany w transactionCallbacks. Możesz ustawić adres dla nieudanego opłacenia (ERROR_URL) lub płatności zakończonej sukcesem (SUCCESS_URL).
API
Do opłacenia transakcji przez API wykorzystaj otrzymany identyfikator transakcji.
Odpowiednie dane prześlesz korzystając z metody /marketplace/v1/transaction/{id}/pay. W przypadku poprawnej odpowiedzi możesz uzyskać dane dodatkowe, np. dla kart płatniczych może być to link do 3DS, na który przekierujesz płatnika.
Poprawny rezultat nie gwarantuje właściwej realizacji transakcji: poczekaj na asynchroniczne powiadomienie otrzymane od Tpay – to ostateczne potwierdzenie płatności.
Powiadomienia
Oprócz wspomnianych wcześniej adresów URL do przekierowania płatnika, w transactionCallbacks możesz przekazać dwa inne typy callbacku: NOTIFICATION_URL oraz NOTIFICATION_EMAIL.
NOTIFICATION_URL odpowiada za wysłanie na przekazany adres URL powiadomienia o realizacji transakcji, które jest ostatecznym potwierdzeniem zakończenia płatności z sukcesem.
NOTIFICATION_EMAIL zawierający adres e-mail sprzedawcy wykorzystujemy do wysłania powiadomienia o potwierdzeniu płatności.
Zwroty
Zwrot do transakcji możesz zlecić wyłącznie przez udostępnione Ci API. Możesz zlecić zwrot części środków lub całej płatności.
Zwrot możesz zlecić przesyłając podział per konto sprzedawcy (analogicznie do danych użytych przy tworzeniu transakcji) lub bez danych - zwrócisz wówczas całą transakcję.
Podczas transakcji wykonujemy odpowiednie sprawdzenia, np. czy nie przekroczono maksymalnej kwoty zwrotu, która wynosi 100% wpłaconej kwoty, z podziałem na danych sprzedawców.
Obciążenie sald sprzedawców, dla których zlecany jest zwrot, działa tak samo jak w przypadku pojedynczych transakcji. Kwotę potrzebną na pokrycie zwrotu oraz prowizję za operację pobieramy z salda sprzedawcy. Jeśli sprzedawca nie ma wystarczających środków na saldzie, odrzucimy zlecenie zwrotu.
Metoda API pozwalająca na zlecanie zwrotów:
Endpoint API:/marketplace/v1/transaction/{id}/refundgdzie {id}to identyfikator transakcji marketplace zwrócony przez system w momencie jej tworzenia.
Przykładowy request body zwracający 20 zł z transakcji sprzedawcy 1:
{
"childTransactions": [
{
"merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
"amount": 2000
}
]
}
Przykładowy request body zwracający 20 zł z transakcji sprzedawcy 1 oraz 10 zł z transakcji sprzedawcy 2:
{
"childTransactions": [
{
"merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
"amount": 2000
},
{
"merchantId": "01G6WAPZFNNX4CXBPKQH5MYD4R",
"amount": 1000
}
]
}
Przykładowy request body zwracający całą transakcję:
{}
Anulowanie transakcji
Transakcję marketplace możesz anulować pod warunkiem, że płatnik nie dokonał już płatności. Do wykonania tej akcji użyj metody/marketplace/v1/transaction/{id}/cancel – jej dokładny opis znajdziesz w API online. Poprawna odpowiedź na żądanie anulacji gwarantuje uniemożliwienie jej opłacenia.
W przypadku gdy dokonałeś anulacji transakcji, podczas procesu opłacania przez płatnika z wykorzystaniem metody z asynchronicznym powiadomieniem o realizacji – anulujemy płatność i zwrócimy pieniądze na konto płatnika.
