Stripe

Stripe ist eine Online-Zahlungsplattform für Internetunternehmen. Die Integration von Stripe ermöglicht es Ihrer Anwendung, Transaktionen, Abonnements und Finanzdaten sicher zu verarbeiten.

Konfigurationsschritte

Nachdem Sie Stripe in der Integrationsliste ausgewählt haben, öffnet sich ein Konfigurationsdialog. Sie müssen folgende Anmeldedaten aus Ihrem Stripe-Dashboard angeben, um die Verbindung herzustellen:

1. Secret Key

Eingabe: Tragen Sie Ihren privaten Stripe-Secret Key (beginnt in der Regel mit sk_) in das Feld Secret Key ein. Dieser Schlüssel ermöglicht dem Backend die Authentifizierung sicherer Anfragen.

2. Publishable Key

Eingabe: Tragen Sie Ihren öffentlichen Stripe-Publishable Key (beginnt in der Regel mit pk_) in das Feld Publishable Key ein. Dieser Schlüssel wird für die Frontend-Implementierung verwendet.

3. Umgebung

Eingabe: Wählen Sie im Dropdown die passende Umgebung (z. B. Test für Entwicklung/Sandbox oder Production für Live-Zahlungen).

Verbindung abschließen

Sobald Schlüssel und Umgebung konfiguriert sind:

Prüfen Sie die Statusleiste (zeigt derzeit Nicht verbunden).
Klicken Sie unten rechts auf den schwarzen Button Hinzufügen, um die Anmeldedaten zu speichern und die Zahlungsintegration zu aktivieren.

Stripe-Integrationskonfiguration

Stripe-Integrations-API-Referenz

Konfigurationsverwaltung
Kundenverwaltung
Payment Intents
Abonnements
Produkte und Preise
Rechnungen
Rückerstattungen
Checkout-Sitzungen
Billing-Portal-Sitzungen
Zahlungsmethoden
Webhook-Ereignisse
Paginierung
Fehlerbehandlung

Konfigurationsverwaltung {#configuration-management}

configureStripe

Erstellt eine neue Stripe-Konfiguration für Projekt und Umgebung.

Mutation:

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

Eingabe:

input ConfigureStripeInput {
  secretKey: String!          # Stripe-Secret-Key (sk_test_... oder sk_live_...)
  publishableKey: String!    # Stripe-Publishable-Key (pk_test_... oder pk_live_...)
  environment: StripeEnvironment!  # TEST oder LIVE
  webhookSecret: String      # Webhook-Signaturgeheimnis (optional)
}

Antwort:

type ConfigureStripePayload {
  id: ID!                    # Konfigurations-ID
  publishableKey: String!    # Publishable Key
  webhookUrl: String!        # Generierte Webhook-URL
}

Beispiel:

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

Hinweise:

Der Secret Key wird vor der Speicherung mit AES-256-GCM verschlüsselt
Nur eine Konfiguration pro Projekt-/Umgebungskombination
Fehler, falls die Konfiguration bereits existiert

updateStripeConfig

Aktualisiert eine vorhandene Stripe-Konfiguration.

Mutation:

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

Eingabe:

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

Antwort:

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

Hinweise:

Alle Felder sind optional
Es werden nur übergebene Felder aktualisiert
Der Secret Key wird bei Angabe verschlüsselt

Kundenverwaltung {#customer-management}

stripe_customer

Ruft einen einzelnen Kunden anhand der ID ab.

Abfrage:

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

stripe_customers

Listet Kunden mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
customerId: Nach Kunden-ID filtern (optional)

stripe_createCustomer

Erstellt einen neuen Kunden.

Mutation:

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

Aktualisiert einen vorhandenen Kunden.

Mutation:

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
  }
}

Hinweise:

Alle Felder sind optional
Es werden nur übergebene Felder aktualisiert

stripe_deleteCustomer

Löscht einen Kunden.

Mutation:

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

Antwort:

Gibt bei Erfolg true zurück
Fehler, wenn der Kunde nicht gefunden wird

Payment Intents {#payment-intents}

stripe_paymentIntent

Ruft einen einzelnen Payment Intent anhand der ID ab.

Abfrage:

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

stripe_paymentIntents

Listet Payment Intents mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
customerId: Nach Kunden-ID filtern (optional)

stripe_createPaymentIntent

Erstellt einen neuen Payment Intent.

Mutation:

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
  }
}

