Produkt

Connect i Smart routing

Dwa moduły dla większych kont. Connect (plan Platforma) pozwala platformie przyjmować płatności w imieniu swoich sprzedawców, potrącać prowizję i zostawić wypłaty operatorowi płatności. Smart routing (plan Skala) wybiera dla każdej płatności produkcyjnej konto operatora według kosztu i skuteczności i przełącza się przy awarii. Oba widać w API jako kilka pól płatności i kilka typów zdarzeń.

Klucz testowy w przykładach

Wklej klucz sk_test_ z panelu (zakładka Deweloperzy), a każdy przykład będzie gotowy do uruchomienia. Klucz zostaje w tej karcie przeglądarki, nie wysyłamy go nigdzie.

Przykłady używają Twojego klucza testowego. Produkcyjnego klucza nie przyjmujemy.

Tryb testowy

Connect: płatności dla sprzedawców platformy#

Platforma (Twoje konto Oplac) ma własną umowę z operatorem płatności na produkt dla marketplace. Każdy sprzedawca platformy dostaje u operatora konto połączone i przechodzi tam weryfikację (KYC); Oplac prowadzi te konta w panelu, w zakładce Connect, i wysyła link onboardingu. Pieniądze idą od klienta przez operatora do sprzedawcy, prowizja platformy zostaje na koncie platformy; Oplac nie dotyka środków.

01Dodaj sprzedawcę w panelu (adres e-mail, nazwa). Dostaje identyfikator conn_ i link weryfikacji u operatora, ważny 7 dni; link możesz odświeżyć.
02Po weryfikacji przychodzi zdarzenie account.verified. Dopóki go nie ma, płatność z tym sprzedawcą kończy się 400 connected_account_not_ready.
03Tworząc płatność albo link, podaj connected_account (identyfikator conn_) i application_fee (prowizja w groszach, od 0 do kwoty płatności). Płatność trafia do sprzedawcy po potrąceniu prowizji.
04Wypłaty robi operator według własnego harmonogramu; zdarzenie payout.paid informuje o zrealizowanej wypłacie.

Zwrot płatności z podziałem (POST /v1/refunds) cofa też przelew do sprzedawcy i proporcjonalną część prowizji. Smart routing nie dotyczy płatności z connected_account: idą zawsze przez konto główne platformy. Panel pokazuje prowizje platformy w miesiącu.

Connect: płatności dla sprzedawców platformy

curl https://oplac.pl/api/v1/payments \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: zamowienie-55021" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25900,
    "currency": "PLN",
    "description": "Zamówienie 55021 u sprzedawcy Sklep Anny",
    "connected_account": "conn_Ab12Cd34Ef56Gh",
    "application_fee": 2590,
    "return_url": "https://platforma.example.com/zamowienie/55021",
    "metadata": {"order_id": "55021", "seller_id": "118"}
  }'

$ch = curl_init('https://oplac.pl/api/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Idempotency-Key: zamowienie-55021',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 25900,
        'currency' => 'PLN',
        'description' => 'Zamówienie 55021 u sprzedawcy Sklep Anny',
        'connected_account' => 'conn_Ab12Cd34Ef56Gh',
        'application_fee' => 2590,   // 10 procent prowizji platformy, w groszach
        'return_url' => 'https://platforma.example.com/zamowienie/55021',
        'metadata' => ['order_id' => '55021', 'seller_id' => '118'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': 'zamowienie-55021',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 25900,
    currency: 'PLN',
    description: 'Zamówienie 55021 u sprzedawcy Sklep Anny',
    connected_account: 'conn_Ab12Cd34Ef56Gh',
    application_fee: 2590, // 10 procent prowizji platformy, w groszach
    return_url: 'https://platforma.example.com/zamowienie/55021',
    metadata: { order_id: '55021', seller_id: '118' },
  }),
});
const payment = await res.json();

import requests

res = requests.post(
    "https://oplac.pl/api/v1/payments",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ", "Idempotency-Key": "zamowienie-55021"},
    json={
        "amount": 25900,
        "currency": "PLN",
        "description": "Zamówienie 55021 u sprzedawcy Sklep Anny",
        "connected_account": "conn_Ab12Cd34Ef56Gh",
        "application_fee": 2590,  # 10 procent prowizji platformy, w groszach
        "return_url": "https://platforma.example.com/zamowienie/55021",
        "metadata": {"order_id": "55021", "seller_id": "118"},
    },
)
payment = res.json()

