Przejdź do treści
/
Generowanie transakcji Di...
Ostatnia aktualizacja

Generowanie transakcji DirectBilling

Aby rozpocząć proces płatności u operatora GSM, musisz wygenerować nową transakcję, odpytując nasze API. W odpowiedzi otrzymasz dedykowany link (redirectUrl), na który należy przekierować klienta, aby mógł wpisać swój numer telefonu i potwierdzić obciążenie rachunku.

Endpoint i autoryzacja

Endpoint: POST /directbilling/{serviceId}/transactions Wersja: 1.0.0 Autoryzacja: Bearer Token (wymaga nagłówka Authorization: Bearer TWÓJ_KLUCZ_API)

Parametry ścieżki (Path parameters)

ParametrTypWymaganeOpis
serviceIdstringTAKIdentyfikator Twojej usługi DirectBilling (np. e14f8074). Parametr przekazywany bezpośrednio w adresie URL.

🌟 Unikalna funkcja: amountType (Zarabiaj tyle, ile chcesz!)

Zazwyczaj bramki płatnicze zmuszają Cię do podawania sztywnej kwoty brutto, jaką ma zapłacić klient. W przypadku płatności DirectBilling, gdzie prowizje operatorów potrafią być skomplikowane, wyliczenie odpowiedniej ceny dla klienta bywa kłopotliwe.

Rozwiązaliśmy ten problem, wprowadzając unikalny parametr amountType! Pozwala on zdefiniować, czym w rzeczywistości jest przekazywana przez Ciebie kwota (amount).

Dzięki temu możesz wysłać do nas żądanie z komunikatem: "Chcę zarobić na czysto 10 PLN, wyliczcie za mnie, ile klient musi zapłacić".

Dostępne warianty amountType:

  • gross (domyślne) – kwota, którą podajesz, to finalna kwota brutto, którą zapłaci klient. Twój zysk zostanie wyliczony po odjęciu prowizji.
  • net – podajesz kwotę netto.
  • required – absolutny hit! Podajesz kwotę swojej ostatecznej prowizji (ile chcesz zarobić "na czysto"). Nasz system sam sprawdzi tabele prowizyjne operatorów i na ich podstawie zażąda od klienta odpowiedniej, wyższej kwoty brutto, aby zagwarantować Ci oczekiwany zysk.

Ciało żądania (Request)

Żądanie należy przesłać w formacie JSON (Content-Type: application/json).

Przykładowy Payload

{
  "amount": 10.00,
  "amountType": "required",
  "control": "Zamowienie_VIP_123",
  "returns": {
    "complete": "https://twojsklep.pl/sukces",
    "failure": "https://twojsklep.pl/blad"
  }
}

(W powyższym przykładzie sklep informuje SimPay: "Wygeneruj transakcję, z której chcę otrzymać równe 10.00 PLN do swojego portfela. Sami policzcie brutto").

Odpowiedź sukcesu (HTTP 200 OK)

Gdy żądanie jest poprawne, system utworzy transakcję i zwróci adres przekierowania dla klienta.

{
  "success": true,
  "data": {
    "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "redirectUrl": "https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
  }
}
Wskazówka

Zapisz wartość data.transactionId w swojej bazie danych i powiąż ją z koszykiem klienta. To właśnie po tym ID zidentyfikujesz transakcję, gdy w przyszłości otrzymasz od nas asynchroniczne powiadomienie IPN o jej opłaceniu.

Kody błędów

W przypadku podania nieprawidłowych danych lub problemów z uwierzytelnieniem, API zwróci jeden z poniższych kodów HTTP wraz z odpowiednim errorCode w formacie JSON:

  • HTTP 401 (Unauthorized) – brakuje nagłówka z tokenem lub klucz API jest nieprawidłowy (errorCode: UNAUTHORIZED).
  • HTTP 403 (Forbidden) – Twój token nie ma uprawnień do danej akcji lub wykonujesz zapytanie z nieautoryzowanego adresu IP (errorCode: INVALID_ABILITY_PROVIDED lub IP_ADDRESS_NOT_WHITELISTED).
  • HTTP 404 (Not Found) – nie znaleziono podanej usługi lub błędny adres endpointu (errorCode: SERVICE_NOT_FOUND, ROUTE_NOT_FOUND).
  • HTTP 422 (Unprocessable Entity) – błąd walidacji przekazanych danych (np. brak wymaganej kwoty). Odpowiedź będzie zawierała obiekt errors ze szczegółami.

Przykład błędu 422:

{
  "success": false,
  "errorCode": "VALIDATION_ERROR",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}
Poprzednia strona
Następna strona