Hinweise:

clientSecret wird für die Bestätigung im Frontend zurückgegeben
Verwenden Sie automaticPaymentMethods: true für die Stripe.js-Integration

stripe_updatePaymentIntent

Aktualisiert einen Payment Intent vor der Bestätigung.

Mutation:

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
  }
}

Hinweise:

Nur vor der Bestätigung änderbar
Alle Felder sind optional

stripe_confirmPaymentIntent

Bestätigt einen Payment Intent.

Mutation:

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
  }
}

Hinweise:

Erforderlich zum Abschluss der Zahlung
Kann 3D Secure erfordern
Gibt aktualisierten Status zurück (succeeded, requires_action usw.)

stripe_cancelPaymentIntent

Bricht einen Payment Intent ab.

Mutation:

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

Hinweise:

Nur möglich, solange der Intent nicht succeeded oder canceled ist
Status wechselt zu „canceled“

Abonnements {#subscriptions}

stripe_subscription

Ruft ein einzelnes Abonnement anhand der ID ab.

Abfrage:

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

stripe_subscriptions

Listet Abonnements mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
customerId: Nach Kunden-ID filtern (optional)
status: Nach Status filtern (optional)

stripe_createSubscription

Erstellt ein neues Abonnement.

Mutation:

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
      }
    }
  }
}

Hinweise:

paymentBehavior kann „default_incomplete“ sein, wenn eine Zahlungsmethode erforderlich ist
Testphase wird in Tagen angegeben
Letzte Rechnung und Payment Intent werden automatisch expandiert

stripe_updateSubscription

Aktualisiert ein vorhandenes Abonnement.

Mutation:

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

Kündigt ein Abonnement.

Mutation:

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

Parameter:

id: Abonnement-ID (erforderlich)
cancelAtPeriodEnd: Bei true Kündigung zum Periodenende; bei false sofortige Kündigung (Standard: false)

Hinweise:

Sofortige Kündigung: Abonnement endet sofort
Kündigung zum Periodenende: läuft bis zum Ende der aktuellen Periode

Produkte und Preise {#products-and-prices}

stripe_products

Listet Produkte mit Paginierung.

Abfrage:

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

Erstellt ein neues Produkt.

Mutation:

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

Listet Preise mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
productId: Nach Produkt-ID filtern (optional)

stripe_createPrice

Erstellt einen neuen Preis.

Mutation:

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
    }
  }
}

Hinweise:

recurring weglassen für Einmalpreise
interval muss einer von „day“, „week“, „month“, „year“ sein

Rechnungen {#invoices}

stripe_invoice

Ruft eine einzelne Rechnung anhand der ID ab.

Abfrage:

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
      }
    }
  }
}

Hinweise:

Die Abonnement-ID wird bei Verfügbarkeit per API-Expansion gesetzt

stripe_invoices

Listet Rechnungen mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
customerId: Nach Kunden-ID filtern (optional)
status: Nach Status filtern (optional)

stripe_payInvoice

Zahlt eine Rechnung programmatisch.

Mutation:

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
      }
    }
  }
}

Hinweise:

Versucht die Zahlung mit der Standard-Zahlungsmethode des Kunden
Fehler bei fehlgeschlagener Zahlung
Bei Erfolg wird der Rechnungsstatus auf „paid“ gesetzt

