Stripe

Stripe to platforma internetowa do obsługi płatności online, przeznaczona dla firm działających w sieci. Integracja ze Stripe pozwala aplikacji obsługiwać transakcje, subskrypcje i dane finansowe w sposób bezpieczny.

Kroki konfiguracji

Po wybraniu Stripe z listy integracji pojawi się okno konfiguracji. Musisz podać następujące dane uwierzytelniające z panelu Stripe, aby nawiązać połączenie:

1. Klucz tajny

Wprowadzenie: Wpisz prywatny klucz tajny Stripe (zwykle zaczyna się od sk_) w polu Secret Key. Klucz ten pozwala backendowi uwierzytelniać bezpieczne żądania.

2. Klucz publiczny

Wprowadzenie: Wpisz publiczny klucz publikowalny Stripe (zwykle zaczyna się od pk_) w polu Publishable Key. Klucz ten służy po stronie frontendu.

3. Środowisko

Wprowadzenie: Wybierz odpowiedni kontekst środowiska z listy (np. Test dla trybu deweloperskiego lub sandbox, albo Production dla przetwarzania na żywo).

Finalizacja połączenia

Gdy klucze i środowisko są skonfigurowane:

Sprawdź pasek statusu (pokazuje Not Connected).
Kliknij czarny przycisk Add w prawym dolnym rogu, aby zapisać dane i aktywować integrację płatności.

Konfiguracja integracji Stripe

Dokumentacja API integracji Stripe

Zarządzanie konfiguracją
Zarządzanie klientami
Intencje płatności
Subskrypcje
Produkty i ceny
Faktury
Zwroty
Sesje Checkout
Sesje portalu rozliczeniowego
Metody płatności
Zdarzenia webhook
Paginacja
Obsługa błędów

