Dokumentacja
Dokumentacja API Oplac
Wszystko, czego potrzebujesz, żeby przyjąć pierwszą płatność testową w kilka minut i przejść na produkcję bez rozmowy z handlowcem: przewodniki krok po kroku, referencja każdego zasobu i każdej operacji REST API, webhooki z podpisem HMAC i piaskownica z kodami BLIK. Przykłady działają na kluczu testowym bez żadnej biblioteki SDK: zwykłe HTTPS w curl, PHP, Node i Pythonie.
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.
Od czego zacząć#
Jak czytać tę dokumentację#
Dokumentacja ma dwie części. Przewodniki wyjaśniają, jak działa API jako całość: tryby i klucze, konwencje, błędy, idempotencja, webhooki, piaskownica, wersje. Referencja API opisuje każdy zasób i każdą operację z parametrami, obiektem odpowiedzi i przykładem w czterech językach; jest generowana ze specyfikacji OpenAPI 3.1, tej samej, którą czyta kod, więc zawsze zgadza się z tym, co odpowiada serwer.
-
Adres API to
https://oplac.pl/api, wszystkie trasy zaczynają się od/v1. -
Klucz
sk_test_otwiera piaskownicę bez ruchu pieniędzy, kluczsk_live_produkcję. Reszta integracji jest identyczna w obu trybach. - Oplac jest oprogramowaniem: płatności przyjmuje i rozlicza operator płatności podpięty do Twojego konta, a Oplac prowadzi płatność, subskrypcję, fakturę i powiadomienia.
- Wyszukiwarka po lewej zna każdą operację, kod błędu i typ zdarzenia. Na klawiaturze otwiera ją ukośnik.
Pierwsza płatność w jednym żądaniu#
Wymagane są tylko amount (w groszach) i currency. W odpowiedzi dostajesz checkout_url, czyli hostowaną stronę płatności: w piaskownicy z kodami BLIK 777 123 (sukces) i 777 000 (odmowa), w produkcji u dostawcy płatności Twojego konta. Po zapłacie klient wraca na return_url, a Twój serwer dostaje zdarzenie payment.succeeded.
- 01Wklej klucz testowy w karcie powyżej albo , żeby go dostać.
- 02Uruchom żądanie obok w wybranym języku. Przełącznik języka pamięta Twój wybór w całej dokumentacji.
- 03Otwórz
checkout_urlz odpowiedzi i zapłać kodem 777 123. Potem podepnij webhook.
curl https://oplac.pl/api/v1/payments \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
-H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
-H "Content-Type: application/json" \
-d '{
"amount": 12900,
"currency": "PLN",
"description": "Zamówienie 10482",
"return_url": "https://sklep.example.com/powrot",
"metadata": {
"order_id": "10482"
}
}'$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: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 12900,
'currency' => 'PLN',
'description' => 'Zamówienie 10482',
'return_url' => 'https://sklep.example.com/powrot',
'metadata' => [
'order_id' => '10482',
],
]),
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': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 12900,
currency: 'PLN',
description: 'Zamówienie 10482',
return_url: 'https://sklep.example.com/powrot',
metadata: {
order_id: '10482',
},
}),
});
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": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
},
json={
"amount": 12900,
"currency": "PLN",
"description": "Zamówienie 10482",
"return_url": "https://sklep.example.com/powrot",
"metadata": {
"order_id": "10482",
},
},
)
payment = res.json(){
"id": "pay_Ab12Cd34Ef56Gh",
"object": "payment",
"amount": 12900,
"amount_refunded": 0,
"currency": "PLN",
"status": "pending",
"method": null,
"description": "Zamówienie 10482",
"checkout_url": "https://oplac.pl/p/Ab12Cd34Ef56Gh",
"return_url": "https://sklep.example.com/powrot",
"customer": "cus_Xy98Zw76Vu54Ts",
"customer_email": "[email protected]",
"customer_name": "Anna Nowak",
"payment_link": null,
"subscription": null,
"invoice": null,
"tax_id": null,
"provider_account": null,
"connected_account": null,
"application_fee": null,
"failure_code": null,
"decline_code": null,
"metadata": {
"order_id": "10482"
},
"livemode": false,
"expires_at": 1760086400,
"paid_at": null,
"created": 1760000000
}Podstawy API#
Reguły wspólne dla każdej trasy. Przeczytaj je raz, zanim napiszesz obsługę błędów i webhooków.
Referencja API#
Każdy zasób z pełną listą pól, każda operacja z parametrami, przykładem żądania w curl, PHP, Node i Pythonie oraz przykładem odpowiedzi. Budowana ze specyfikacji OpenAPI 2026-10-03, więc nie rozjeżdża się z kodem.
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.