Przejdź do treści
Oplac

Referencja API

Piaskownica

Pomocnicy testowi dla klucza sk_test_.

POST/v1/test_helpers/webhooksPOST/v1/test_helpers/payments/{id}/confirmPOST/v1/test_helpers/subscriptions/{id}/confirmPOST/v1/test_helpers/subscriptions/{id}/renew

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

Wyślij zdarzenie próbne#

POST /v1/test_helpers/webhooks

Zdarzenie wybranego typu z przykładowym obiektem na adres webhooka trybu testowego, z prawdziwym podpisem. Sprawdza adres, podpis i obsługę typu po stronie integracji.

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

Treść żądania JSON, opcjonalna

  • type string

    Domyślnie 'payment.succeeded'.

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

Błędy tej operacji: webhook_not_configured, api_key_invalid, test_helpers_live_mode, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

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

res = requests.post(
    "https://oplac.pl/api/v1/test_helpers/webhooks",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "type": "payment.succeeded",
    },
)
event = res.json()
Odpowiedź HTTP 201 
{
  "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
  }
}

Ustaw wynik płatności testowej#

POST /v1/test_helpers/payments/{id}/confirm

Zamiast klikać na stronie płatności piaskownicy. outcome: succeeded (domyślnie) albo failed (card_declined); blik_code: 777123 sukces, 777000 odmowa (blik_rejected), 777408 zły kod (blik_code_invalid). Uruchamia te same zdarzenia, webhooki i faktury co prawdziwa zapłata.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator pay_ płatności testowej.

Treść żądania JSON, opcjonalna

  • outcome string

    Domyślnie 'succeeded'.

    succeededfailed
  • method string

    Domyślnie 'card'.

    blikcard
  • blik_code string
    777123777000777408

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

curl https://oplac.pl/api/v1/test_helpers/payments/pay_Ab12Cd34Ef56Gh/confirm \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "blik_code": "777123"
}'
$ch = curl_init('https://oplac.pl/api/v1/test_helpers/payments/pay_Ab12Cd34Ef56Gh/confirm');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'blik_code' => '777123',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/test_helpers/payments/pay_Ab12Cd34Ef56Gh/confirm', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    blik_code: '777123',
  }),
});
const payment = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/test_helpers/payments/pay_Ab12Cd34Ef56Gh/confirm",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "blik_code": "777123",
    },
)
payment = res.json()
Odpowiedź HTTP 200 
{
  "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
}

Opłać pierwszy okres subskrypcji testowej#

POST /v1/test_helpers/subscriptions/{id}/confirm

Subskrypcja incomplete przechodzi w active (albo trialing przy okresie próbnym) i wysyła subscription.created; outcome failed zostawia incomplete z nieudaną płatnością.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator sub_ subskrypcji testowej.

Treść żądania JSON, opcjonalna

  • outcome string

    Domyślnie 'succeeded'.

    succeededfailed
  • method string

    Domyślnie 'card'.

    blikcard

Odpowiedź

HTTP 200: obiekt subscription.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, test_helpers_live_mode, resource_missing, subscription_not_active, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/confirm \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "succeeded",
  "method": "blik"
}'
$ch = curl_init('https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/confirm');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'outcome' => 'succeeded',
        'method' => 'blik',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$subscription = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/confirm', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    outcome: 'succeeded',
    method: 'blik',
  }),
});
const subscription = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/confirm",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "outcome": "succeeded",
        "method": "blik",
    },
)
subscription = res.json()
Odpowiedź HTTP 200 
{
  "id": "sub_Ab12Cd34Ef56Gh",
  "object": "subscription",
  "plan": "plan_Ab12Cd34Ef56Gh",
  "status": "active",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "customer_email": "[email protected]",
  "customer_name": "Anna Nowak",
  "tax_id": null,
  "coupon": null,
  "amount": 4900,
  "currency": "PLN",
  "interval": "month",
  "trial_end": null,
  "current_period_start": 1760000000,
  "current_period_end": 1762592000,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "credit_balance": 0,
  "last_decline_code": null,
  "checkout_url": "https://oplac.pl/s/Kx7Pq2MnAb12",
  "metadata": [],
  "livemode": false,
  "created": 1760000000
}

Symuluj odnowienie subskrypcji testowej#

POST /v1/test_helpers/subscriptions/{id}/renew

Odnowienie przed terminem: succeeded (payment.succeeded, subscription.renewed), failed (odmowa przejściowa insufficient_funds, status past_due, subscription.payment_failed, Recover ponawia) albo failed_permanently (stolen_card, odmowa trwała).

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

Parametry ścieżki

  • id string wymagane

    Identyfikator sub_ subskrypcji testowej.

Treść żądania JSON, opcjonalna

  • outcome string

    Domyślnie 'succeeded'.

    succeededfailedfailed_permanently

Odpowiedź

HTTP 200: obiekt subscription.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, test_helpers_live_mode, resource_missing, subscription_not_active, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/renew \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "succeeded"
}'
$ch = curl_init('https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/renew');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'outcome' => 'succeeded',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$subscription = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/renew', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    outcome: 'succeeded',
  }),
});
const subscription = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/test_helpers/subscriptions/sub_Ab12Cd34Ef56Gh/renew",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "outcome": "succeeded",
    },
)
subscription = res.json()
Odpowiedź HTTP 200 
{
  "id": "sub_Ab12Cd34Ef56Gh",
  "object": "subscription",
  "plan": "plan_Ab12Cd34Ef56Gh",
  "status": "active",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "customer_email": "[email protected]",
  "customer_name": "Anna Nowak",
  "tax_id": null,
  "coupon": null,
  "amount": 4900,
  "currency": "PLN",
  "interval": "month",
  "trial_end": null,
  "current_period_start": 1760000000,
  "current_period_end": 1762592000,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "credit_balance": 0,
  "last_decline_code": null,
  "checkout_url": "https://oplac.pl/s/Kx7Pq2MnAb12",
  "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

BLIK, karty, subskrypcje i KSeF w jednym panelu.