Zarządzanie konfiguracją {#configuration-management}

configureStripe {#configurestripe}

Tworzy nową konfigurację Stripe dla projektu i środowiska.

Mutacja:

mutation ConfigureStripe (
  $input: ConfigureStripeInput!
) {
  configureStripe (
    input: $input
  ) {
    id
    publishableKey
    webhookUrl
  }
}

Dane wejściowe:

input ConfigureStripeInput {
  secretKey: String!          # Klucz tajny Stripe (sk_test_... lub sk_live_...)
  publishableKey: String!    # Klucz publikowalny Stripe (pk_test_... lub pk_live_...)
  environment: StripeEnvironment!  # TEST o LIVE
  webhookSecret: String      # Sekret podpisu webhook (opcjonalnie)
}

Odpowiedź:

type ConfigureStripePayload {
  id: ID!                    # Identyfikator konfiguracji
  publishableKey: String!    # Klucz publikowalny
  webhookUrl: String!        # Wygenerowany adres URL webhook
}

Przykład:

{
  "input": {
    "secretKey": "sk_test_...",
    "publishableKey": "pk_test_...",
    "environment": "TEST",
    "webhookSecret": "whsec_..."
  }
}

Uwagi:

Klucz tajny jest szyfrowany algorytmem AES-256-GCM przed zapisem
Tylko jedna konfiguracja na parę projekt/środowisko
Zwraca błąd, jeśli konfiguracja już istnieje

updateStripeConfig {#updatestripeconfig}

Aktualizuje istniejącą konfigurację Stripe.

Mutacja:

mutation UpdateStripeConfig (
  $input: UpdateStripeConfigInput!
) {
  updateStripeConfig (
    input: $input
  ) {
    id
    publishableKey
    webhookUrl
  }
}

Dane wejściowe:

input UpdateStripeConfigInput {
  secretKey: String          # Opcjonalnie
  publishableKey: String     # Opcjonalnie
  environment: StripeEnvironment  # Opcjonalnie
  webhookSecret: String      # Opcjonalnie
}

Odpowiedź:

type UpdateStripeConfigPayload {
  id: ID!
  publishableKey: String!
  webhookUrl: String!
}

Uwagi:

Wszystkie pola są opcjonalne
Aktualizowane są tylko podane pola
Klucz tajny jest szyfrowany, jeśli zostanie podany

Zarządzanie klientami {#customer-management}

stripe_customer {#stripe_customer}

Pobiera pojedynczego klienta po identyfikatorze.

Zapytanie:

query stripe_customer{
  stripe_customer(
    id: "cus_Ts..."
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

stripe_customers {#stripe_customers}

Wyświetla listę klientów z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_customers (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_customers (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        name
        email
        phone
        description
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
customerId: Filtruj po identyfikatorze klienta (opcjonalnie)

stripe_createCustomer {#stripe_createcustomer}

Tworzy nowego klienta.

Mutacja:

mutation stripe_createCustomer {
  stripe_createCustomer (
    input: {
      name: "Customer",
      email: "example@archie.com",
      phone: "+573001230001",
      description: "Description Example"
      metadata: {
        data1: "Example data1",
        data2: "Example data2"
      }
    }
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

stripe_updateCustomer {#stripe_updatecustomer}

Aktualizuje istniejącego klienta.

Mutacja:

mutation stripe_updateCustomer {
  stripe_updateCustomer(
    id: "cus_Ts...",
    input: {
      name: "Customer",
      email: "example@archie.com",
      phone: "+573001230001",
      description:"Description Example",
      metadata: {
        data1: "Example data1 updated",
        data2: "Example data2 updated"
      }
    }
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

Uwagi:

Wszystkie pola są opcjonalne
Aktualizowane są tylko podane pola

stripe_deleteCustomer {#stripe_deletecustomer}

Usuwa klienta.

Mutacja:

mutation stripe_deleteCustomer {
  stripe_deleteCustomer (
    id: "cus_Ts...")
}

Odpowiedź:

Zwraca true w przypadku powodzenia
Zwraca błąd, jeśli klient nie został znaleziony

Intencje płatności {#payment-intents}

stripe_paymentIntent {#stripe_paymentintent}

Pobiera pojedynczą intencję płatności po identyfikatorze.

Zapytanie:

query stripe_paymentIntent {
  stripe_paymentIntent (
    id: "pi_3Su..."
  )
  {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

stripe_paymentIntents {#stripe_paymentintents}

Wyświetla listę intencji płatności z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_paymentIntents (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_paymentIntents (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        paymentMethodId
        currency
        amount
        status
        metadata
        object
        clientSecret
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
customerId: Filtruj po identyfikatorze klienta (opcjonalnie)

stripe_createPaymentIntent {#stripe_createpaymentintent}

Tworzy nową intencję płatności.

Mutacja:

mutation stripe_createPaymentIntent {
  stripe_createPaymentIntent (
    input: {
      amount: 12.35,
      currency: "usd",
      customerId: "cus_Ts...",
      paymentMethodId: "pm_1Su...",
      automaticPaymentMethods: true
    }
  )
  {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

Uwagi:

Zwracany jest clientSecret do potwierdzenia po stronie frontendu
Użyj automaticPaymentMethods: true dla integracji ze Stripe.js

stripe_updatePaymentIntent {#stripe_updatepaymentintent}

Aktualizuje intencję płatności przed potwierdzeniem.

Mutacja:

mutation stripe_updatePaymentIntent{
  stripe_updatePaymentIntent(
    id: "pi_3S...",
    input: {
      amount: 36.92,
      currency: "usd",
      paymentMethodId: "pm_1Su..."
      metadata:{
        data1: "Example data1"
      }
    }
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

Uwagi:

Można aktualizować tylko przed potwierdzeniem
Wszystkie pola są opcjonalne

stripe_confirmPaymentIntent {#stripe_confirmpaymentintent}

Potwierdza intencję płatności.

Mutacja:

mutation stripe_confirmPaymentIntent{
  stripe_confirmPaymentIntent(
    id: "pi_3Su..."
    input: {
      paymentMethodId: "pm_1Su...",
      returnUrl: "http://localhost:3000/successful-payment"
    }
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

Uwagi:

Wymagane do dokończenia płatności
Może wymagać uwierzytelnienia 3D Secure
Zwraca zaktualizowany status (succeeded, requires_action itd.)

stripe_cancelPaymentIntent {#stripe_cancelpaymentintent}

Anuluje intencję płatności.

Mutacja:

mutation stripe_cancelPaymentIntent {
  stripe_cancelPaymentIntent(
    id: "pi_3Su..."
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

Uwagi:

Można anulować tylko intencje, które nie mają statusu succeeded ani canceled
Status zmienia się na “canceled”

Subskrypcje {#subscriptions}

stripe_subscription {#stripe_subscription}

Pobiera pojedynczą subskrypcję po identyfikatorze.

Zapytanie:

query stripe_subscription {
  stripe_subscription(id: "sub_1Su...") {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

stripe_subscriptions {#stripe_subscriptions}

Wyświetla listę subskrypcji z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_subscriptions (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_subscriptions (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        status
        currentPeriodStart
        currentPeriodEnd
        createdAt
        cancelAtPeriodEnd
        metadata
        object
        items {
          data {
            id
            priceId
            quantity
          }
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
customerId: Filtruj po identyfikatorze klienta (opcjonalnie)
status: Filtruj po statusie (opcjonalnie)

stripe_createSubscription {#stripe_createsubscription}

Tworzy nową subskrypcję.

Mutacja:

mutation stripe_createSubscription {
  stripe_createSubscription (
    input: {
      customerId: "cus_TsQ...",
      items: {
        priceId: "price_1Su...",
        quantity: 1
      },
      metadata: {
        data1: "Example data1"
      },
      trialPeriodDays: 0
    }
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

Uwagi:

paymentBehavior może być “default_incomplete” dla subskrypcji wymagających metody płatności
Okres próbny podawany jest w dniach
Ostatnia faktura i intencja płatności są automatycznie rozwijane

stripe_updateSubscription {#stripe_updatesubscription}

Aktualizuje istniejącą subskrypcję.

Mutacja:

mutation stripe_updateSubscription {
  stripe_updateSubscription(
    id: "sub_1Sv..."
    input: {
      cancelAtPeriodEnd: false
      metadata: {
        data2: "Example data2"
      }
    }
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

stripe_cancelSubscription {#stripe_cancelsubscription}

Anuluje subskrypcję.

Mutacja:

mutation stripe_cancelSubscription {
  stripe_cancelSubscription (
    cancelAtPeriodEnd: true,
    id: "sub_1Sv..."
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

Parametry:

id: Identyfikator subskrypcji (wymagany)
cancelAtPeriodEnd: Jeśli true, anulacja na koniec okresu; jeśli false, natychmiastowa anulacja (domyślnie: false)

Uwagi:

Anulacja natychmiastowa: subskrypcja kończy się teraz
Anulacja na koniec okresu: subskrypcja trwa do końca bieżącego okresu

Produkty i ceny {#products-and-prices}

stripe_products {#stripe_products}

Wyświetla listę produktów z paginacją.

Zapytanie:

query stripe_products (
  $first: Int,
  $after: String
) {
  stripe_products (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        name
        description
        active
        metadata
        object
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

stripe_createProduct {#stripe_createproduct}

Tworzy nowy produkt.

Mutacja:

mutation stripe_createProduct {
  stripe_createProduct (
    input: {
      name: "Product 01",
      description: "Description product 01",
      metadata: {
        data1: "Example data1"
      }
    }
  ) {
    id
    name
    description
    active
    metadata
    object
    createdAt
  }
}

stripe_prices {#stripe_prices}

Wyświetla listę cen z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_prices (
  $first: Int,
  $after: String,
  $productId: String
) {
  stripe_prices (
    first: $first,
    after: $after,
    productId: $productId
  ) {
    edges {
      node {
        id
        productId
        active
        currency
        unitAmount
        object
        metadata
        createdAt
        recurring {
          interval
          intervalCount
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
productId: Filtruj po identyfikatorze produktu (opcjonalnie)

stripe_createPrice {#stripe_createprice}

Tworzy nową cenę.

Mutacja:

mutation stripe_createPrice {
  stripe_createPrice (
    input: {
      productId: "prod_Tst...",
      unitAmount: 25.85,
      currency: "usd",
      recurring: {
        interval: "month",
        intervalCount: 1
      },
      metadata: {
        data1: "Example data1"
      }
    }
  ) {
    id
    productId
    currency
    unitAmount
    active
    object
    createdAt
    metadata
    recurring {
      interval
      intervalCount
    }
  }
}

Uwagi:

Pomiń recurring dla cen jednorazowych
interval musi być jednym z: “day”, “week”, “month”, “year”

Faktury {#invoices}

stripe_invoice {#stripe_invoice}

Pobiera pojedynczą fakturę po identyfikatorze.

Zapytanie:

query stripe_invoice {
  stripe_invoice (
    id: "in_1Su..."
  ) {
    id
    customerId
    subscriptionId
    currency
    amountPaid
    amountDue
    status
    object
    metadata
    createdAt
    lineItems {
      data {
        id
        description
        currency
        amount
        quantity
      }
    }
  }
}

Uwagi:

Identyfikator subskrypcji jest uzupełniany przez rozszerzenie API, gdy jest dostępne

stripe_invoices {#stripe_invoices}

Wyświetla listę faktur z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_invoices (
  $first: Int,
  $after: String,
  $customerId: String,
  $status: String
) {
  stripe_invoices (
    first: $first,
    after: $after,
    customerId: $customerId,
    status: $status
  ) {
    edges {
      node {
        id
        customerId
        subscriptionId
        currency
        amountPaid
        amountDue
        status
        object
        metadata
        createdAt
        lineItems {
          data {
            id
            description
            currency
            amount
            quantity
          }
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
customerId: Filtruj po identyfikatorze klienta (opcjonalnie)
status: Filtruj po statusie (opcjonalnie)

stripe_payInvoice {#stripe_payinvoice}

Opłaca fakturę programowo.

Mutacja:

mutation stripe_payInvoice {
  stripe_payInvoice (
    id: "in_1Sv..."
  ) {
    id
    customerId
    subscriptionId
    currency
    amountPaid
    amountDue
    status
    object
    metadata
    createdAt
    lineItems {
      data {
        id
        description
        currency
        amount
        quantity
      }
    }
  }
}

Uwagi:

Próbuje opłacić fakturę domyślną metodą płatności klienta
Zwraca błąd, jeśli płatność się nie powiedzie
Po sukcesie aktualizuje status faktury na “paid”

Zwroty {#refunds}

stripe_refunds {#stripe_refunds}

Wyświetla listę zwrotów z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query  stripe_refunds (
  $first: Int,
  $after: String,
  $paymentIntentId: String
)  {
  stripe_refunds (
    first: $first,
    after: $after,
    paymentIntentId: $paymentIntentId
  ) {
    edges {
      node {
        id
        paymentIntentId
        reason
        status
        currency
        amount
        metadata
        object
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
paymentIntentId: Filtruj po identyfikatorze intencji płatności (opcjonalnie)

stripe_createRefund {#stripe_createrefund}

Tworzy zwrot dla intencji płatności.

Mutacja:

mutation stripe_createRefund {
  stripe_createRefund (
    input: {
      paymentIntentId: "pi_3Sv...",
      amount: 200,
      reason: "requested_by_customer"
    }
  ) {
    id
    reason
    paymentIntentId
    status
    currency
    amount
    object
    metadata
    createdAt
  }
}

Uwagi:

Pomiń amount dla zwrotu pełnej kwoty
reason może być: “duplicate”, “fraudulent”, “requested_by_customer”
Status zwrotu zaczyna się jako “pending”, potem przechodzi na “succeeded” lub “failed”

Sesje Checkout {#checkout-sessions}

stripe_createCheckoutSession {#stripe_createcheckoutsession}

Tworzy sesję Stripe Checkout dla płatności jednorazowych lub subskrypcji. Zwraca adres URL przekierowujący klientów na hostowaną stronę płatności Stripe.

Mutacja:

mutation CreateCheckoutSession($input: StripeCreateCheckoutSessionInput!) {
  stripe_createCheckoutSession(input: $input) {
    id
    url
    customerId
    customerEmail
    paymentIntentId
    subscriptionId
    mode
    status
    currency
    amountTotal
    metadata
    createdAt
  }
}

Dane wejściowe:

input StripeCreateCheckoutSessionInput {
  customerId: String              # Istniejący identyfikator klienta Stripe (opcjonalnie)
  customerEmail: String            # E-mail nowych klientów (opcjonalnie)
  mode: String!                   # "payment" dla jednorazowej lub "subscription" dla cyklicznej
  successUrl: String!             # URL przekierowania po udanej płatności
  cancelUrl: String!              # URL przekierowania, gdy klient anuluje
  lineItems: [StripeCheckoutSessionLineItemInput!]!  # Pozycje do zakupu
  paymentMethodTypes: [String!]    # Dozwolone metody płatności (opcjonalnie)
  metadata: Map                    # Niestandardowe metadane (opcjonalnie)
}

input StripeCheckoutSessionLineItemInput {
  priceId: String      # Identyfikator ceny Stripe (istniejące ceny)
  quantity: Int!        # Liczba sztuk
  amount: Float         # Niestandardowa kwota w dolarach (płatności jednorazowe)
  currency: String      # Kod waluty (wymagany, jeśli podano amount)
}

Odpowiedź:

type StripeCheckoutSession {
  id: ID!                    # Identyfikator sesji
  object: String!            # "checkout.session"
  url: String!              # Adres URL przekierowania dla klienta
  customerId: String        # Identyfikator klienta (jeśli istnieje)
  customerEmail: String     # E-mail klienta
  paymentIntentId: String   # Identyfikator intencji płatności (płatności jednorazowe)
  subscriptionId: String    # Identyfikator subskrypcji (subskrypcje)
  mode: String!             # "payment" lub "subscription"
  status: String!            # Status sesji
  currency: String          # Kod waluty
  amountTotal: Float        # Suma w dolarach
  metadata: Map             # Niestandardowe metadane
  createdAt: Time!          # Znacznik czasu utworzenia
}

Przykład — płatność jednorazowa:

{
  "input": {
    "mode": "payment",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "lineItems": [
      {
        "priceId": "price_1234567890",
        "quantity": 1
      }
    ]
  }
}

Przykład — jednorazowa płatność z niestandardową kwotą:

{
  "input": {
    "mode": "payment",
    "customerEmail": "customer@example.com",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "lineItems": [
      {
        "amount": 29.99,
        "currency": "usd",
        "quantity": 1
      }
    ]
  }
}

Przykład — subskrypcja:

{
  "input": {
    "mode": "subscription",
    "customerId": "cus_1234567890",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "lineItems": [
      {
        "priceId": "price_monthly_subscription",
        "quantity": 1
      }
    ]
  }
}

Uwagi:

Pole url zawiera adres przekierowania, na który należy wysłać klientów
Dla płatności jednorazowych użyj mode: "payment" i podaj priceId albo amount + currency
Dla subskrypcji użyj mode: "subscription" i podaj priceId (musi to być cena cykliczna)
Należy podać customerId lub customerEmail, ale nie oba naraz
paymentMethodTypes może zawierać: “card”, “us_bank_account”, “link” itd.
Sesje wygasają po 24 godzinach, jeśli nie zostaną dokończone

Sesje portalu rozliczeniowego {#billing-portal-sessions}

stripe_createBillingPortalSession {#stripe_createbillingportalsession}

Tworzy sesję portalu rozliczeniowego Stripe, aby klienci zarządzali subskrypcjami, metodami płatności i danymi rozliczeniowymi w hostowanym portalu Stripe.

Mutacja:

mutation CreateBillingPortalSession($input: StripeCreateBillingPortalSessionInput!) {
  stripe_createBillingPortalSession(input: $input) {
    id
    url
    customerId
    returnUrl
    createdAt
  }
}

Dane wejściowe:

input StripeCreateBillingPortalSessionInput {
  customerId: String!      # Identyfikator klienta Stripe (wymagany)
  returnUrl: String!       # URL przekierowania po opuszczeniu portalu
  configuration: String    # Identyfikator konfiguracji portalu (opcjonalnie)
}

Odpowiedź:

type StripeBillingPortalSession {
  id: ID!            # Identyfikator sesji
  object: String!    # "billing_portal.session"
  url: String!       # Adres URL przekierowania dla klienta
  customerId: String!  # Identyfikator klienta
  returnUrl: String   # URL powrotu
  createdAt: Time!   # Znacznik czasu utworzenia
}

Przykład:

{
  "input": {
    "customerId": "cus_1234567890",
    "returnUrl": "https://example.com/account"
  }
}

Uwagi:

Pole url zawiera adres przekierowania, na który należy wysłać klientów
Sesja portalu jest krótkotrwała i wygasa po użyciu
Klienci mogą zarządzać subskrypcjami, aktualizować metody płatności, przeglądać faktury i dane rozliczeniowe
Funkcje portalu konfiguruje się w panelu Stripe
Jeśli nie podano configuration, używana jest domyślna konfiguracja portalu
Portal pokazuje wyłącznie subskrypcje i faktury wskazanego klienta

Metody płatności {#payment-methods}

stripe_paymentMethods {#stripe_paymentmethods}

Wyświetla listę metod płatności z paginacją i opcjonalnym filtrowaniem.

Zapytanie:

query stripe_paymentMethods (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_paymentMethods(
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        type
        object
        metadata
        createdAt
        card {
          brand
          expMonth
          expYear
          last4
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji
customerId: Filtruj po identyfikatorze klienta (opcjonalnie)

Uwagi:

Zwracane są wyłącznie bezpieczne dane karty (last4, marka, data ważności)
Pełne numery kart nigdy nie są ujawniane

stripe_attachPaymentMethod {#stripe_attachpaymentmethod}

Przypisuje metodę płatności do klienta.

Mutacja:

mutation stripe_attachPaymentMethod {
  stripe_attachPaymentMethod (
    id: "pm_1Sv...",
    input: {
      customerId: "cus_Ts4..."
    }
  ) {
    id
    customerId
    type
    card {
      brand
      expMonth
      expYear
      last4
    }
    metadata
    object
    createdAt
  }
}

Uwagi:

Metoda płatności musi być wcześniej utworzona (zwykle przez Stripe.js)
Przypisane metody można używać w subskrypcjach i płatnościach

stripe_detachPaymentMethod {#stripe_detachpaymentmethod}

Odłącza metodę płatności od klienta.

Mutacja:

mutation stripe_detachPaymentMethod {
  stripe_detachPaymentMethod (
    id: "pm_1Sv..."
  ) {
    id
    customerId
    type
    card {
      brand
      expYear
      expMonth
      last4
    }
    metadata
    object
    createdAt
  }
}

Uwagi:

Po odłączeniu metody nie można ich używać do płatności
Zwraca metodę płatności z customerId równym null

Zdarzenia webhook {#webhook-events}

stripe_webhookEvents {#stripe_webhookevents}

Wyświetla zdarzenia webhook odebrane przez usługę.

Zapytanie:

query ListWebhookEvents (
  $first: Int,
  $after: String
) {
  stripe_webhookEvents (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        type
        data
        processed
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      endCursor
    }
  }
}

Odpowiedź:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Typ zdarzenia (np. "payment_intent.succeeded")
  data: String!              # Łańcuch JSON z danymi zdarzenia
  processed: Boolean!        # Czy zdarzenie zostało przetworzone
  createdAt: Time!
}

Parametry:

first: Liczba zwracanych elementów (domyślnie: 10)
after: Kursor paginacji

Uwagi:

Zdarzenia są automatycznie odbierane na endpointzie webhook
Zdarzenia są zapisywane po weryfikacji podpisu
Pole data zawiera pełny ładunek zdarzenia jako łańcuch JSON

Paginacja {#pagination}

Wszystkie zapytania listujące obsługują paginację opartą na kursorach wzorcu Relay Connection.

PageInfo {#pageinfo}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Przykład użycia {#usage-example}

query ListCustomers (
  $first: Int,
  $after: String
) {
  stripe_customers (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        email
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Przebieg paginacji:

Pierwsze żądanie: first: 10, after: null
Użyj pageInfo.endCursor z odpowiedzi jako after w kolejnym żądaniu
Sprawdź hasNextPage, czy są kolejne strony

Wartości domyślne:

first: Domyślnie 10, jeśli nie podano
after: Zaczyna od początku, jeśli nie podano

Obsługa błędów {#error-handling}

Wszystkie operacje zwracają błędy GraphQL z czytelnymi komunikatami. Błędy są mapowane z API Stripe, aby użytkownik otrzymał jasną informację zwrotną.

Typowe scenariusze błędów {#common-error-scenarios}

Błędy konfiguracji:

400: Nieprawidłowy format kluczy Stripe
404: Nie znaleziono projektu lub konfiguracji
400: Konfiguracja już istnieje

Błędy klienta:

404: Klient nie został znaleziony
400: Nieprawidłowe dane klienta

Błędy intencji płatności:

404: Nie znaleziono intencji płatności
400: Nieprawidłowa kwota lub waluta
402: Płatność nieudana (karta odrzucona, niewystarczające środki itd.)

Błędy subskrypcji:

404: Nie znaleziono subskrypcji
400: Nieprawidłowe parametry subskrypcji
400: Nie można zaktualizować anulowanej subskrypcji

Kody błędów Stripe: Typowe kody Stripe są mapowane na czytelne komunikaty:

card_declined: “Twoja karta została odrzucona”
insufficient_funds: “Niewystarczające środki”
invalid_number: “Nieprawidłowy numer karty”
expired_card: “Karta wygasła”
incorrect_cvc: “Nieprawidłowy kod CVC”

Format odpowiedzi z błędem {#error-response-format}

{
  "errors": [
    {
      "message": "Klient nie został znaleziony",
      "extensions": {
        "code": "NOT_FOUND",
        "stripeErrorCode": "resource_missing"
      }
    }
  ],
  "data": null
}

Typy danych {#data-types}

StripeEnvironment {#stripe-environment}

enum StripeEnvironment {
  TEST  # Tryb testowy
  LIVE  # Tryb na żywo / produkcja
}

Skalar Map {#map-scalar}

Typ skalarny Map reprezentuje mapę klucz-wartość, gdzie:

Klucze są łańcuchami
Wartości mogą być łańcuchami, liczbami, wartościami logicznymi lub zagnieżdżonymi mapami
Używany jest w polach metadanych

Przykład:

{
  "metadata": {
    "order_id": "12345",
    "user_id": "67890",
    "premium": true
  }
}

Skalar Time {#time-scalar}

Typ skalarny Time reprezentuje znaczniki czasu w formacie ISO 8601.

Przykład: "2025-11-16T00:28:48.081Z"