Przejdź do treści
Oplac

Referencja API

Subskrypcje

Płatności cykliczne z okresem próbnym, proracją i Recover.

POST/v1/subscriptionsGET/v1/subscriptions/{id}POST/v1/subscriptions/{id}GET/v1/subscriptionsPOST/v1/subscriptions/{id}/cancel

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

Subskrypcja (sub_) klienta sprzedawcy. Po utworzeniu ma status incomplete i checkout_url (strona zapisu); po opłaceniu pierwszego okresu active (albo trialing przy okresie próbnym). Nieudane odnowienie daje past_due i uruchamia Recover.

Pola

  • id string wymagane

    Identyfikator subskrypcji.

  • object string wymagane

    Nazwa typu obiektu, zawsze "subscription".

  • plan string wymagane

    Plan (plan_) albo pełny obiekt przy expand[]=plan.

  • status string wymagane
    incompletetrialingactivepast_duecanceled
  • customer string | null

    Klient (cus_) albo obiekt przy expand[]=customer.

  • customer_email string | null
  • customer_name string | null
  • tax_id string | null
  • coupon string | null
  • amount integer

    Kwota okresu z planu, przed rabatem.

  • currency string
  • interval string
    monthyear
  • trial_end integer | null
  • current_period_start integer | null
  • current_period_end integer | null
  • cancel_at_period_end boolean

    true: subskrypcja kończy się po bieżącym opłaconym okresie.

  • canceled_at integer | null
  • credit_balance integer | null

    Kredyt z proracji w groszach, odliczany od następnego odnowienia.

  • last_decline_code string | null

    Kod ostatniej odmowy przy odnowieniu (insufficient_funds, stolen_card, card_declined).

  • checkout_url string (uri) wymagane

    Strona zapisu klienta (pierwsza płatność, zapis karty u dostawcy).

  • proration object

    Tylko w odpowiedzi na zmianę planu: charged (dopłata pobrana teraz) i credited (kredyt na następny okres), w groszach.

    • charged integer
    • credited 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).

JSON 
{
  "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
}

Utwórz subskrypcję#

POST /v1/subscriptions

Wymagany tylko plan. Klient z pola customer (cus_) albo z customer_email. Odpowiedź ma status incomplete i checkout_url (strona zapisu). Po opłaceniu pierwszego okresu status active, zdarzenie subscription.created; każde odnowienie to payment.succeeded i subscription.renewed; nieudane odnowienie to subscription.payment_failed, status past_due i ponowienia Recover.

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

Treść żądania JSON

  • plan string wymagane

    Identyfikator planu plan_.

  • customer string

    Klient cus_.

  • coupon string

    Identyfikator coupon_ albo kod rabatowy.

  • customer_email string (email)
  • customer_name string
  • tax_id string
  • 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.

  • 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 subscription.

Błędy tej operacji: coupon_invalid, parameter_missing, api_key_invalid, module_not_in_plan, 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/subscriptions \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "plan_Ab12Cd34Ef56Gh",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "coupon": "START20",
  "return_url": "https://app.example.com/witaj"
}'
$ch = curl_init('https://oplac.pl/api/v1/subscriptions');
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([
        'plan' => 'plan_Ab12Cd34Ef56Gh',
        'customer' => 'cus_Xy98Zw76Vu54Ts',
        'coupon' => 'START20',
        'return_url' => 'https://app.example.com/witaj',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$subscription = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    plan: 'plan_Ab12Cd34Ef56Gh',
    customer: 'cus_Xy98Zw76Vu54Ts',
    coupon: 'START20',
    return_url: 'https://app.example.com/witaj',
  }),
});
const subscription = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/subscriptions",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "plan": "plan_Ab12Cd34Ef56Gh",
        "customer": "cus_Xy98Zw76Vu54Ts",
        "coupon": "START20",
        "return_url": "https://app.example.com/witaj",
    },
)
subscription = res.json()
Odpowiedź HTTP 201 
{
  "id": "sub_Ab12Cd34Ef56Gh",
  "object": "subscription",
  "plan": "plan_Ab12Cd34Ef56Gh",
  "status": "incomplete",
  "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": null,
  "current_period_end": null,
  "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
}

Pobierz subskrypcję#

GET /v1/subscriptions/{id}

Subskrypcja po identyfikatorze.

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator sub_.

Parametry zapytania

  • expand[] array of string

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

    customerplancoupon

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

res = requests.get(
    "https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
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
}

Zmień subskrypcję#

POST /v1/subscriptions/{id}

plan: zmiana planu z proracją (pole proration w odpowiedzi: dopłata pobrana teraz i kredyt na następny okres); cancel_at_period_end: true kończy po opłaconym okresie, false cofa rezygnację; metadata. Pola można łączyć.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator sub_.

Treść żądania JSON, opcjonalna

  • plan string
  • cancel_at_period_end boolean
  • 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 subscription.

Błędy tej operacji: currency_mismatch, parameter_missing, api_key_invalid, module_not_in_plan, resource_missing, subscription_not_active, 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/subscriptions/sub_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "plan_Zz99Yy88Xx77Ww"
}'
$ch = curl_init('https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'plan' => 'plan_Zz99Yy88Xx77Ww',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$subscription = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    plan: 'plan_Zz99Yy88Xx77Ww',
  }),
});
const subscription = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "plan": "plan_Zz99Yy88Xx77Ww",
    },
)
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
}

Lista subskrypcji#

GET /v1/subscriptions

Subskrypcje konta w trybie klucza.

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.

    incompletetrialingactivepast_duecanceled
  • customer string

    Subskrypcje klienta cus_.

  • plan string

    Subskrypcje planu plan_.

  • expand[] array of string

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

    customerplancoupon

Odpowiedź

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

res = requests.get(
    "https://oplac.pl/api/v1/subscriptions?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
subscriptions = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}

Anuluj subskrypcję#

POST /v1/subscriptions/{id}/cancel

Domyślnie na koniec opłaconego okresu (cancel_at_period_end: true, status bez zmian); at_period_end: false kończy od razu (status canceled, zdarzenie subscription.canceled).

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

Parametry ścieżki

  • id string wymagane

    Identyfikator sub_.

Treść żądania JSON, opcjonalna

  • at_period_end boolean

    Domyślnie true.

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, module_not_in_plan, resource_missing, subscription_not_active, 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/subscriptions/sub_Ab12Cd34Ef56Gh/cancel \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "at_period_end": true
}'
$ch = curl_init('https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh/cancel');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'at_period_end' => true,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$subscription = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    at_period_end: true,
  }),
});
const subscription = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/subscriptions/sub_Ab12Cd34Ef56Gh/cancel",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "at_period_end": True,
    },
)
subscription = res.json()
Odpowiedź HTTP 200 
{
  "id": "sub_Ab12Cd34Ef56Gh",
  "object": "subscription",
  "plan": "plan_Ab12Cd34Ef56Gh",
  "status": "canceled",
  "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": 1760000000,
  "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.