Przejdź do treści
Oplac

Referencja API

Portal klienta

Jednorazowe adresy wejścia do portalu klienta końcowego.

POST/v1/portal_sessionsGET/v1/portal_sessions/{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 portal_session#

Sesja portalu klienta (bps_): jednorazowy adres (url), pod którym klient końcowy sprzedawcy wchodzi bez hasła do swoich płatności, faktur PDF i subskrypcji (nowa karta, rezygnacja z końcem okresu, zmiana planu, dane do faktury; zakres zmian ustawia sprzedawca w panelu). Adres działa godzinę i raz; po wejściu sesja trwa dwie godziny. url wraca wyłącznie przy utworzeniu.

Pola

  • id string wymagane

    Identyfikator sesji.

  • object string wymagane

    Nazwa typu obiektu, zawsze "portal_session".

  • customer string | null

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

  • customer_email string | null
  • url string | null wymagane

    Jednorazowy adres wejścia do portalu (tylko w odpowiedzi na utworzenie).

  • return_url string | null
  • expires_at integer | null

    Do kiedy działa adres wejścia (Unix).

  • 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": "bps_Ab12Cd34Ef56Gh",
  "object": "portal_session",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "customer_email": "[email protected]",
  "url": "https://oplac.pl/portal/wejscie/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90Uv12Wx34",
  "return_url": "https://app.example.com/konto",
  "expires_at": 1760003600,
  "livemode": false,
  "created": 1760000000
}

Utwórz sesję portalu klienta#

POST /v1/portal_sessions

Jednorazowy adres wejścia do portalu klienta dla klienta cus_ albo adresu e-mail: wstaw go w przycisku „Moje płatności” w swojej aplikacji albo w mailu. Klient widzi tylko swoje płatności, faktury PDF i subskrypcje i robi to, na co pozwalają ustawienia portalu w panelu (rezygnacja z końcem okresu, zmiana planu, nowa karta, dane do faktury). Każda zmiana wysyła subscription.updated albo customer.updated. Adres działa godzinę i raz. Portal musi być włączony w panelu (inaczej 400 portal_disabled).

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

Treść żądania JSON, opcjonalna

  • customer string

    Klient cus_ (wymagany, gdy nie ma customer_email).

  • customer_email string (email)

    Adres klienta (wymagany, gdy nie ma customer).

  • return_url string (uri)

    Adres https Twojej aplikacji, do którego klient wraca z portalu. Do 500 znaków.

Odpowiedź

HTTP 201: obiekt portal_session.

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

res = requests.post(
    "https://oplac.pl/api/v1/portal_sessions",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "customer": "cus_Xy98Zw76Vu54Ts",
        "return_url": "https://app.example.com/konto",
    },
)
portal_session = res.json()
Odpowiedź HTTP 201 
{
  "id": "bps_Ab12Cd34Ef56Gh",
  "object": "portal_session",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "customer_email": "[email protected]",
  "url": "https://oplac.pl/portal/wejscie/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90Uv12Wx34",
  "return_url": "https://app.example.com/konto",
  "expires_at": 1760003600,
  "livemode": false,
  "created": 1760000000
}

Pobierz sesję portalu#

GET /v1/portal_sessions/{id}

Sesja po identyfikatorze, bez adresu wejścia (url wraca tylko przy utworzeniu).

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator bps_.

Parametry zapytania

  • expand[] array of string

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

    customer

Odpowiedź

HTTP 200: obiekt portal_session.

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

res = requests.get(
    "https://oplac.pl/api/v1/portal_sessions/bps_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
portal_session = res.json()
Odpowiedź HTTP 200 
{
  "id": "bps_Ab12Cd34Ef56Gh",
  "object": "portal_session",
  "customer": "cus_Xy98Zw76Vu54Ts",
  "customer_email": "[email protected]",
  "url": "https://oplac.pl/portal/wejscie/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90Uv12Wx34",
  "return_url": "https://app.example.com/konto",
  "expires_at": 1760003600,
  "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.