Dokumentacja Placenie dla programistów

REST API, webhooki i piaskownica bramki płatniczej. Jedno wywołanie tworzy płatność i zwraca adres ekranu płatności, a wynik dostajesz webhookiem z podpisem. Klucz testowy działa od założenia konta, bez umowy z operatorem.

Szybki start Od klucza testowego do opłaconej płatności testowej i odebranego webhooka, w sześciu krokach z kodem. Otwórz Wtyczka do sklepu WooCommerce, Shoper, PrestaShop i Shopify: ten sam zestaw kluczy i ten sam webhook, bez pisania kodu. Otwórz Webhooki Pięć typów zdarzeń, podpis HMAC-SHA256, siedem ponowień i idempotentne przetwarzanie. Otwórz

Jak działa płatność #

Tworzysz płatność. POST /v1/platnosci z kwotą w groszach, numerem zamówienia i adresem powrotu. W odpowiedzi dostajesz obiekt platnosc z identyfikatorem tr_… i polem adres_platnosci.
Kierujesz klienta na ekran płatności. Klient wybiera BLIK, kartę albo szybki przelew i płaci u operatora. Numer karty nigdy nie przechodzi przez Twój serwer ani przez Placenie.
Dostajesz webhook. Po zaksięgowaniu wysyłamy platnosc.oplacona z podpisem Placenie-Signature na adres z panelu. Odpowiadasz 2xx i wydajesz towar.
Sprawdzasz stan, kiedy chcesz. GET /v1/platnosci/{id} zwraca aktualny status i listę zwrotów. Zwrot pełny albo częściowy to POST /v1/platnosci/{id}/zwroty.

Powrót klienta na adres_powrotu nie jest potwierdzeniem zapłaty. Potwierdzeniem jest webhook albo odpowiedź GET ze statusem oplacona.

POST /v1/platnosci

curl -X POST "https://placenie.pl/api/v1/platnosci" \
  -H "Authorization: Bearer plc_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f9d4c2a-6b3e-4e1a-9c7d-2b8f1e3a5d6c" \
  -d '{
      "kwota": 12900,
      "waluta": "PLN",
      "numer_zamowienia": "ZAM-2026-001",
      "opis": "Zamówienie ZAM-2026-001",
      "email_klienta": "[email protected]",
      "adres_powrotu": "https://twojsklep.pl/zamowienie/ZAM-2026-001/dziekujemy",
      "metadane": {
          "koszyk": "c_8812",
          "klient_crm": "4471"
      }
  }'

$ch = curl_init('https://placenie.pl/api/v1/platnosci');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer plc_test_...',
        'Content-Type: application/json',
        'Idempotency-Key: 0f9d4c2a-6b3e-4e1a-9c7d-2b8f1e3a5d6c',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'kwota' => 12900,
        'waluta' => 'PLN',
        'numer_zamowienia' => 'ZAM-2026-001',
        'opis' => 'Zamówienie ZAM-2026-001',
        'email_klienta' => '[email protected]',
        'adres_powrotu' => 'https://twojsklep.pl/zamowienie/ZAM-2026-001/dziekujemy',
        'metadane' => [
            'koszyk' => 'c_8812',
            'klient_crm' => '4471',
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);

$platnosc = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status >= 400) {
    throw new RuntimeException($platnosc['blad']['kod'].': '.$platnosc['blad']['opis']);
}

const odpowiedz = await fetch('https://placenie.pl/api/v1/platnosci', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer plc_test_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': '0f9d4c2a-6b3e-4e1a-9c7d-2b8f1e3a5d6c',
  },
  body: JSON.stringify({
    kwota: 12900,
    waluta: 'PLN',
    numer_zamowienia: 'ZAM-2026-001',
    opis: 'Zamówienie ZAM-2026-001',
    email_klienta: '[email protected]',
    adres_powrotu: 'https://twojsklep.pl/zamowienie/ZAM-2026-001/dziekujemy',
    metadane: {
      koszyk: 'c_8812',
      klient_crm: '4471',
    },
  }),
});

const platnosc = await odpowiedz.json();

if (!odpowiedz.ok) {
  throw new Error(`${platnosc.blad.kod}: ${platnosc.blad.opis}`);
}

import requests

