# Generowanie transakcji

Endpoint: POST /payment/{serviceId}/transactions
Version: 1.0.0
Security: bearerAuth

## Header parameters:

  - `x-sim-flow-submerchant` (string)
    Dotyczy tylko integratorów SimPay Flow. Jeśli nie korzystasz z SimPay Flow - pomiń ten nagłówek.

Wskazuje submerchanta, w imieniu którego wykonywane jest żądanie. Wartość to ID submerchanta (flsm_...)
lub jego customId nadany przy rejestracji (maks. 36 znaków).

Kiedy nagłówek jest wymagany?

Gdy serviceId w ścieżce to usługa Płatności Online powiązana z Twoją aktywną usługą Flow
(usługa nadrzędna, widoczna w paymentService w GET /flow/{flowServiceId}).
Wtedy każde żądanie pod /payment/{serviceId}/... musi zawierać ten nagłówek - bez niego otrzymasz
422 z kodem SIMPAY_FLOW_VALIDATION_ERROR.

Dla zwykłych usług Płatności Online (niepowiązanych z Flow) nagłówek jest ignorowany.

Jak to działa?

- W ścieżce zawsze podajesz serviceId usługi nadrzędnej (powiązanej z usługą Flow), a nie usługi submerchanta.
- Żądanie jest wykonywane w kontekście usługi Płatności Online submerchanta - transakcje, zwroty, kanały, subskrypcje
  i aliasy BLIK dotyczą wskazanego submerchanta, a środki trafiają na jego portfel.
- Usług Płatności Online submerchantów nie można używać bezpośrednio - podanie ich ID w serviceId
  zwróci 422 (VALIDATION_ERROR).

Możliwe błędy:

- 422 SIMPAY_FLOW_VALIDATION_ERROR - brak nagłówka dla usługi powiązanej z Flow lub nieprawidłowa wartość,
- 404 FLOW_SUBMERCHANT_NOT_FOUND - submerchant nie istnieje w ramach tej usługi Flow,
- 403 FLOW_SUBMERCHANT_NOT_ACTIVE - submerchant nie zakończył onboardingu lub nie jest aktywny,
- 400 FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND / FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVE - usługa Płatności Online submerchanta nie istnieje lub nie jest aktywna.

Przykład: x-sim-flow-submerchant: flsm_aaaabbbb lub x-sim-flow-submerchant: user-123
    Example: "flsm_aaaabbbb"

## Path parameters:

  - `serviceId` (string, required)
    Id usługi

## Request fields (application/json):

  - `amount` (number, required)
    Kwota transakcji

  - `currency` (string)
    Waluta transakcji

  - `description` (string)
    Opis transakcji nadany przez partnera, prezentowany na bramce płatności

  - `control` (string)
    Pole do wykorzystania przez partnera

  - `customer` (object,null)
    Obiekt podstawowych informacji o płacącym

  - `customer.name` (string)

  - `customer.email` (string)

  - `customer.ip` (string)
    Adres IP kupującego. Wymagany przy używaniu directChannel.

  - `customer.countryCode` (string)
    Kod ISO kupującego. Wymagany przy używaniu directChannel.
    Example: "PL"

  - `antifraud` (object,null)
    Obiekt informacji do antifrauda

  - `antifraud.useragent` (string)
    UserAgent kupującego. Wymagany przy używaniu directChannel.

  - `antifraud.steamid` (integer)
    STEAMID64 kupującego

  - `antifraud.mcusername` (string)
    Nick gracza Minecraft

  - `antifraud.mcid` (string)
    UUID gracza Minecraft

  - `billing` (object,null)

  - `billing.name` (string,null, required)

  - `billing.surname` (string,null, required)

  - `billing.street` (string,null, required)

  - `billing.building` (string,null)

  - `billing.flat` (string,null)

  - `billing.city` (string,null, required)

  - `billing.region` (string,null)

  - `billing.postalCode` (string,null, required)
    Kod pocztowy, format zależny od pola country

  - `billing.country` (string,null, required)
    Kraj

  - `billing.company` (string,null)
    Nazwa firmy

  - `shipping` (object,null)

  - `cart` (array,null)

  - `cart.name` (string, required)
    Nazwa produktu

  - `cart.quantity` (number, required)
    Ilość danego produktu

  - `cart.price` (number, required)
    Kwota jednego produktu

  - `cart.producer` (string,null, required)
    Marka producneta produktu

  - `cart.category` (string,null, required)
    Kategoria produktu

  - `cart.code` (string,null, required)
    Kod produktu

  - `returns` (object,null)

  - `returns.success` (string)

  - `returns.failure` (string)

  - `directChannel` (string)
    W tym polu można przesłać Id kanału, wtedy płacący zostanie przekierowany od razu na stronę podanego kanału
