Oplac
Dokumentacja
Referencja API
Strony sprzedaży

Referencja API

Strony sprzedaży

Publiczne strony zakupu w marce sprzedawcy, z kodem QR i przyciskiem.

POST/v1/checkout_pagesUtwórz stronę sprzedaży GET/v1/checkout_pages/{id}Pobierz stronę sprzedaży POST/v1/checkout_pages/{id}Zmień stronę sprzedaży GET/v1/checkout_pagesLista stron sprzedaży

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

Obiekt `checkout_page`#

Strona sprzedaży (cpage_): publiczny adres https://oplac.pl/k/<kod> w marce sprzedawcy (kolor i logo z panelu), na którym klient kupuje produkt bez sklepu. Zakup to zwykła płatność (pay_) albo subskrypcja (sub_) z tymi samymi zdarzeniami, fakturami i webhookami co w API; metadata płatności ma checkout_page i product. Kod QR, przycisk HTML do wklejenia i statystyki w obiekcie.

Pola

id string wymagane

Identyfikator strony sprzedaży.
object string wymagane

Nazwa typu obiektu, zawsze "checkout_page".
product string wymagane

Produkt (prod_) albo pełny obiekt przy expand[]=product.
url string (uri) wymagane

Adres strony sprzedaży do wysłania klientom (Instagram, Facebook, SMS, e-mail).
qr_code_url string (uri) wymagane

Kod QR strony jako PNG.
button_html string wymagane

Gotowy przycisk „Kup teraz” (zwykły link bez skryptów) do wklejenia na dowolną stronę.
fields object wymagane

Pola dla kupującego poza e-mailem i nazwą (zawsze obecne): address (adres), tax_id (NIP do faktury), phone (telefon), coupon (kod rabatowy z kuponów Bill, od planu Firma).
- address boolean
- tax_id boolean
- phone boolean
- coupon boolean
quantity_max integer wymagane

Największa ilość w jednym zamówieniu; 1 to bez wyboru ilości. Subskrypcja zawsze 1. Od 1 do 99.
success_url string | null

Adres, na który klient trafia po zapłacie (z ?payment=pay_... albo ?subscription=sub_...); null to strona podziękowania Oplac.
message string | null

Komunikat na stronie podziękowania (gdy nie ma success_url). Do 1000 znaków.
active boolean wymagane

Wyłączona strona pokazuje informację o wstrzymanej sprzedaży.
stats object wymagane

Statystyki strony: views (wyświetlenia), payments (opłacone płatności, także okresy subskrypcji), revenue (przychód brutto w groszach).
- views integer
- payments integer
- revenue integer
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_).
created integer wymagane

Chwila utworzenia jako znacznik czasu Unix (sekundy, UTC).

Obiekt checkout_page JSON

{
  "id": "cpage_Ab12Cd34Ef56Gh",
  "object": "checkout_page",
  "product": "prod_Ab12Cd34Ef56Gh",
  "url": "https://oplac.pl/k/Kx7Pq2MnAb12",
  "qr_code_url": "https://oplac.pl/k/Kx7Pq2MnAb12/qr.png",
  "button_html": "<a href=\"https://oplac.pl/k/Kx7Pq2MnAb12\" style=\"display:inline-block;background:#0A1F44;color:#fff;padding:12px 22px;border-radius:6px;font:600 15px Inter,Arial,sans-serif;text-decoration:none\">Kup teraz</a>",
  "fields": {
    "address": false,
    "tax_id": true,
    "phone": false,
    "coupon": false
  },
  "quantity_max": 1,
  "success_url": null,
  "message": "Dostęp wyślemy w ciągu godziny.",
  "active": true,
  "stats": {
    "views": 318,
    "payments": 24,
    "revenue": 309600
  },
  "metadata": [],
  "livemode": false,
  "created": 1760000000
}

Utwórz stronę sprzedaży#

POST /v1/checkout_pages

Publiczna strona zakupu produktu w marce sprzedawcy (kolor i logo z panelu), bez sklepu i bez kodu. Odpowiedź ma url do wysłania klientom, qr_code_url i button_html do wklejenia na dowolną stronę. Zakup tworzy płatność (pay_) z metadata.checkout_page albo subskrypcję (sub_) i daje te same zdarzenia payment.* i subscription.* co API; kupujący zostaje klientem (cus_). Po zapłacie klient trafia na success_url (z ?payment= albo ?subscription=) albo na stronę podziękowania z message.

Nagłówki opcjonalne: Oplac-Version, Idempotency-Key

Treść żądania JSON

product string wymagane

Produkt prod_ (włączony).
fields object

