Przejdź do treści
Oplac

Referencja API

Zdarzenia

Historia zdarzeń i ponowna wysyłka.

GET/v1/events/{id}GET/v1/eventsPOST/v1/events/{id}/resend

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 event#

Zdarzenie (evt_). Ta sama treść idzie na webhook (bez pola delivery) i jest dostępna przez GET /v1/events. data.object to migawka obiektu z chwili zdarzenia.

Pola

  • id string wymagane

    Identyfikator zdarzenia.

  • object string wymagane

    Nazwa typu obiektu, zawsze "event".

  • type string wymagane
    payment.createdpayment.succeededpayment.failedpayment.canceledpayment.routedpayment_link.expiredaccount.verifiedpayout.paidrefund.createdrefund.succeededrefund.failedcustomer.createdcustomer.updatedcustomer.deletedsubscription.createdsubscription.updatedsubscription.renewedsubscription.payment_failedsubscription.recoveredsubscription.canceledinvoice.issuedinvoice.paidinvoice.ksef_acceptedinvoice.ksef_rejected
  • api_version string wymagane
  • 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).

  • data object wymagane
    • object object wymagane

      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.

      • id string wymagane

        Identyfikator faktury.

      • object string wymagane

        Nazwa typu obiektu, zawsze "invoice".

      • number string wymagane

        Numer z serii sprzedawcy.

      • type string wymagane
        payablepaidcredit_note
      • corrects string | null

        Faktura pierwotna (inv_) dla korekty.

      • refund string | null

        Zwrot (re_), po którym powstała korekta.

      • status string wymagane
        openpartially_paidpaidrefunded
      • customer_name string | null
      • customer_tax_id string | null
      • customer_email string | null
      • lines array of object
        • nazwa string
        • ilosc number
        • netto integer
      • vat_rate integer | null

        Stawka VAT w procentach.

      • net integer
      • vat integer
      • gross integer wymagane

        Kwota brutto w groszach.

      • amount_paid integer
      • amount_due integer
      • overpaid integer
      • currency string wymagane
      • issue_date string | null
      • due_date string | null
      • disputed boolean
      • payment string | null

        Płatność (pay_), która opłaciła fakturę.

      • payment_url string | null

        Strona płatności faktury (type payable).

      • ksef_status string | null

        Stan w KSeF: null, wyslana, przyjeta, blad.

      • ksef_number string | null
      • 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_).

      • paid_at integer | null
      • created integer wymagane

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

  • request object | null

    Żądanie API, które wywołało zdarzenie; null dla zdarzeń z harmonogramu, strony płatności i panelu.

    • id string | null
    • idempotency_key string | null
  • pending_webhooks integer wymagane

    1, gdy webhook jeszcze nie dotarł i czeka na ponowienie; 0 po doręczeniu albo bez adresu webhooka.

  • delivery object

    Stan doręczenia (tylko w API, nie w treści webhooka).

    • attempts integer
    • last_status integer | null

      Kod HTTP ostatniej odpowiedzi serwera odbiorcy.

    • delivered_at integer | null
    • next_attempt integer | null
JSON 
{
  "id": "evt_Ab12Cd34Ef56Gh",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-10-03",
  "livemode": false,
  "created": 1760000000,
  "data": {
    "object": {
      "id": "pay_Ab12Cd34Ef56Gh",
      "object": "payment",
      "amount": 12900,
      "amount_refunded": 0,
      "currency": "PLN",
      "status": "succeeded",
      "method": "blik",
      "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": 1760000000,
      "created": 1760000000
    }
  },
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "pending_webhooks": 0,
  "delivery": {
    "attempts": 1,
    "last_status": 200,
    "delivered_at": 1760000001,
    "next_attempt": null
  }
}

Pobierz zdarzenie#

GET /v1/events/{id}

Zdarzenie po identyfikatorze, ze stanem doręczenia (delivery).

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator evt_.

Odpowiedź

HTTP 200: obiekt event.

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/events/evt_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$event = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const event = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
event = res.json()
Odpowiedź HTTP 200 
{
  "id": "evt_Ab12Cd34Ef56Gh",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-10-03",
  "livemode": false,
  "created": 1760000000,
  "data": {
    "object": {
      "id": "pay_Ab12Cd34Ef56Gh",
      "object": "payment",
      "amount": 12900,
      "amount_refunded": 0,
      "currency": "PLN",
      "status": "succeeded",
      "method": "blik",
      "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": 1760000000,
      "created": 1760000000
    }
  },
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "pending_webhooks": 0,
  "delivery": {
    "attempts": 1,
    "last_status": 200,
    "delivered_at": 1760000001,
    "next_attempt": null
  }
}

Lista zdarzeń#

GET /v1/events

Historia zdarzeń konta w trybie klucza; to samo, co poszło (albo idzie) na webhook. Do odzyskania zdarzeń po awarii własnego serwera: pobierz zdarzenia z created[gte] i delivered=false.

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
  • type string

    Pełny typ (payment.succeeded) albo rodzina z gwiazdką (payment.*).

  • delivered boolean

    true: doręczone na webhook; false: niedoręczone (czekają na ponowienie albo bez adresu).

Odpowiedź

HTTP 200: lista {object: "list", url, has_more, data} z obiektami event 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/events?limit=3" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/events?limit=3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$events = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/events?limit=3', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const events = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/events?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
events = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_Ab12Cd34Ef56Gh",
      "object": "event",
      "type": "payment.succeeded",
      "api_version": "2026-10-03",
      "livemode": false,
      "created": 1760000000,
      "data": {
        "object": {
          "id": "pay_Ab12Cd34Ef56Gh",
          "object": "payment",
          "amount": 12900,
          "amount_refunded": 0,
          "currency": "PLN",
          "status": "succeeded",
          "method": "blik",
          "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": 1760000000,
          "created": 1760000000
        }
      },
      "request": {
        "id": null,
        "idempotency_key": null
      },
      "pending_webhooks": 0,
      "delivery": {
        "attempts": 1,
        "last_status": 200,
        "delivered_at": 1760000001,
        "next_attempt": null
      }
    }
  ]
}

Wyślij zdarzenie ponownie#

POST /v1/events/{id}/resend

Jedna próba doręczenia teraz, bez zmiany harmonogramu ponowień. Wynik w polu delivery.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator evt_.

Treść żądania JSON, opcjonalna

Bez pól. Wyślij puste żądanie albo pusty obiekt JSON.

Odpowiedź

HTTP 200: obiekt event.

Błędy tej operacji: webhook_not_configured, 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/events/evt_Ab12Cd34Ef56Gh/resend \
  -X POST \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh/resend');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$event = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh/resend', {
  method: 'POST',
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const event = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/events/evt_Ab12Cd34Ef56Gh/resend",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
event = res.json()
Odpowiedź HTTP 200 
{
  "id": "evt_Ab12Cd34Ef56Gh",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-10-03",
  "livemode": false,
  "created": 1760000000,
  "data": {
    "object": {
      "id": "pay_Ab12Cd34Ef56Gh",
      "object": "payment",
      "amount": 12900,
      "amount_refunded": 0,
      "currency": "PLN",
      "status": "succeeded",
      "method": "blik",
      "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": 1760000000,
      "created": 1760000000
    }
  },
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "pending_webhooks": 0,
  "delivery": {
    "attempts": 1,
    "last_status": 200,
    "delivered_at": 1760000001,
    "next_attempt": null
  }
}

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

BLIK, karty, subskrypcje i KSeF w jednym panelu.