Podstawy API

Rozwijanie obiektów (expand)

Pola z identyfikatorem innego obiektu (customer, payment, plan, coupon, invoice) domyślnie zwracają sam identyfikator. Parametr expand[] każe zwrócić w ich miejscu pełny obiekt, więc zamiast dwóch żądań robisz jedno. Działa na pojedynczym obiekcie i na listach, także z zagnieżdżaniem.

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

Jak używać#

Na pojedynczym obiekcie: GET /v1/payments/{id}?expand[]=customer.
Kilka pól: powtórz parametr, expand[]=customer&expand[]=subscription.
Zagnieżdżanie kropką: GET /v1/refunds/{id}?expand[]=payment.customer rozwija płatność, a w niej klienta.
Na liście z przedrostkiem data.: GET /v1/payments?expand[]=data.customer (samo customer też działa).
Przy POST pole expand możesz wysłać w treści JSON jako tablicę, żeby od razu dostać rozwiniętą odpowiedź.

Rozwinięty obiekt należy do tego samego konta i trybu; jeśli powiązany obiekt nie istnieje (np. został usunięty), pole zostaje identyfikatorem. Pole, którego ten zasób nie rozwija, kończy się 400 expand_invalid.

Jak używać

curl "https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh?expand[]=customer" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"

$ch = curl_init('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh?' . http_build_query(['expand' => ['customer']]));
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$payment = json_decode(curl_exec($ch), true);
$email = $payment['customer']['email'];

const res = await fetch('https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh?expand[]=customer', {
  headers: { Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const payment = await res.json();
const email = payment.customer.email;

import requests

res = requests.get(
    "https://oplac.pl/api/v1/payments/pay_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    params={"expand[]": ["customer"]},
)
payment = res.json()
email = payment["customer"]["email"]

Odpowiedź

HTTP/1.1 200 OK
{
  "id": "pay_Ab12Cd34Ef56Gh",
  "object": "payment",
  "amount": 12900,
  "currency": "PLN",
  "status": "succeeded",
  "customer": {
    "id": "cus_Xy98Zw76Vu54Ts",
    "object": "customer",
    "email": "[email protected]",
    "name": "Anna Nowak",
    "metadata": {"crm_id": "7"},
    "livemode": false,
    "created": 1760000000
  },
  "livemode": false,
  "created": 1760000000
}

Pola rozwijalne według zasobu#

Zasób	Pola `expand[]`
payment	`customer`, `payment_link`, `subscription`, `invoice`
refund	`payment`, `payment.customer`
subscription	`customer`, `plan`, `coupon`
invoice	`payment`, `refund`, `corrects`
payment_link, customer, plan, coupon, event, account	bez pól rozwijalnych

Ta sama lista jest przy każdej operacji w referencji jako dozwolone wartości parametru expand[]; referencja jest generowana ze specyfikacji, więc gdy dojdzie nowe pole, pojawi się tam automatycznie.

Expand a zdarzenia webhooka#

Obiekt w data.object zdarzenia jest migawką bez rozwinięć: pola powiązane to identyfikatory. Jeśli obsługa zdarzenia potrzebuje pełnego klienta albo planu, pobierz obiekt żądaniem GET z expand[]; przy okazji potwierdzisz aktualny stan, co jest zalecane przy każdym zdarzeniu.

Powiązane

Konwencje/docs/konwencje Stronicowanie/docs/stronicowanie Zdarzenia/docs/zdarzenia Zwroty w referencji API/docs/api/zwroty

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