Odpowiedź

HTTP/1.1 201 Created
{
  "id": "pay_Cd34Ef56Gh78Ij",
  "object": "payment",
  "amount": 25900,
  "currency": "PLN",
  "status": "pending",
  "checkout_url": "https://oplac.pl/p/Cd34Ef56Gh78Ij",
  "connected_account": "conn_Ab12Cd34Ef56Gh",
  "application_fee": 2590,
  "metadata": {"order_id": "55021", "seller_id": "118"},
  "livemode": false,
  "created": 1760000000
}

Błędy Connect#

Kod	Kiedy
`connect_not_in_plan` (403)	konto nie ma planu Platforma
`connected_account_invalid` (400)	identyfikator `conn_` nie należy do tego konta albo nie istnieje
`connected_account_not_ready` (400)	sprzedawca nie przeszedł jeszcze weryfikacji u operatora; czekaj na `account.verified`
`application_fee_invalid` (400)	prowizja ujemna albo większa od kwoty płatności

Smart routing: wybór konta operatora#

W planie Skala do konta głównego dodajesz w panelu do dwóch dodatkowych kont operatora płatności (razem trzy), w planie Platforma bez limitu. Dla każdego konta podajesz koszt: stawkę w punktach bazowych i opłatę stałą. Przy każdej płatności produkcyjnej Oplac liczy ranking i wybiera konto o najniższym oczekiwanym koszcie.

Skuteczność konta to udział udanych płatności w ostatnich 50 zakończonych płatnościach produkcyjnych tego konta; poniżej 10 prób przyjmujemy 100 procent, żeby nowe konto miało szansę.
Ranking to koszt podzielony przez skuteczność (nie mniej niż 5 procent), rosnąco. Przy równym wyniku wygrywa konto główne, potem kolejność dodania.
Awaria (błąd połączenia, 5xx, limit u operatora) wstrzymuje konto na 5 minut i płatność idzie do następnego w rankingu. Gdy wszystkie konta są wstrzymane, próbujemy wszystkich: wstrzymanie to wskazówka, nie blokada sprzedaży.
Odmowa banku klienta (brak środków, odrzucony kod BLIK) nie jest awarią i nie przełącza konta.

W API routing widać w polu provider_account płatności (primary dla konta głównego albo identyfikator konta dodatkowego; null przed przejściem klienta do płatności i w piaskownicy) oraz w zdarzeniu payment.routed. Zwroty idą zawsze przez konto, które obsłużyło płatność. Routing nie dotyczy płatności z connected_account ani odnowień subskrypcji Bill: te idą przez konto główne.

JSON

{
  "id": "evt_Ef56Gh78Ij90Kl",
  "object": "event",
  "type": "payment.routed",
  "livemode": true,
  "created": 1760000010,
  "data": {
    "object": {
      "id": "pay_Ab12Cd34Ef56Gh",
      "object": "payment",
      "status": "pending",
      "provider_account": "prov_Gh78Ij90Kl12Mn",
      "livemode": true
    }
  }
}

Testowanie Connect i routingu#

Connect testujesz w piaskownicy z identyfikatorem conn_ sprzedawcy dodanego w panelu w trybie testowym: płatność z connected_account i application_fee przechodzi przez stronę płatności piaskownicy, a odpowiedź i zdarzenia mają oba pola. Smart routing dotyczy wyłącznie płatności produkcyjnych, więc w piaskownicy provider_account jest zawsze null; w produkcji sprawdzisz go po pierwszych płatnościach w panelu, w zakładce Routing, razem ze skutecznością każdego konta.

Powiązane

Moduły a plany/docs/moduly-i-plany Płatności dla marketplace/platnosci-dla-marketplace Smart routing/smart-routing Płatności w referencji API/docs/api/platnosci

Klucz testowy dostajesz od razu po zapisie

Adres e-mail, kod z maila i piaskownica z kodami BLIK. Produkcję włączasz sam w panelu: plan, dostawca płatności, klucz sk_live_. Wolisz, żeby wdrożenie w sklepie zrobił nasz zespół? To też jest za darmo.

Zamów integrację za darmo