Przejdź do treści
Ostatnia aktualizacja

Płatności w imieniu submerchanta

Transakcje dla submerchantów tworzysz przez standardowe API Płatności Online - te same endpointy, co przy zwykłej integracji. Różnią się tylko dwa elementy:

  1. w ścieżce podajesz serviceId usługi nadrzędnej (usługi Płatności Online powiązanej z Twoją usługą Flow),
  2. w nagłówku x-sim-flow-submerchant wskazujesz submerchanta, w imieniu którego wykonujesz żądanie.

serviceId usługi nadrzędnej znajdziesz w polu paymentService.id w odpowiedzi GET /flow/{flowServiceId}.

Przykład: tworzenie transakcji

curl -X POST "https://api.simpay.pl/payment/{serviceIdUslugiNadrzednej}/transactions" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-sim-flow-submerchant: user-123" \
  -d '{
    "amount": 49.99,
    "description": "Zamówienie #1001",
    "control": "order-1001"
  }'

Transakcja zostanie utworzona w usłudze submerchanta user-123, a środki trafią na jego portfel (lub - dla instytucji płatniczych - zostaną rozliczone z IP).

Nagłówek x-sim-flow-submerchant

WartośćID submerchanta (flsm_...) lub jego customId
Kiedy wymaganyW każdym żądaniu /payment/{serviceId}/..., gdy serviceId to usługa nadrzędna Twojej aktywnej usługi Flow
Kiedy ignorowanyGdy serviceId to zwykła usługa Płatności Online, niepowiązana z Flow

Nagłówek działa dla wszystkich endpointów Płatności Online - transakcji, zwrotów, kanałów, walut, subskrypcji, BLIK Level 0 i aliasów BLIK. Każde z tych żądań jest wykonywane w kontekście usługi wskazanego submerchanta. Przykładowo GET /payment/{serviceId}/transactions zwróci tylko transakcje danego submerchanta.

Nie używaj usługi submerchanta bezpośrednio

Każdy submerchant ma własną usługę Płatności Online, ale nie można jej używać bezpośrednio. Podanie jej ID jako serviceId zwróci błąd 422. Zawsze używaj usługi nadrzędnej i nagłówka x-sim-flow-submerchant.

Możliwe błędy

Kod HTTPerrorCodePrzyczyna
422SIMPAY_FLOW_VALIDATION_ERRORBrak nagłówka dla usługi nadrzędnej Flow lub nieprawidłowa wartość.
404FLOW_SUBMERCHANT_NOT_FOUNDSubmerchant nie istnieje w ramach Twojej usługi Flow.
403FLOW_SUBMERCHANT_NOT_ACTIVESubmerchant nie zakończył onboardingu lub nie jest aktywny.
400FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND / FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVEUsługa Płatności Online submerchanta nie istnieje lub nie jest aktywna.

Powiadomienia o płatnościach

Powiadomienia IPN o transakcjach submerchantów działają tak samo jak przy zwykłej integracji - zobacz Powiadomienia o płatnościach.

Domyślnie powiadomienia dla wszystkich submerchantów trafiają na adres IPN usługi nadrzędnej i są podpisywane jej kluczem. Dla wybranego submerchanta możesz ustawić osobny adres.

W powiadomieniach płatności dla submerchantów:

  • service_id zawiera ID usługi nadrzędnej,
  • nowy obiekt data.flow wskazuje submerchanta (submerchant_id, submerchant_custom_id) i usługę Flow - we wszystkich zdarzeniach poza ipn:test,
  • w transaction:status_changed nowe pole amount.commission_flow zawiera Twoją prowizję Flow.

Szczegóły i przykład: Webhooki płatności w SimPay Flow.

Poprzednia strona
Następna strona