Przejdź do treści
Oplac

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 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 wymagane
    PLNEURUSD
  • 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).

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
}

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()
Odpowiedź HTTP 201
{
  "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()
Odpowiedź HTTP 200
{
  "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()
Odpowiedź HTTP 200
{
  "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()
Odpowiedź HTTP 200
{
  "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()
Odpowiedź HTTP 200
{
  "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.

Zamów integrację za darmo

BLIK, karty, subskrypcje i KSeF w jednym panelu.