Pola dla kupującego poza e-mailem i nazwą (zawsze obecne): address (adres), tax_id (NIP do faktury), phone (telefon), coupon (kod rabatowy z kuponów Bill, od planu Firma).
- address boolean
- tax_id boolean
- phone boolean
- coupon boolean
quantity_max integer

Największa ilość w zamówieniu (tylko one_time). Domyślnie 1. Od 1 do 99.
success_url string (uri)

Adres https po zapłacie. Do 500 znaków.
message string

Komunikat na stronie podziękowania. Do 1000 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 201: obiekt checkout_page.

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, sandbox_limit_reached, module_not_in_plan, resource_missing, product_inactive, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy.

POST /v1/checkout_pages

curl https://oplac.pl/api/v1/checkout_pages \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "product": "prod_Ab12Cd34Ef56Gh",
  "fields": {
    "tax_id": true
  },
  "message": "Dostęp wyślemy w ciągu godziny."
}'

$ch = curl_init('https://oplac.pl/api/v1/checkout_pages');
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([
        'product' => 'prod_Ab12Cd34Ef56Gh',
        'fields' => [
            'tax_id' => true,
        ],
        'message' => 'Dostęp wyślemy w ciągu godziny.',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$checkout_page = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/checkout_pages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product: 'prod_Ab12Cd34Ef56Gh',
    fields: {
      tax_id: true,
    },
    message: 'Dostęp wyślemy w ciągu godziny.',
  }),
});
const checkoutPage = await res.json();

import requests

res = requests.post(
    "https://oplac.pl/api/v1/checkout_pages",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "product": "prod_Ab12Cd34Ef56Gh",
        "fields": {
            "tax_id": True,
        },
        "message": "Dostęp wyślemy w ciągu godziny.",
    },
)
checkout_page = res.json()

Odpowiedź HTTP 201

{
  "id": "cpage_Ab12Cd34Ef56Gh",
  "object": "checkout_page",
  "product": "prod_Ab12Cd34Ef56Gh",
  "url": "https://oplac.pl/k/Kx7Pq2MnAb12",
  "qr_code_url": "https://oplac.pl/k/Kx7Pq2MnAb12/qr.png",
  "button_html": "<a href=\"https://oplac.pl/k/Kx7Pq2MnAb12\" style=\"display:inline-block;background:#0A1F44;color:#fff;padding:12px 22px;border-radius:6px;font:600 15px Inter,Arial,sans-serif;text-decoration:none\">Kup teraz</a>",
  "fields": {
    "address": false,
    "tax_id": true,
    "phone": false,
    "coupon": false
  },
  "quantity_max": 1,
  "success_url": null,
  "message": "Dostęp wyślemy w ciągu godziny.",
  "active": true,
  "stats": {
    "views": 318,
    "payments": 24,
    "revenue": 309600
  },
  "metadata": [],
  "livemode": false,
  "created": 1760000000
}

Pobierz stronę sprzedaży#

GET /v1/checkout_pages/{id}

Strona po identyfikatorze, ze statystykami (views, payments, revenue).

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

id string wymagane

Identyfikator cpage_.

Parametry zapytania

expand[] array of string

Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: product.

product

Odpowiedź

HTTP 200: obiekt checkout_page.

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.

GET /v1/checkout_pages/{id}

curl https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"

$ch = curl_init('https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$checkout_page = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const checkoutPage = await res.json();

import requests

res = requests.get(
    "https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
checkout_page = res.json()

Odpowiedź HTTP 200

{
  "id": "cpage_Ab12Cd34Ef56Gh",
  "object": "checkout_page",
  "product": "prod_Ab12Cd34Ef56Gh",
  "url": "https://oplac.pl/k/Kx7Pq2MnAb12",
  "qr_code_url": "https://oplac.pl/k/Kx7Pq2MnAb12/qr.png",
  "button_html": "<a href=\"https://oplac.pl/k/Kx7Pq2MnAb12\" style=\"display:inline-block;background:#0A1F44;color:#fff;padding:12px 22px;border-radius:6px;font:600 15px Inter,Arial,sans-serif;text-decoration:none\">Kup teraz</a>",
  "fields": {
    "address": false,
    "tax_id": true,
    "phone": false,
    "coupon": false
  },
  "quantity_max": 1,
  "success_url": null,
  "message": "Dostęp wyślemy w ciągu godziny.",
  "active": true,
  "stats": {
    "views": 318,
    "payments": 24,
    "revenue": 309600
  },
  "metadata": [],
  "livemode": false,
  "created": 1760000000
}

Zmień stronę sprzedaży#

POST /v1/checkout_pages/{id}

active (wyłączenie i włączenie), fields, quantity_max, success_url, message, metadata. Produkt strony jest stały.

Nagłówki opcjonalne: Oplac-Version, Idempotency-Key

Parametry ścieżki

id string wymagane

Identyfikator cpage_.

Treść żądania JSON, opcjonalna

active boolean
fields object

Pola dla kupującego poza e-mailem i nazwą (zawsze obecne): address (adres), tax_id (NIP do faktury), phone (telefon), coupon (kod rabatowy z kuponów Bill, od planu Firma).
- address boolean
- tax_id boolean
- phone boolean
- coupon boolean
quantity_max integer

Od 1 do 99.
success_url string (uri)

Do 500 znaków.
message string

Do 1000 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 checkout_page.

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.

POST /v1/checkout_pages/{id}

curl https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'

$ch = curl_init('https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'active' => false,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$checkout_page = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    active: false,
  }),
});
const checkoutPage = await res.json();