np. przy podaniu blik zostanie przekierowany od razu na bramkę płatności BLIK. Wymagane jest wtedy przesłanie antifraud.useragent oraz customer.ip.

  - `channels` (array,null)
    Tablica z Id kanałów płatności, które zostaną wyświetlone płacącemu na bramce po przekierowaniu na url transakcji
Listę dostępnych kanałów wraz z ich Id możemy uzyskać tutaj [Pobieranie listy kanałów dla usługi](#tag/Payment/operation/paymentGetChannels)

  - `channelTypes` (object,null)
    Obiekt w którym możemy zdefiniować które typu kanłów mają być dostępne na bramce płatności

  - `channelTypes.blik` (boolean)
    Płatność BLIK

  - `channelTypes.transfer` (boolean)
    Płatności przelewami online

  - `channelTypes.cards` (boolean)
    Płatności kartami

  - `channelTypes.ewallets` (boolean)
    Płatności wirtualnymi portfelami (Google Pay, Apple Pay)

  - `channelTypes.paypal` (boolean)
    Płatność PayPal

  - `channelTypes.paysafe` (boolean)
    Płatności od grupy Paysafe (Skrill, PaysafeCard)

  - `channelTypes.latam` (boolean)
    Płatności Ameryki Południowej (PIX, Boleto, BoletoFlash)

  - `referer` (string)

  - `context` (object,null)
    Obiekt z dodatkowymi danymi przekazywanymi do kanału płatności (zalecane dla Twisto)

  - `context.accountCreatedAt` (string,null)
    Data utworzenia konta kupującego w formacie ISO 8601
    Example: "2026-03-27T14:55:33+01:00"

  - `context.salesTotalCount` (integer,null)
    Ilość transakcji kupującego zrealizowanych przed tą transakcją
    Example: 27

  - `context.salesTotalAmount` (number,null)
    Łączna kwota wszystkich transakcji kupującego zrealizowanych przed tą transakcją
    Example: 1234.56

  - `context.salesAvgAmount` (number,null)
    Średnia kwota transakcji kupującego zrealizowanych przed tą transakcją
    Example: 123.45

  - `context.salesMaxAmount` (number,null)
    Maksymalna kwota transakcji kupującego zrealizowanych przed tą transakcją
    Example: 500

  - `context.refundsTotalAmount` (number,null)
    Łączna kwota wszystkich zwrotów kupującego zrealizowanych przed tą transakcją

  - `context.previousChargeback` (boolean,null)
    Czy kupujący miał wcześniej chargebacki

  - `context.accountSetCurrency` (string,null)
    Ustawiona waluta konta kupującego
    Example: "PLN"

  - `context.lastLoginAt` (string,null)
    Data ostatniego logowania kupującego na konto w sklepie
    Example: "2026-03-20T14:55:33+01:00"

  - `context.hasPreviousPurchases` (boolean,null)
    Czy kupujący dokonywał wcześniej zakupu w sklepie?
    Example: true

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Request status
    Example: true

  - `data` (object, required)
    Example: {"transactionId":"1d87a1b3-18f8-4146-bcb1-c0c9f293b04f","redirectUrl":"https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"}

  - `data.transactionId` (string, required)
    Id transakcji

  - `data.redirectUrl` (string, required)
    Example: "https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"

## Response 401 fields (application/json):

  - `success` (boolean, required)
    Request status

  - `errorCode` (string, required)
    Error status code
    Enum: "UNAUTHORIZED"

## Response 403 fields (application/json):

  - `success` (boolean, required)
    Request status

  - `errorCode` (string, required)
    Error status code
    Enum: "INVALID_ABILITY_PROVIDED", "IP_ADDRESS_NOT_WHITELISTED"

## Response 404 fields (application/json):

  - `success` (boolean, required)
    Request status

  - `errorCode` (string, required)
    Error status code
    Enum: "SERVICE_NOT_FOUND", "TRANSACTION_NOT_FOUND", "ROUTE_NOT_FOUND"

## Response 422 fields (application/json):

  - `success` (boolean, required)
    Request status

  - `errorCode` (string, required)
    Error status code
    Enum: "VALIDATION_ERROR"

  - `errors` (object, required)
    Example: {"amount":["The amount field is required."],"currency":["The selected currency is invalid."]}

  - `errors.amount` (array)
    Example: ["The amount field is required."]


