Marketplace

Program Partnerski to forma współpracy z firmami oferującymi różnorodne usługi, takie jak wdrożenia rozwiązań e-commerce u swoich klientów czy tworzenie własnych rozwiązań marketplace. W ramach programu Partner poleca usługi Tpay i zarabia określony procent od każdej faktury poleconego przez siebie klienta.

Aby korzystać z Marketplace Tpay, musisz być w Programie Partnerskim Tpay. Jeśli nie masz jeszcze statusu partnera – dowiedz się, jak dołączyć do Programu.

Instrukcję uruchamiania i obsługi płatności marketplace Tpay w Panelu Partnera znajdziesz tutaj.

Dostępne metody płatności

W ramach marketplace Tpay dostępne są poniższe metody płatności:

• BLIK.
• Przelew online (PayByLink).
• Płatności ratalne.
• Płatności odroczone.

Autoryzacja

Jako Partner z poziomu swojego Panelu Partnera w zakładce API > Partner API możesz wygenerować dostępy do rejestracji sprzedawców po API.

Zakładka pozwoli Ci na wygenerowanie dostępów do komunikacji po API, pozwalające na dostęp do metod accounts i marketplace.

Aby wygenerować klucze dostępu do API, należy kliknąć przycisk Dodaj nowy klucz. Zostaną wygenerowane:

• Client ID.
• Secret.

W celu autoryzacji w API sprawdź instrukcję Pierwsze kroki > Autoryzacja

Transakcja

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 GET /accounts/pos, która listuje POS-y Twojego marketplace.

Posiadając potrzebne identyfikatory, możesz wysłać żądanie metodą POST na adres:

https://api.tpay.com/marketplace/v1/transaction.

W zapytaniu określ następujące parametry:

Podstawowe body żądania powinno wyglądać następująco:

{
  "currency": "PLN",
  "description": "Example description",
  "hiddenDescription": "Example hidden description",
  "languageCode": "PL",
  "pos": {
    "id": "01G6WAS5MNGQ2X728AW53D8JPR"
  },
  "billingAddress": {
    "email": "[email protected]",
    "name": "Name"
  },
  "childTransactions": [
    {
      "amount": 1500,
      "description": "Item no1",
      "merchant": {
        "id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
      }
    },
    {
      "amount": 4000,
      "description": "Item no2",
      "merchant": {
        "id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
      }
    }
  ]
}

Po wysłaniu żądania otrzymasz w odpowiedzi schemat TransactionCreated.

Najważniejsze parametry odpowiedzi:

Po poprawnym przetworzeniu żądania, system wysyła na adres e-mail płatnika wiadomość o założeniu nowej transakcji.

Przekieruj płatnika na panel transakcyjny

Przekieruj płatnika na URL zawarty w odpowiedzi w polu paymentUrl.

Następnie płatnik na panelu transakcyjnym wybiera formę, w jakiej chce opłacić transakcję, i ją realizuje.

Autoryzacja płatności

W niektórych formach płatności występują dodatkowe autoryzacje, które płatnik musi zatwierdzić lub zrealizować, takie jak:

• Autoryzacja kodu BLIK
• Autoryzacja 3D Secure
• Autoryzacja Visa Mobile

Więcej informacji znajdziesz w dokumentacji poszczególnych metod płatności.

Płatnik zostanie przekierowany na stronę sukcesu lub porażki

Gdy płatność zostanie zakończona, płatnik zostanie przekierowany na stronę sukcesu (success page) lub stronę porażki (error page) w zależności od tego, czy transakcja się udała.

Oczekuj notyfikacji o udanej transakcji

Płatność w naszym systemie odbywa się w pełni procesem asynchronicznym.

Asynchroniczność oznacza, że proces płatności nie jest wykonywany natychmiastowo ani w znanym z góry okresie. Mimo że większość metod płatności wystosowuje powiadomienia w ciągu kilku-kilkunastu minut po założeniu transakcji, status transakcji może zmienić się w każdej chwili do upływu miesiąca od założenia transakcji.

Gdy status transakcji zmieni się na opłaconą, poinformujemy Twój system o udanej płatności za pomocą notyfikacji. Więcej informacji o webhookach transakcji marketplace znajdziesz tutaj.

Transakcja on-site

W niektórych metodach płatności istnieje możliwość integracji on-site. W celu opłacenia transakcji on-site wykorzystaj endpoint tworzenia transakcji, a następnie, zamiast przekierować płatnika na panel transakcyjny, posłuż się parametrem transactionId wysyłając żądanie POST na adres:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/pay

Umieść {transactionId} w adresie URL np.:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/pay

W zapytaniu możesz określić następujące parametry:

Transakcja zawierająca opis produktów

Opcjonalnie, razem z transakcją możesz przekazać krótką listę produktów z koszyka klienta, by ułatwić odróżnienie transakcji podczas zwrotu w Twojej implementacji.

Lista produktów powinna być przyporządkowana do dostarczającego je sprzedawcy i przekazana w kluczu products transakcji podrzędnej.

Podstawowe body żądania z listą produktów powinno wyglądać następująco:

{
  "currency": "PLN",
  "description": "Example transaction with products",
  "hiddenDescription": "example_hidden_description",
  "languageCode": "PL",
  "pos": {
    "id": "01G6WAS5MNGQ2X728AW53D8JPR"
  },
  "billingAddress": {
    "email": "[email protected]",
    "name": "Name"
  },
  "childTransactions": [
    {
      "amount": 1500,
      "description": "Item no1",
      "merchant": {
        "id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
      },
      "products": [
        {
          "name": "Czereśnie (100g)",
          "externalId": "111.222.33.44",
          "quantity": 1.2,
          "unitPrice": 1250
        }
      ]
    },
    {
      "amount": 4000,
      "description": "Item no2",
      "merchant": {
        "id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
      },
      "products": [
        {
          "name": "Zlew",
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

Powiadomienia

Podczas tworzenia transakcji możesz przekazać w parametrze transactionCallbacks, różne typy powiadomień:

Zwroty

Zwrot możesz zlecić, przesyłając listę kwot per konto sprzedawcy, listę produktów zwracanych od konkretnego sprzedawcy (przesyłając identyfikator sprzedawcy, analogicznie do danych użytych przy tworzeniu transakcji) przesyłając listę kwot lub listę produktów zwracanych z konkretnej transakcji podrzędnej, przesyłając jej identyfikator, lub bez danych – zwrócisz wówczas całą transakcję.

Podczas transakcji wykonujemy odpowiednie walidacje, np. czy nie przekroczono maksymalnej kwoty zwrotu, która wynosi 100% wpłaconej kwoty, w całości zwrotu, czy też w podziale na poszczególnych 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.

Realizacja zwrotu całkowitego

Aby zrealizować zwrot całkowity, wyślij żądanie POST na endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Zastąp {transactionId} identyfikatorem transakcji, którą chcesz zwrócić.

Sprawdź szczegóły w dokumentacji API Reference: POST /marketplace/v1/transaction/{transactionId}/refund

Przykładowy URL: https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

Body żądania powinno być pustym obiektem JSON:

{}

Realizacja zwrotu częściowego poprzez podanie kwoty

Aby zrealizować zwrot częściowy, wyślij żądanie POST na endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Zastąp {transactionId} identyfikatorem transakcji, którą chcesz zwrócić.

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

W zapytaniu określ następujące parametry:

Podstawowe body żądania powinno wyglądać jak jeden z poniższych przykładów:

{
  "childTransactions": [
    {
      "merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
      "amount": 2000
    },
    {
      "merchantId": "01G6WAPZFNNX4CXBPKQH5MYD4R",
      "amount": 1000
    }
  ]
}

{
  "childTransactions": [
    {
      "id": "01JENG92HA094GVX7QT60EP0K9",
      "amount": 2000
    },
    {
      "id": "01JENG98VYHM1YF0SBDCM66AH9",
      "amount": 1000
    }
  ]
}

Realizacja zwrotu częściowego poprzez podanie listy produktów

Aby zrealizować zwrot częściowy, wyślij żądanie POST na endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Zastąp {transactionId} identyfikatorem transakcji, którą chcesz zwrócić:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

W zapytaniu określ następujące parametry:

Podstawowe body żądania powinno wyglądać jak jeden z poniższych przykładów:

{
  "childTransactions": [
    {
      "merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
      "products": [
        {
          "externalId": "111.222.33.44",
          "quantity": 1.0,
          "unitPrice": 1250
        },
        {
          "externalId": "111.222.33.44",
          "quantity": 0.2,
          "unitPrice": 500
        }
      ]
    },
    {
      "merchantId": "01G6WAPZFNNX4CXBPKQH5MYD4R",
      "products": [
        {
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

{
  "childTransactions": [
    {
      "id": "01JENG92HA094GVX7QT60EP0K9",
      "products": [
        {
          "externalId": "111.222.33.44",
          "quantity": 1.0,
          "unitPrice": 1250
        },
        {
          "externalId": "111.222.33.44",
          "quantity": 0.2,
          "unitPrice": 500
        }
      ]
    },
    {
      "id": "01JENG98VYHM1YF0SBDCM66AH9",
      "products": [
        {
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

Lista dostępnych metod płatniczych

Dostępne metody płatności zależą od ustawień sprzedawców przypisanych do Twojego marketplace. Dostępne są tylko te metody płatności, które są wspólne dla wszystkich sprzedawców w ramach danej transakcji.

Możesz pobrać listę kanałów, które są włączone dla wszystkich merchantów, aby wyświetlić je podczas podsumowania zakupów.

Aby pobrać listę metod płatniczych dla marketplace, wyślij żadanie GET na endpoint:

https://api.tpay.com/marketplace/v1/bank-groups

W zapytaniu określ następujące parametry:

Przykład:

https://api.tpay.com/marketplace/v1/bank-groups?merchantId[]=01G6WAPZFNNX4CXBPKQH5MYD4R&merchantId[]=01G6QRHEBPFAECEWRWVEEPM9WY

Metoda wymaga podania identyfikatorów wszystkich sprzedawców, którzy biorą udział w opłacanym koszyku, w jednym wywołaniu, ponieważ ogranicza zbiór zwracanych metod do ich części wspólnej. Przykładowo, gdy sprzedawca 1 nie ma uruchomionych płatności ratalnych, to nie można wybrać tej metody, mimo że pozostali sprzedawcy mają ją włączoną.

Anulowanie transakcji

Transakcję marketplace możesz anulować pod warunkiem, że płatnik nie dokonał już płatności.

Aby anulować transakcję marketplace, wyślij żądanie POST na endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/cancel

Zastąp {transactionId} identyfikatorem transakcji, którą chcesz zwrócić:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/cancel

Poprawna odpowiedź na żądanie anulowania gwarantuje uniemożliwienie jej opłacenia.