odpowiedz = requests.post(
    "https://placenie.pl/api/v1/platnosci",
    headers={"Authorization": "Bearer plc_test_...", "Idempotency-Key": "0f9d4c2a-6b3e-4e1a-9c7d-2b8f1e3a5d6c"},
    json={
        "kwota": 12900,
        "waluta": "PLN",
        "numer_zamowienia": "ZAM-2026-001",
        "opis": "Zamówienie ZAM-2026-001",
        "email_klienta": "[email protected]",
        "adres_powrotu": "https://twojsklep.pl/zamowienie/ZAM-2026-001/dziekujemy",
        "metadane": {
            "koszyk": "c_8812",
            "klient_crm": "4471",
        },
    },
)
platnosc = odpowiedz.json()

if not odpowiedz.ok:
    raise RuntimeError(f"{platnosc['blad']['kod']}: {platnosc['blad']['opis']}")

Odpowiedź 201

{
    "obiekt": "platnosc",
    "id": "tr_8h2k1j0f9e8d7c6b5a4z",
    "tryb": "test",
    "status": "nowa",
    "kwota": 12900,
    "waluta": "PLN",
    "zwrocono": 0,
    "do_zwrotu": 0,
    "numer_zamowienia": "ZAM-2026-001",
    "opis": "Zamówienie ZAM-2026-001",
    "email_klienta": "[email protected]",
    "adres_powrotu": "https://twojsklep.pl/zamowienie/ZAM-2026-001/dziekujemy",
    "metoda": null,
    "metadane": {
        "koszyk": "c_8812",
        "klient_crm": "4471"
    },
    "adres_platnosci": "https://placenie.pl/zaplac/tr_8h2k1j0f9e8d7c6b5a4z",
    "utworzona": "2026-10-03T10:00:00+00:00",
    "oplacona": null,
    "zwroty": []
}

Trzy drogi do wdrożenia #

Droga	Dla kogo	Co trzeba zrobić	Gdzie czytać
REST API	Własny sklep, system rezerwacji, aplikacja, panel SaaS	Jedno wywołanie tworzy płatność, jeden odbiornik webhooka zamyka zamówienie. Zwroty, lista i zdarzenia tym samym kluczem.	Szybki start, Referencja
Platforma sklepowa	WooCommerce, Shoper, PrestaShop, Shopify	Klucze API i adres webhooka z panelu wklejasz w ustawieniach płatności platformy. Opis dla każdej platformy osobno.	Integracje
Linki do zapłaty	Firma usługowa, sprzedaż bez sklepu	Link tworzysz w panelu i wysyłasz klientowi. Zero kodu, te same metody płatności i te same webhooki.	Linki do zapłaty

Piaskownica i produkcja #

Tryb wybiera klucz. plc_test_… to piaskownica: pieniądze nie płyną, ekran płatności prowadzi do banku testowego, a konto bez opłaconego planu ma 30 płatności testowych. plc_live_… to produkcja: działa w opłaconym planie, po podłączeniu konta operatora płatności w panelu. Klucz testowy widzi wyłącznie transakcje testowe, produkcyjny wyłącznie produkcyjne.

Oba klucze wydajesz w panelu, w zakładce Integracja i klucze. Klucz pokazujemy raz, w bazie trzymamy tylko jego skrót. Wydanie nowego klucza wycofuje poprzedni od razu.

plc_test_…

od założenia konta, bez karty i bez umowy z operatorem
bank testowy: BLIK 777777 zatwierdza, 111111 odrzuca
symulacja wyniku przez API do testów automatycznych
webhooki wysyłane tak samo jak w produkcji

plc_live_…

w opłaconym planie, po podłączeniu operatora w panelu
status oczekuje, gdy klient poszedł do operatora
zwrot może czekać u operatora (zlecony) i zostać odrzucony
stan płatności oczekuje odświeżamy u operatora przy każdym GET

Co robi Placenie, a co operator #

Placenie.pl jest warstwą technologiczną: bramką, panelem, API i integracjami. Płatności przyjmuje i wypłaca na rachunek Twojej firmy operator płatności z zezwoleniem KNF, z którym Twoja firma ma umowę. Numer karty klient wpisuje wyłącznie w formularzu operatora, więc ani Twój serwer, ani Placenie go nie widzi.

Dla kodu znaczy to trzy rzeczy: nie ma końcówki do przyjmowania numeru karty, status oczekuje i zlecony to czas po stronie operatora, a decyzja o uruchomieniu produkcji należy do operatora po weryfikacji firmy. Więcej na stronie Bezpieczeństwo.

Jak działa płatność #

Trzy drogi do wdrożenia #

Piaskownica i produkcja #

Co robi Placenie, a co operator #

Dalej #