import requests

res = requests.post(
    "https://oplac.pl/api/v1/checkout_pages/cpage_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "active": False,
    },
)
checkout_page = res.json()

Odpowiedź HTTP 200

{
  "id": "cpage_Ab12Cd34Ef56Gh",
  "object": "checkout_page",
  "product": "prod_Ab12Cd34Ef56Gh",
  "url": "https://oplac.pl/k/Kx7Pq2MnAb12",
  "qr_code_url": "https://oplac.pl/k/Kx7Pq2MnAb12/qr.png",
  "button_html": "<a href=\"https://oplac.pl/k/Kx7Pq2MnAb12\" style=\"display:inline-block;background:#0A1F44;color:#fff;padding:12px 22px;border-radius:6px;font:600 15px Inter,Arial,sans-serif;text-decoration:none\">Kup teraz</a>",
  "fields": {
    "address": false,
    "tax_id": true,
    "phone": false,
    "coupon": false
  },
  "quantity_max": 1,
  "success_url": null,
  "message": "Dostęp wyślemy w ciągu godziny.",
  "active": true,
  "stats": {
    "views": 318,
    "payments": 24,
    "revenue": 309600
  },
  "metadata": [],
  "livemode": false,
  "created": 1760000000
}

Lista stron sprzedaży#

GET /v1/checkout_pages

Strony konta w trybie klucza, ze statystykami.

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
active boolean

Tylko włączone albo wyłączone.
product string

Strony jednego produktu prod_.
expand[] array of string

Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: product.

product

Odpowiedź

HTTP 200: lista {object: "list", url, has_more, data} z obiektami checkout_page 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.

GET /v1/checkout_pages

curl "https://oplac.pl/api/v1/checkout_pages?limit=3" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"

$ch = curl_init('https://oplac.pl/api/v1/checkout_pages?limit=3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$checkout_pages = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/checkout_pages?limit=3', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const checkoutPages = await res.json();

import requests

res = requests.get(
    "https://oplac.pl/api/v1/checkout_pages?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
checkout_pages = res.json()

Odpowiedź HTTP 200

{
  "object": "list",
  "url": "/v1/checkout_pages",
  "has_more": false,
  "data": [
    {
      "id": "cpage_Ab12Cd34Ef56Gh",
      "object": "checkout_page",
      "product": "prod_Ab12Cd34Ef56Gh",
      "url": "https://oplac.pl/k/Kx7Pq2MnAb12",
      "qr_code_url": "https://oplac.pl/k/Kx7Pq2MnAb12/qr.png",
      "button_html": "<a href=\"https://oplac.pl/k/Kx7Pq2MnAb12\" style=\"display:inline-block;background:#0A1F44;color:#fff;padding:12px 22px;border-radius:6px;font:600 15px Inter,Arial,sans-serif;text-decoration:none\">Kup teraz</a>",
      "fields": {
        "address": false,
        "tax_id": true,
        "phone": false,
        "coupon": false
      },
      "quantity_max": 1,
      "success_url": null,
      "message": "Dostęp wyślemy w ciągu godziny.",
      "active": true,
      "stats": {
        "views": 318,
        "payments": 24,
        "revenue": 309600
      },
      "metadata": [],
      "livemode": false,
      "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.

Zamów integrację za darmo

Obiekt checkout_page#

Pola

Utwórz stronę sprzedaży#

Treść żądania JSON

Odpowiedź

Pobierz stronę sprzedaży#

Parametry ścieżki

Parametry zapytania

Odpowiedź

Zmień stronę sprzedaży#

Parametry ścieżki

Treść żądania JSON, opcjonalna

Odpowiedź

Lista stron sprzedaży#

Parametry zapytania

Odpowiedź

Klucz testowy dostajesz od razu po zapisie

Obiekt `checkout_page`#