Przejdź do treści
Oplac

Referencja API

Webhooki

Adres webhooka i sekret podpisu.

POST/v1/webhook_endpointsGET/v1/webhook_endpoints/{id}POST/v1/webhook_endpoints/{id}GET/v1/webhook_endpointsDELETE/v1/webhook_endpoints/{id}

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

Adres webhooka (we_) trybu klucza: jeden na tryb. Sekret whsec_ wraca tylko przy utworzeniu i przy rotate_secret.

Pola

  • id string wymagane
  • object string wymagane

    Nazwa typu obiektu, zawsze "webhook_endpoint".

  • url string (uri) wymagane
  • enabled_events array of string wymagane

    Lista typów zdarzeń albo ["*"] dla wszystkich.

  • status string wymagane
    enabled
  • secret string

    Sekret podpisu whsec_ (tylko przy utworzeniu i rotacji).

  • livemode boolean wymagane

    true dla obiektów produkcyjnych (klucz sk_live_), false dla piaskownicy (sk_test_).

  • created integer

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

JSON 
{
  "id": "we_test_Ab12Cd34Ef56Gh",
  "object": "webhook_endpoint",
  "url": "https://sklep.example.com/oplac/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.failed",
    "refund.succeeded"
  ],
  "status": "enabled",
  "secret": "whsec_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90",
  "livemode": false,
  "created": 1760000000
}

Zapisz adres webhooka#

POST /v1/webhook_endpoints

Adres https na publicznym serwerze i lista zdarzeń (albo ["*"]). Odpowiedź zawiera sekret whsec_ do sprawdzania podpisu; zapisz go, nie wraca w GET. Ponowny POST zastępuje adres i wydaje nowy sekret.

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

Treść żądania JSON

  • url string (uri) wymagane

    Do 500 znaków.

  • enabled_events array of string

    Domyślnie ["*"].

    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*

Odpowiedź

HTTP 201: obiekt webhook_endpoint.

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/webhook_endpoints \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://sklep.example.com/oplac/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.failed",
    "refund.succeeded"
  ]
}'
$ch = curl_init('https://oplac.pl/api/v1/webhook_endpoints');
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([
        'url' => 'https://sklep.example.com/oplac/webhook',
        'enabled_events' => ['payment.succeeded', 'payment.failed', 'refund.succeeded'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$webhook_endpoint = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/webhook_endpoints', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://sklep.example.com/oplac/webhook',
    enabled_events: ['payment.succeeded', 'payment.failed', 'refund.succeeded'],
  }),
});
const webhookEndpoint = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/webhook_endpoints",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "url": "https://sklep.example.com/oplac/webhook",
        "enabled_events": ["payment.succeeded", "payment.failed", "refund.succeeded"],
    },
)
webhook_endpoint = res.json()
Odpowiedź HTTP 201 
{
  "id": "we_test_Ab12Cd34Ef56Gh",
  "object": "webhook_endpoint",
  "url": "https://sklep.example.com/oplac/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.failed",
    "refund.succeeded"
  ],
  "status": "enabled",
  "secret": "whsec_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90",
  "livemode": false,
  "created": 1760000000
}

Pobierz adres webhooka#

GET /v1/webhook_endpoints/{id}

Adres po identyfikatorze (bez sekretu).

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator we_.

Odpowiedź

HTTP 200: obiekt webhook_endpoint.

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

res = requests.get(
    "https://oplac.pl/api/v1/webhook_endpoints/we_test_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
webhook_endpoint = res.json()
Odpowiedź HTTP 200 
{
  "id": "we_test_Ab12Cd34Ef56Gh",
  "object": "webhook_endpoint",
  "url": "https://sklep.example.com/oplac/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.failed",
    "refund.succeeded"
  ],
  "status": "enabled",
  "secret": "whsec_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90",
  "livemode": false,
  "created": 1760000000
}

Zmień adres webhooka#

POST /v1/webhook_endpoints/{id}

url, enabled_events, rotate_secret (true: nowy sekret w odpowiedzi, stary przestaje działać od razu).

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

Parametry ścieżki

  • id string wymagane

    Identyfikator we_.

Treść żądania JSON, opcjonalna

  • url string (uri)
  • enabled_events array of string
  • rotate_secret boolean

    Domyślnie false.

Odpowiedź

HTTP 200: obiekt webhook_endpoint.

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/webhook_endpoints/we_test_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://sklep.example.com/powrot",
  "enabled_events": [],
  "rotate_secret": false
}'
$ch = curl_init('https://oplac.pl/api/v1/webhook_endpoints/we_test_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://sklep.example.com/powrot',
        'enabled_events' => [],
        'rotate_secret' => false,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$webhook_endpoint = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/webhook_endpoints/we_test_Ab12Cd34Ef56Gh', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://sklep.example.com/powrot',
    enabled_events: [],
    rotate_secret: false,
  }),
});
const webhookEndpoint = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/webhook_endpoints/we_test_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "url": "https://sklep.example.com/powrot",
        "enabled_events": [],
        "rotate_secret": False,
    },
)
webhook_endpoint = res.json()
Odpowiedź HTTP 200 
{
  "id": "we_test_Ab12Cd34Ef56Gh",
  "object": "webhook_endpoint",
  "url": "https://sklep.example.com/oplac/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.failed",
    "refund.succeeded"
  ],
  "status": "enabled",
  "secret": "whsec_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90",
  "livemode": false,
  "created": 1760000000
}

Lista adresów webhooka#

GET /v1/webhook_endpoints

Adres webhooka trybu klucza (jeden na tryb) albo pusta lista.

Nagłówki opcjonalne: Oplac-Version

Odpowiedź

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

res = requests.get(
    "https://oplac.pl/api/v1/webhook_endpoints",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
webhook_endpoints = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/webhook_endpoints",
  "has_more": false,
  "data": [
    {
      "id": "we_test_Ab12Cd34Ef56Gh",
      "object": "webhook_endpoint",
      "url": "https://sklep.example.com/oplac/webhook",
      "enabled_events": [
        "payment.succeeded",
        "payment.failed",
        "refund.succeeded"
      ],
      "status": "enabled",
      "secret": "whsec_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90",
      "livemode": false,
      "created": 1760000000
    }
  ]
}

Usuń adres webhooka#

DELETE /v1/webhook_endpoints/{id}

Zdarzenia zostają w historii (GET /v1/events), nic nie jest wysyłane.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator we_.

Odpowiedź

HTTP 200: obiekt {id, object, deleted: true}; usuniętego obiektu nie da się już zmieniać.

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

res = requests.delete(
    "https://oplac.pl/api/v1/webhook_endpoints/we_test_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
deleted = res.json()
Odpowiedź HTTP 200 
{
  "id": "we_test_Ab12Cd34Ef56Gh",
  "object": "webhook_endpoint",
  "deleted": true,
  "livemode": false
}

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.