BLIK API, przelew API i integracja BLIK w jednym API płatności z kartami i webhookami
BLIK API, przelew API i karty w Oplac to jedna integracja REST na płatności, zwroty, klientów, subskrypcje i faktury: kwoty w groszach, klucze idempotencji, webhooki podpisane HMAC SHA-256, piaskownica z testowymi kodami BLIK i przykłady w curl, PHP, Node i Pythonie.
REST, JSON i przewidywalne obiekty
API działa pod adresem https://oplac.pl/api/v1, przyjmuje i zwraca JSON, a każdy obiekt ma prefiks identyfikatora: pay_ dla płatności, re_ dla zwrotu, cus_ dla klienta, sub_ dla subskrypcji, in_ dla faktury. Kwoty podajesz w najmniejszej jednostce waluty, czyli w groszach: 12900 to 129,00 zł. Uwierzytelnianie odbywa się kluczem w nagłówku Authorization: Bearer, osobnym dla trybu testowego (sk_test_) i produkcyjnego (sk_live_).
- płatności jednorazowe i cykliczne
-
linki do płatności (
/v1/payment_links) wysyłane e-mailem albo w czacie - zwroty całkowite i częściowe
- klienci z zapisanymi metodami płatności u dostawcy
- subskrypcje, faktury i zdarzenia KSeF
- pełna referencja w dokumentacji API
Pierwsza płatność w curl
Najprostsze żądanie tworzy płatność i zwraca adres strony płatności, na którą przekierowujesz klienta albo którą wysyłasz jako link do płatności.
Odpowiedź zawiera obiekt płatności ze statusem pending i polem checkout_url.
curl https://oplac.pl/api/v1/payments \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ_TESTOWY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{
"amount": 12900,
"currency": "PLN",
"description": "Zamówienie 10482",
"methods": ["blik", "card", "apple_pay", "google_pay", "transfer"],
"customer": {"email": "[email protected]"},
"return_url": "https://sklep.example.com/dziekujemy",
"metadata": {"order_id": "10482"}
}'BLIK API z kodem wpisywanym na Twojej stronie
Jeśli chcesz, żeby klient wpisał kod BLIK bez przekierowania, przekazujesz go w polu blik_code. Płatność przechodzi w status requires_confirmation, klient potwierdza ją w aplikacji banku, a wynik przychodzi webhookiem. W piaskownicy kod 777 123 akceptuje płatność, a 777 000 ją odrzuca. BLIK integracja działa tak samo w sklepie, w aplikacji mobilnej i w płatnościach BLIK w sklepie z wtyczek.
<?php
$oplac = new \Oplac\Client(getenv('OPLAC_SECRET_KEY'));
$payment = $oplac->payments->create([
'amount' => 12900,
'currency' => 'PLN',
'description' => 'Zamówienie 10482',
'method' => 'blik',
'blik_code' => '777123',
'metadata' => ['order_id' => '10482'],
], ['idempotency_key' => 'order-10482']);
echo $payment->status;Przelew API i pozostałe metody
Szybki przelew (pay by link) działa przez to samo żądanie z metodą transfer: klient wybiera bank na stronie płatności i wraca na return_url. Karty obsługuje formularz licencjonowanego dostawcy osadzony na stronie płatności, więc numery kart nie trafiają na serwery Oplac ani Twoje. Apple Pay i Google Pay pojawiają się automatycznie na urządzeniach, które je obsługują.
Idempotencja chroni przed podwójnym obciążeniem
Sieć potrafi zerwać połączenie w chwili, gdy płatność już powstała. Nagłówek Idempotency-Key sprawia, że ponowienie tego samego żądania z tym samym kluczem zwraca pierwotny wynik zamiast tworzyć drugą płatność. Klucz trzymamy przez 24 godziny. Dobrym kluczem jest identyfikator zamówienia albo UUID zapisany razem z zamówieniem.
Webhooki z podpisem HMAC SHA-256
Każde zdarzenie (payment.succeeded, payment.failed, payment.routed, refund.succeeded, subscription.renewed, invoice.paid, invoice.ksef_accepted i inne) trafia na Twój adres jako żądanie POST z nagłówkiem Oplac-Signature. Podpis to HMAC SHA-256 liczony z czasu i treści żądania kluczem webhooka. Gdy Twój serwer nie odpowie kodem 2xx, Oplac ponawia wysyłkę z rosnącym odstępem. Więcej praktyki we wpisie webhooki płatności.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/webhooks/oplac", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Oplac-Signature") || "";
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto
.createHmac("sha256", process.env.OPLAC_WEBHOOK_SECRET)
.update(`${parts.t}.${req.body}`)
.digest("hex");
const valid =
typeof parts.v1 === "string" &&
parts.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
if (valid === false) {
return res.status(400).send("invalid signature");
}
const event = JSON.parse(req.body);
if (event.type === "payment.succeeded") {
// oznacz zamówienie event.data.metadata.order_id jako opłacone
}
res.sendStatus(200);
});Przykłady kodu, piaskownica i wdrożenie w sklepie
API to zwykłe wywołania HTTPS z JSON, więc działa z każdego języka bez dodatkowych bibliotek, a dokumentacja ma gotowe przykłady w curl, PHP, Node i Pythonie: uwierzytelnianie, idempotencja, stronicowanie list i weryfikacja podpisu webhooka. Piaskownica działa na kluczu testowym i nie przenosi pieniędzy, a zdarzenia z niej wyglądają tak samo jak na produkcji. Jeśli korzystasz ze sklepu, zamiast pisać kod możesz zamówić darmowe wdrożenie przez nasz zespół, na przykład dla WooCommerce, PrestaShop, Shopify albo WordPress. Przy kilku dostawcach to samo API przełącza transakcje przez smart routing, a zdarzenie payment.routed mówi, który dostawca obsłużył płatność.
API płatności w cenniku Oplac
API i webhooki są w każdym planie, od planu Start. Ceny są netto, a opłaty transakcyjne pobiera dostawca płatności według swojego cennika.
Start
- Cena
- 199 zł miesięcznie albo 1 188 zł rocznie
- Obrót w miesiącu
- do 50 000 zł
- Co dodaje w API
- płatności, zwroty, klienci, webhooki, 1 dostawca
Firma
- Cena
- 299 zł miesięcznie albo 1 788 zł rocznie
- Obrót w miesiącu
- do 250 000 zł
- Co dodaje w API
- subskrypcje, faktury VAT i KSeF
Skala
- Cena
- 999 zł miesięcznie albo 5 988 zł rocznie
- Obrót w miesiącu
- do 1 500 000 zł
- Co dodaje w API
- routing do 3 dostawców, PLN, EUR, USD
Platforma
- Cena
- 2 999 zł miesięcznie albo 17 988 zł rocznie
- Obrót w miesiącu
- do 10 000 000 zł
- Co dodaje w API
- Connect, routing bez limitu dostawców, SLA 99,9 procent
Enterprise
- Cena
- na wycenę
- Obrót w miesiącu
- powyżej 10 000 000 zł
- Co dodaje w API
- indywidualne limity zapytań i SLA
Najczęstsze pytania
Wszystkie pytaniaCzy mogę przetestować API bez podpisywania umowy z dostawcą?
Tak. Klucz testowy działa w piaskownicy od razu po założeniu konta, a zdarzenia i webhooki zachowują się jak na produkcji.
Jak podać kwotę w API płatności?
W groszach, jako liczbę całkowitą. 12900 oznacza 129,00 zł.
Co zrobić, gdy żądanie utworzenia płatności przekroczy czas?
Powtórz je z tym samym nagłówkiem Idempotency-Key. Dostaniesz tę samą płatność, bez drugiego obciążenia.
Czy numery kart przechodzą przez moje serwery?
Nie. Dane kart klient wpisuje w formularzu licencjonowanego dostawcy, więc nie trafiają ani na Twoje serwery, ani na serwery Oplac.
Pobierz klucz testowy i wyślij pierwsze żądanie
Załóż konto, skopiuj klucz sk_test_ i utwórz płatność w piaskownicy tym samym kodem, którego użyjesz na produkcji.