Rückerstattungen {#refunds}

stripe_refunds

Listet Rückerstattungen mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
paymentIntentId: Nach Payment-Intent-ID filtern (optional)

stripe_createRefund

Erstellt eine Rückerstattung für einen Payment Intent.

Mutation:

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

Hinweise:

amount weglassen für vollständige Rückerstattung
reason kann sein: „duplicate“, „fraudulent“, „requested_by_customer“
Status beginnt mit „pending“, dann „succeeded“ oder „failed“

Checkout-Sitzungen {#checkout-sessions}

stripe_createCheckoutSession

Erstellt eine Stripe-Checkout-Sitzung für Einmalzahlungen oder Abonnements. Gibt eine URL zurück, die Kunden zur gehosteten Zahlungsseite von Stripe weiterleitet.

Mutation:

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

Eingabe:

input StripeCreateCheckoutSessionInput {
  customerId: String              # Vorhandene Stripe-Kunden-ID (optional)
  customerEmail: String            # E-Mail für neue Kunden (optional)
  mode: String!                   # „payment“ für einmalig oder „subscription“ für wiederkehrend
  successUrl: String!             # Weiterleitung nach erfolgreicher Zahlung
  cancelUrl: String!              # Weiterleitung bei Abbruch
  lineItems: [StripeCheckoutSessionLineItemInput!]!  # Kaufelemente
  paymentMethodTypes: [String!]    # Erlaubte Zahlungsmethoden (optional)
  metadata: Map                    # Benutzerdefinierte Metadaten (optional)
}

input StripeCheckoutSessionLineItemInput {
  priceId: String      # Stripe-Preis-ID (bestehende Preise)
  quantity: Int!        # Menge
  amount: Float         # Benutzerdefinierter Betrag in Dollar (Einmalzahlungen)
  currency: String      # Währungscode (erforderlich, wenn amount gesetzt)
}

Antwort:

type StripeCheckoutSession {
  id: ID!                    # Sitzungs-ID
  object: String!            # „checkout.session“
  url: String!              # Weiterleitungs-URL für den Kunden
  customerId: String        # Kunden-ID (falls vorhanden)
  customerEmail: String     # Kunden-E-Mail
  paymentIntentId: String   # Payment-Intent-ID (Einmalzahlungen)
  subscriptionId: String    # Abonnement-ID (Abonnements)
  mode: String!             # „payment“ oder „subscription“
  status: String!            # Sitzungsstatus
  currency: String          # Währungscode
  amountTotal: Float        # Gesamtbetrag in Dollar
  metadata: Map             # Benutzerdefinierte Metadaten
  createdAt: Time!          # Erstellungszeitpunkt
}

Beispiel – Einmalzahlung:

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

Beispiel – Einmalzahlung mit benutzerdefiniertem Betrag:

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

Beispiel – Abonnement:

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

Hinweise:

Das Feld url enthält die Weiterleitungs-URL für Kunden
Für Einmalzahlungen: mode: "payment" und entweder priceId oder amount + currency
Für Abonnements: mode: "subscription" und priceId (muss ein wiederkehrender Preis sein)
Entweder customerId oder customerEmail, nicht beides
paymentMethodTypes kann z. B. „card“, „us_bank_account“, „link“ enthalten
Sitzungen verfallen nach 24 Stunden ohne Abschluss

Billing-Portal-Sitzungen {#billing-portal-sessions}

stripe_createBillingPortalSession

Erstellt eine Stripe-Billing-Portal-Sitzung, damit Kunden Abonnements, Zahlungsmethoden und Rechnungsdaten im gehosteten Portal verwalten können.

Mutation:

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

Eingabe:

input StripeCreateBillingPortalSessionInput {
  customerId: String!      # Stripe-Kunden-ID (erforderlich)
  returnUrl: String!       # Weiterleitung nach Verlassen des Portals
  configuration: String    # Portal-Konfigurations-ID (optional)
}

Antwort:

type StripeBillingPortalSession {
  id: ID!            # Sitzungs-ID
  object: String!    # „billing_portal.session“
  url: String!       # Weiterleitungs-URL für den Kunden
  customerId: String!  # Kunden-ID
  returnUrl: String   # Rückkehr-URL
  createdAt: Time!   # Erstellungszeitpunkt
}

Beispiel:

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

Hinweise:

Das Feld url enthält die Weiterleitungs-URL für Kunden
Die Portalsitzung ist kurzlebig und läuft nach Nutzung ab
Kunden können Abonnements, Zahlungsmethoden, Rechnungen und Rechnungsdaten verwalten
Portal-Funktionen werden im Stripe-Dashboard konfiguriert
Ohne configuration wird die Standard-Portal-Konfiguration verwendet
Das Portal zeigt nur Daten des angegebenen Kunden

Zahlungsmethoden {#payment-methods}

stripe_paymentMethods

Listet Zahlungsmethoden mit Paginierung und optionaler Filterung.

Abfrage:

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
    }
  }
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung
customerId: Nach Kunden-ID filtern (optional)

Hinweise:

Es werden nur sichere Kartendaten zurückgegeben (last4, Marke, Ablauf)
Vollständige Kartennummern werden nie angezeigt

stripe_attachPaymentMethod

Hängt eine Zahlungsmethode an einen Kunden an.

Mutation:

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

Hinweise:

Zahlungsmethode muss zuerst erstellt werden (typisch mit Stripe.js)
Angehängte Zahlungsmethoden können für Abonnements und Zahlungen genutzt werden

stripe_detachPaymentMethod

Löst eine Zahlungsmethode von einem Kunden.

Mutation:

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

Hinweise:

Getrennte Zahlungsmethoden können nicht mehr für Zahlungen verwendet werden
Gibt die Zahlungsmethode mit customerId null zurück

Webhook-Ereignisse {#webhook-events}

stripe_webhookEvents

Listet vom Dienst empfangene Webhook-Ereignisse.

Abfrage:

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

Antwort:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Ereignistyp (z. B. „payment_intent.succeeded“)
  data: String!              # JSON-String der Ereignisdaten
  processed: Boolean!        # Ob das Ereignis verarbeitet wurde
  createdAt: Time!
}

Parameter:

first: Anzahl der zurückzugebenden Einträge (Standard: 10)
after: Cursor für die Paginierung

Hinweise:

Ereignisse werden automatisch über den Webhook-Endpunkt empfangen
Ereignisse werden nach Signaturprüfung gespeichert
Das Feld data enthält die vollständige Nutzlast als JSON-String

Paginierung {#pagination}

Alle Listenabfragen unterstützen cursorbasierte Paginierung nach dem Relay-Connection-Muster.

PageInfo

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

Verwendungsbeispiel

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

Paginierungsablauf:

Erste Anfrage: first: 10, after: null
pageInfo.endCursor aus der Antwort als after in der nächsten Anfrage verwenden
hasNextPage prüfen, ob weitere Seiten existieren

Standardwerte:

first: Standard 10, falls nicht angegeben
after: Beginnt am Anfang, falls nicht angegeben

Fehlerbehandlung {#error-handling}

Alle Vorgänge liefern GraphQL-Fehler mit verständlichen Meldungen. Fehler werden aus Stripe-API-Fehlern abgebildet.

Häufige Fehlerszenarien

Konfigurationsfehler:

400: Ungültiges Format der Stripe-Schlüssel
404: Projekt oder Konfiguration nicht gefunden
400: Konfiguration existiert bereits

Kundenfehler:

404: Kunde nicht gefunden
400: Ungültige Kundendaten

Payment-Intent-Fehler:

404: Payment Intent nicht gefunden
400: Ungültiger Betrag oder Währung
402: Zahlung fehlgeschlagen (Karte abgelehnt, unzureichende Deckung usw.)

Abonnementfehler:

404: Abonnement nicht gefunden
400: Ungültige Abonnementparameter
400: Gekündigtes Abonnement kann nicht aktualisiert werden

Stripe-Fehlercodes: Häufige Stripe-Codes werden auf verständliche Meldungen abgebildet:

card_declined: „Ihre Karte wurde abgelehnt“
insufficient_funds: „Unzureichende Deckung“
invalid_number: „Ungültige Kartennummer“
expired_card: „Karte abgelaufen“
incorrect_cvc: „Falscher CVC-Code“

Fehlerantwortformat

{
  "errors": [
    {
      "message": "Customer not found",
      "extensions": {
        "code": "NOT_FOUND",
        "stripeErrorCode": "resource_missing"
      }
    }
  ],
  "data": null
}

Datentypen {#data-types}

StripeEnvironment

enum StripeEnvironment {
  TEST  # Testmodus
  LIVE  # Live-/Produktionsmodus
}

Map-Skalartyp

Der Skalartyp Map steht für ein Schlüssel-Wert-Map, wobei:

Schlüssel Zeichenketten sind
Werte Zeichenketten, Zahlen, Booleans oder verschachtelte Maps sein können
Er wird für Metadatenfelder verwendet

Beispiel:

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

Time-Skalartyp

Der Skalartyp Time steht für Zeitstempel im ISO-8601-Format.

Beispiel: "2025-11-16T00:28:48.081Z"