Referencja API
Płatności
Płatność z hostowaną stroną płatności, adresem powrotu i webhookiem.
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.
Obiekt payment#
Płatność (pay_). Tworzona z API, z linku do płatności, z faktury albo z okresu subskrypcji. Hostowana strona płatności pod checkout_url: w piaskownicy u nas (kody BLIK i przyciski wyniku), w produkcji u dostawcy płatności sprzedawcy.
Pola
-
id string wymagane
Identyfikator płatności.
-
object string wymagane
Nazwa typu obiektu, zawsze "payment".
-
amount integer wymagane
Kwota w groszach (najmniejszej jednostce waluty).
-
amount_refunded integer
Suma udanych zwrotów w groszach.
-
currency string wymaganePLNEURUSD
-
status string wymagane
pending: czeka na klienta; requires_confirmation: klient jest w trakcie potwierdzania (np. 3D Secure); processing: dostawca przetwarza; succeeded: opłacona; failed: odrzucona; canceled: anulowana albo wygasła.
pendingrequires_confirmationprocessingsucceededfailedcanceled -
method string | null
Metoda, którą klient zapłacił; null przed zapłatą.
blikcardtransfer -
description string | null
Do 255 znaków.
-
checkout_url string (uri) wymagane
Hostowana strona płatności. Skieruj na nią klienta (przekierowanie 302 albo link).
-
return_url string | null
Adres powrotu po zapłacie; klient wraca tam z parametrem ?payment=pay_...
-
customer string | null
Identyfikator klienta (cus_) albo pełny obiekt przy expand[]=customer.
-
customer_email string | null
-
customer_name string | null
-
payment_link string | null
Link (plink_), z którego powstała płatność.
-
subscription string | null
Subskrypcja (sub_), której okres opłaca ta płatność.
-
invoice string | null
Faktura (inv_), którą opłaca ta płatność.
-
tax_id string | null
NIP podany przez klienta na stronie płatności.
-
provider_account string | null
Konto dostawcy, które obsłużyło płatność (Smart routing): "primary" albo identyfikator konta dodatkowego. Tylko produkcja.
-
connected_account string | null
Sprzedawca platformy (Connect), do którego trafia płatność po potrąceniu prowizji.
-
application_fee integer | null
Prowizja platformy w groszach (Connect).
-
failure_code string | null
Kod odmowy: card_declined, blik_rejected, blik_code_invalid, insufficient_funds, stolen_card.
-
decline_code string | null
Surowy kod odmowy od dostawcy płatności (produkcja).
-
metadata object wymagane
Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.
-
livemode boolean wymagane
true dla obiektów produkcyjnych (klucz sk_live_), false dla piaskownicy (sk_test_).
-
expires_at integer | null
Do kiedy strona płatności przyjmuje zapłatę (Unix). Domyślnie 24 godziny.
-
paid_at integer | null
Chwila zapłaty (Unix) albo null.
-
created integer wymagane
Chwila utworzenia jako znacznik czasu Unix (sekundy, UTC).
{
"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
}
Utwórz płatność#
POST /v1/payments
Wymagane tylko amount i currency. Odpowiedź ma checkout_url (hostowana strona płatności). Przepływ dla sklepu: utwórz płatność z return_url i metadata (numer zamówienia), przekieruj klienta na checkout_url, po powrocie potwierdź status przez GET /v1/payments/{id}, a zamówienie oznaczaj po zdarzeniu payment.succeeded z webhooka. Piaskownica: strona płatności ma kody BLIK 777 123 (sukces), 777 000 (odmowa), 777 408 (zły kod) i przyciski wyniku karty; wynik można też ustawić przez POST /v1/test_helpers/payments/{id}/confirm.
Nagłówki opcjonalne: Oplac-Version, Idempotency-Key
Treść żądania JSON
-
amount integer wymagane
Kwota w groszach (najmniejszej jednostce waluty): 12900 to 129,00 zł. Od 100 (1,00). Od 100 do 999999999.
-
currency string wymagane
Waluta. EUR i USD od planu Skala.
PLNEURUSD -
description string
Opis widoczny dla klienta na stronie płatności. Do 255 znaków.
-
return_url string (uri)
Adres powrotu po zapłacie; klient wraca tam z parametrem ?payment=pay_... Stan płatności zawsze potwierdź przez GET /v1/payments/{id} albo webhook, nie z adresu. Do 500 znaków.
-
customer string | object
Identyfikator klienta cus_.
-
email string (email)
Do 190 znaków.
-
name string
Do 190 znaków.
-
tax_id string
NIP. Do 20 znaków.
-
address object | string
Obiekt (line1, line2, city, postal_code, country) albo jeden tekst.
-
line1 string | null
-
line2 string | null
-
city string | null
-
postal_code string | null
-
country string | null
Kod kraju ISO 3166-1 alpha-2, np. PL.
-
-
metadata object
Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.
-
-
customer_email string (email)
-
customer_name string
-
metadata object
Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.
-
expires_at integer
Do kiedy strona płatności przyjmuje zapłatę, znacznik czasu Unix w przyszłości. Domyślnie 24 godziny.
-
connected_account string
Konto sprzedawcy platformy (Connect, plan Platforma), które dostaje płatność po potrąceniu prowizji.
-
application_fee integer
Prowizja platformy w groszach (wymaga connected_account). Od 0.
Odpowiedź
HTTP 201: obiekt payment.
Błędy tej operacji:
parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, provider_not_connected, currency_not_in_plan, connect_not_in_plan, rate_limited, api_error .
Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.
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
}
Pobierz płatność#
GET /v1/payments/{id}
Aktualny stan płatności. W produkcji stan jest odczytywany od dostawcy płatności przy każdym wywołaniu, więc to wiarygodne źródło po powrocie klienta.
Nagłówki opcjonalne: Oplac-Version
Parametry ścieżki
-
id string wymagane
Identyfikator pay_.
Parametry zapytania
-
expand[] array of string
Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: customer, payment_link, subscription, invoice.
customerpayment_linksubscriptioninvoice
Odpowiedź
HTTP 200: obiekt payment.
Błędy tej operacji:
parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, resource_missing, rate_limited, api_error .
Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.
curl https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh', {
headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const payment = await res.json();
import requests
res = requests.get(
"https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh",
headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
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
}
Zmień płatność#
POST /v1/payments/{id}
Zmiana description i metadata. Kwota, waluta i status płatności są stałe.
Nagłówki opcjonalne: Oplac-Version, Idempotency-Key
Parametry ścieżki
-
id string wymagane
Identyfikator pay_.
Treść żądania JSON, opcjonalna
-
description string
Do 255 znaków.
-
metadata object
Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.
Odpowiedź
HTTP 200: obiekt payment.
Błędy tej operacji:
parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, resource_missing, rate_limited, api_error .
Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.
curl https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
-H "Content-Type: application/json" \
-d '{
"description": "Zamówienie 10482",
"metadata": {
"order_id": "10482"
}
}'
$ch = curl_init('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sk_test_TWOJ_KLUCZ',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Zamówienie 10482',
'metadata' => [
'order_id' => '10482',
],
]),
CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
description: 'Zamówienie 10482',
metadata: {
order_id: '10482',
},
}),
});
const payment = await res.json();
import requests
res = requests.post(
"https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh",
headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
json={
"description": "Zamówienie 10482",
"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
}
Lista płatności#
GET /v1/payments
Płatności konta w trybie klucza, od najnowszej.
Nagłówki opcjonalne: Oplac-Version
Parametry zapytania
-
limit integer
Liczba obiektów na stronie (1 do 100). Domyślnie
10. Od 1 do 100. -
starting_after string
Identyfikator obiektu; zwraca starsze od niego (następna strona).
-
ending_before string
Identyfikator obiektu; zwraca nowsze od niego (poprzednia strona). Nie łączyć ze starting_after.
-
created object
Filtr po chwili utworzenia (Unix): created[gte]=1760000000.
-
gt integer
-
gte integer
-
lt integer
-
lte integer
-
-
status string
Filtr statusu.
pendingrequires_confirmationprocessingsucceededfailedcanceled -
customer string
Płatności klienta cus_.
-
payment_link string
Płatności z linku plink_.
-
subscription string
Płatności subskrypcji sub_.
-
invoice string
Płatności faktury inv_.
-
expand[] array of string
Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: customer, payment_link, subscription, invoice.
customerpayment_linksubscriptioninvoice
Odpowiedź
HTTP 200:
lista {object: "list", url, has_more, data} z obiektami
payment od najnowszego. Stronicowanie kursorem opisuje przewodnik.
Błędy tej operacji:
parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, rate_limited, api_error .
Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.
curl "https://oplac.pl/api/v1/payments?limit=3" \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/payments?limit=3');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
CURLOPT_RETURNTRANSFER => true,
]);
$payments = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/payments?limit=3', {
headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const payments = await res.json();
import requests
res = requests.get(
"https://oplac.pl/api/v1/payments?limit=3",
headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
payments = res.json()
{
"object": "list",
"url": "/v1/payments",
"has_more": false,
"data": [
{
"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
}
]
}
Anuluj płatność#
POST /v1/payments/{id}/cancel
Zamyka stronę płatności (w produkcji także u dostawcy). Tylko status pending albo requires_confirmation; opłaconą płatność zwraca się przez POST /v1/refunds.
Nagłówki opcjonalne: Oplac-Version, Idempotency-Key
Parametry ścieżki
-
id string wymagane
Identyfikator pay_.
Treść żądania JSON, opcjonalna
Bez pól. Wyślij puste żądanie albo pusty obiekt JSON.
Odpowiedź
HTTP 200: obiekt payment.
Błędy tej operacji:
parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, resource_missing, payment_not_cancelable, rate_limited, api_error, provider_error .
Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.
curl https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh/cancel \
-X POST \
-H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh/cancel');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh/cancel', {
method: 'POST',
headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const payment = await res.json();
import requests
res = requests.post(
"https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh/cancel",
headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
payment = res.json()
{
"id": "pay_Ab12Cd34Ef56Gh",
"object": "payment",
"amount": 12900,
"amount_refunded": 0,
"currency": "PLN",
"status": "canceled",
"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
}
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.