Payment facilitator (subagregacja)

wskazówka

Model subagregacji wymaga dodatkowej umowy agregacyjnej z dpay.pl. Skontaktuj się z opiekunem konta, aby aktywować agregację dla Twojego punktu płatności.

Model payment facilitator pozwala agregatorom (platformom obsługującym wielu własnych merchantów) przyjmować płatności w imieniu swoich klientów - submerchantów - w ramach jednego punktu płatności dpay.pl.

Przetwarzanie płatności jest działalnością regulowaną: organizacje płatnicze wymagają, aby każda transakcja była przypisana do konkretnego, wcześniej zarejestrowanego submerchanta. Dlatego:

• każdy submerchant musi zostać zarejestrowany, zanim przyjmie pierwszą płatność,
• dane submerchanta muszą być aktualizowane, gdy tylko się zmienią (nazwa, adres, strona www, MCC).

Cykl życia submerchanta

Submerchant z produktami przelewowymi (PBL, BLIK) jest aktywny natychmiast po udanej rejestracji. Produkty kartowe (MC, V, AMEX, portfele) przechodzą dodatkowy onboarding kartowy - płatności kartą są możliwe po zakończeniu weryfikacji.

Jeżeli rejestracja u agenta rozliczeniowego nie powiedzie się, rekord submerchanta nie jest zapisywany, a odpowiedź zawiera przyczynę błędu - popraw dane i ponów wywołanie.

Zarządzanie submerchantami

Wszystkie wywołania są podpisywane sumą kontrolną SHA-256 (checksum) i wymagają świeżego timestamp (maks. 60 sekund).

PUT/api/v1/aggregator/merchants→Rejestracja submerchanta: pola, produkty, onboarding kartowy i kody błędów.Pełny kontrakt w API Reference PATCH/api/v1/aggregator/merchants→Aktualizacja danych submerchanta (po id lub MID).Pełny kontrakt w API Reference POST/api/v1/aggregator/merchants→Lista submerchantów punktu płatności.Pełny kontrakt w API Reference DELETE/api/v1/aggregator/merchants→Usunięcie submerchanta.Pełny kontrakt w API Reference

Wymagane dane

Pole	Opis
aggregator_mid	Identyfikator submerchanta nadany przez agregatora (MID) - klucz do aktualizacji i przypisywania transakcji
merchant_name	Nazwa handlowa widoczna dla kupującego
merchant_url	Adres strony submerchanta
mcc	Merchant Category Code
tax_id	NIP (lub odpowiednik) submerchanta
products	Lista produktów płatniczych (np. ["PBL", "BLIK"])
companyName	Pełna nazwa prawna firmy submerchanta
address	Adres siedziby: street, postalCode, locality, country (ISO 3166-1)

Adres siedziby

Dla produktów przelewowych pola address.* są wymagane - bez nich rejestracja zakończy się błędem walidacji (HTTP 422). Adres musi być adresem siedziby firmy powiązanym z companyName i tax_id, a nie adresem korespondencyjnym.

Przykład rejestracji

PUT /api/v1/aggregator/merchants

{
  "service": "my-aggregator",
  "timestamp": "1753357200",
  "aggregator_mid": "MID-10045",
  "merchant_name": "superstore.com",
  "merchant_url": "https://www.superstore.com",
  "mcc": "5999",
  "tax_id": "1234567890",
  "products": ["PBL", "BLIK"],
  "companyName": "Superstore Ltd",
  "address": {
    "street": "1 Flower St",
    "postalCode": "00-000",
    "locality": "Flowerton",
    "country": "PL"
  },
  "checksum": "..."
}

Przypisanie transakcji do submerchanta

Przy rejestracji transakcji agregator wskazuje submerchanta w tablicy products:

• products[].id - aggregator_mid submerchanta,
• products[].description - adres e-mail kupującego,
• pole email transakcji ustawione na void@dpay.pl (marker transakcji agregacyjnej).

Na tej podstawie dpay.pl przypisuje płatność do właściwego submerchanta i przekazuje jego dane do systemów rozliczeniowych - opis transakcji widoczny dla kupującego zawiera nazwę i domenę submerchanta.

informacja

Transakcja submerchanta, który nie został wcześniej zarejestrowany, może zostać odrzucona przez systemy rozliczeniowe. Zawsze rejestruj submerchanta przed pierwszą płatnością.

Aktualizacja i usuwanie

• Aktualizacja (PATCH) - wskaż rekord przez id albo aggregator_mid; zmienione dane są propagowane do rejestracji payment facilitator. Aktualność danych submerchantów to obowiązek wynikający z regulacji organizacji płatniczych.
• Usunięcie (DELETE) - usuwa submerchanta z dpay.pl; historyczne transakcje zachowują przypisanie.