De Stripe-integratie toevoegen

Stripe is een online betalingsverwerkingsplatform dat is ontworpen voor internetbedrijven. Door Stripe te integreren, kan uw applicatie transacties, abonnementen en financiële gegevens veilig verwerken.

Configuratiestappen

Na het selecteren van Stripe uit de integratielijst, verschijnt er een configuratiemodal. U moet de volgende inloggegevens van uw Stripe-dashboard opgeven om de verbinding tot stand te brengen:

1. Geheime sleutel (Secret Key)

• Invoer: Voer uw privé Stripe Geheime sleutel (begint meestal met sk_) in het veld Secret Key in. Met deze sleutel kan de backend beveiligde verzoeken authentiseren.

2. Publiceerbare sleutel (Publishable Key)

• Invoer: Voer uw openbare Stripe Publiceerbare sleutel (begint meestal met pk_) in het veld Publishable Key in. Deze sleutel wordt gebruikt voor de frontend-implementatie.

3. Omgeving

• Invoer: Selecteer de juiste omgevingscontext in het vervolgkeuzemenu (bijv. Test voor ontwikkelings-/sandboxmodus of Production voor live verwerking).

De verbinding voltooien

Zodra de sleutels en omgeving zijn geconfigureerd:

1. Controleer de statusbalk (toont momenteel Not Connected).
2. Klik op de zwarte knop Add rechtsonder om de inloggegevens op te slaan en de betalingsintegratie in te schakelen.

Stripe-integratie API-referentie

---

Configuratiebeheer

configureStripe

Maakt een nieuwe Stripe-configuratie aan voor het project en de omgeving.

Mutation:

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

Input:

input ConfigureStripeInput {
  secretKey: String!          # Stripe secret key (sk_test_... or sk_live_...)
  publishableKey: String!    # Stripe publishable key (pk_test_... or pk_live_...)
  environment: StripeEnvironment!  # TEST or LIVE
  webhookSecret: String      # Webhook signing secret (optional)
}

Response:

type ConfigureStripePayload {
  id: ID!                    # Configuration ID
  publishableKey: String!    # Publishable key
  webhookUrl: String!        # Generated webhook URL
}

Example:

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

Opmerkingen:

• Geheime sleutel wordt versleuteld met AES-256-GCM voor opslag
• Slechts één configuratie per project/omgeving-combinatie
• Retourneert een fout als de configuratie al bestaat

---

updateStripeConfig

Werkt een bestaande Stripe-configuratie bij.

Mutation:

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

Input:

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

Response:

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

Opmerkingen:

• Alle velden zijn optioneel
• Alleen opgegeven velden worden bijgewerkt
• Geheime sleutel wordt versleuteld indien opgegeven

---

Klantenbeheer

stripe_customer

Haalt een enkele klant op via ID.

Query:

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

---

stripe_customers

Geeft een lijst met klanten weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• customerId: Filteren op klant-ID (optioneel)

---

stripe_createCustomer

Maakt een nieuwe klant aan.

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

Werkt een bestaande klant bij.

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

Opmerkingen:

• Alle velden zijn optioneel
• Alleen opgegeven velden worden bijgewerkt

---

stripe_deleteCustomer

Verwijdert een klant.

Mutation:

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

Response:

• Retourneert true bij succes
• Retourneert een fout als de klant niet is gevonden

---

Betalingsintenties (Payment Intents)

stripe_paymentIntent

Haalt een enkele betalingsintentie op via ID.

Query:

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

---

stripe_paymentIntents

Geeft een lijst met betalingsintenties weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• customerId: Filteren op klant-ID (optioneel)

---

stripe_createPaymentIntent

Maakt een nieuwe betalingsintentie aan.

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

Opmerkingen:

• clientSecret wordt geretourneerd voor frontend-bevestiging
• Gebruik automaticPaymentMethods: true voor integratie met Stripe.js

---

stripe_updatePaymentIntent

Werkt een betalingsintentie bij vóór bevestiging.

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

Opmerkingen:

• Kan alleen worden bijgewerkt vóór bevestiging
• Alle velden zijn optioneel

---

stripe_confirmPaymentIntent

Bevestigt een betalingsintentie.

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

Opmerkingen:

• Vereist om de betaling te voltooien
• Vereist mogelijk 3D Secure-authenticatie
• Retourneert bijgewerkte status (succeeded, requires_action, enz.)

---

stripe_cancelPaymentIntent

Annuleert een betalingsintentie.

Mutation:

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

Opmerkingen:

• Kan alleen betalingsintenties annuleren die niet succesvol zijn of nog niet geannuleerd zijn
• Status verandert naar “canceled”

---

Abonnementen

stripe_subscription

Haalt een enkel abonnement op via ID.

Query:

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

---

stripe_subscriptions

Geeft een lijst met abonnementen weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• customerId: Filteren op klant-ID (optioneel)
• status: Filteren op status (optioneel)

---

stripe_createSubscription

Maakt een nieuw abonnement aan.

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

Opmerkingen:

• paymentBehavior kan “default_incomplete” zijn voor abonnementen die een betaalmethode vereisen
• Proefperiode wordt in dagen opgegeven
• Laatste factuur en betalingsintentie worden automatisch uitgebreid

---

stripe_updateSubscription

Werkt een bestaand abonnement bij.

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

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

Parameters:

• id: Abonnements-ID (verplicht)
• cancelAtPeriodEnd: Indien true, annuleer aan het einde van de periode; indien false, annuleer onmiddellijk (standaard: false)

Opmerkingen:

• Onmiddellijke annulering: Abonnement eindigt nu
• Annulering aan einde periode: Abonnement loopt door tot het einde van de huidige periode

---

Producten en Prijzen

stripe_products

Geeft een lijst met producten weer met paginering.

Query:

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

Maakt een nieuw product aan.

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

Geeft een lijst met prijzen weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• productId: Filteren op product-ID (optioneel)

---

stripe_createPrice

Maakt een nieuwe prijs aan.

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

Opmerkingen:

• Laat recurring weg voor eenmalige prijzen
• interval moet een van de volgende zijn: “day”, “week”, “month”, “year”

---

Facturen (Invoices)

stripe_invoice

Haalt een enkele factuur op via ID.

Query:

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

Opmerkingen:

• Abonnements-ID wordt ingevuld via API-uitbreiding indien beschikbaar

---

stripe_invoices

Geeft een lijst met facturen weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• customerId: Filteren op klant-ID (optioneel)
• status: Filteren op status (optioneel)

---

stripe_payInvoice

Betaalt een factuur 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
      }
    }
  }
}

Opmerkingen:

• Probeert de factuur te betalen met de standaardbetaalmethode van de klant
• Retourneert een fout als de betaling mislukt
• Werkt de factuurstatus bij naar “paid” bij succes

---

Terugbetalingen (Refunds)

stripe_refunds

Geeft een lijst met terugbetalingen weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• paymentIntentId: Filteren op betalingsintentie-ID (optioneel)

---

stripe_createRefund

Maakt een terugbetaling aan voor een betalingsintentie.

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

Opmerkingen:

• Laat amount weg voor een volledige terugbetaling
• reason kan zijn: “duplicate”, “fraudulent”, “requested_by_customer”
• Terugbetalingsstatus begint als “pending” en wordt bijgewerkt naar “succeeded” of “failed”

---

Betaalmethoden (Payment Methods)

stripe_paymentMethods

Geeft een lijst met betaalmethoden weer met paginering en optionele filtering.

Query:

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

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering
• customerId: Filteren op klant-ID (optioneel)

Opmerkingen:

• Alleen veilige kaartinformatie (laatste 4 cijfers, merk, vervaldatum) wordt geretourneerd
• Volledige kaartnummers worden nooit onthuld

---

stripe_attachPaymentMethod

Koppelt een betaalmethode aan een klant.

Mutation:

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

Opmerkingen:

• Betaalmethode moet eerst worden aangemaakt (meestal via Stripe.js)
• Gekoppelde betaalmethoden kunnen worden gebruikt voor abonnementen en betalingen

---

stripe_detachPaymentMethod

Ontkoppelt een betaalmethode van een klant.

Mutation:

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

Opmerkingen:

• Ontkoppelde betaalmethoden kunnen niet meer worden gebruikt voor betalingen
• Retourneert de betaalmethode met customerId ingesteld op null

---

Webhook-gebeurtenissen

stripe_webhookEvents

Geeft een lijst met webhook-gebeurtenissen weer die door de service zijn ontvangen.

Query:

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

Response:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Event type (e.g., "payment_intent.succeeded")
  data: String!              # JSON string of event data
  processed: Boolean!        # Whether event has been processed
  createdAt: Time!
}

Parameters:

• first: Aantal terug te geven items (standaard: 10)
• after: Cursor voor paginering

Opmerkingen:

• Gebeurtenissen worden automatisch ontvangen via het webhook-eindpunt
• Gebeurtenissen worden opgeslagen na verificatie van de handtekening
• Het veld data bevat de volledige payload van de gebeurtenis als een JSON-tekenreeks

---

Paginering

Alle lijstquery’s ondersteunen cursor-gebaseerde paginering met behulp van het Relay-verbindingspatroon.

PageInfo

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

Gebruiksvoorbeeld

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

Pagineringsstroom:

1. Initiële aanvraag: first: 10, after: null
2. Gebruik pageInfo.endCursor uit het antwoord als after in de volgende aanvraag
3. Controleer hasNextPage om te bepalen of er meer pagina’s zijn

Standaardwaarden:

• first: Standaard 10 indien niet opgegeven
• after: Begint vanaf het begin indien niet opgegeven

---

Foutafhandeling

Alle operaties retourneren GraphQL-fouten met gebruiksvriendelijke berichten. Fouten worden toegewezen vanuit Stripe API-fouten om duidelijke feedback te geven.

Veelvoorkomende foutscenario’s

Configuratiefouten:

• 400: Ongeldige Stripe-sleutelindeling
• 404: Project of configuratie niet gevonden
• 400: Configuratie bestaat al

Klantfouten:

• 404: Klant niet gevonden
• 400: Ongeldige klantgegevens

Betalingsintentiefouten:

• 404: Betalingsintentie niet gevonden
• 400: Ongeldig bedrag of valuta
• 402: Betaling mislukt (kaart geweigerd, onvoldoende saldo, enz.)

Abonnementsfouten:

• 404: Abonnement niet gevonden
• 400: Ongeldige abonnementparameters
• 400: Kan een geannuleerd abonnement niet bijwerken

Stripe-foutcodes: Veelvoorkomende Stripe-foutcodes worden toegewezen aan gebruiksvriendelijke berichten:

• card_declined: “Uw kaart is geweigerd”
• insufficient_funds: “Onvoldoende saldo”
• invalid_number: “Ongeldig kaartnummer”
• expired_card: “Kaart is verlopen”
• incorrect_cvc: “Onjuiste CVC-code”

Foutantwoordindeling

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

---

Gegevenstypen

StripeEnvironment

enum StripeEnvironment {
  TEST  # Test mode
  LIVE  # Live/production mode
}

Scalar Map

Het scalaire type Map vertegenwoordigt een sleutel-waarde-toewijzing waarbij:

• Sleutels tekenreeksen zijn
• Waarden tekenreeksen, getallen, booleans of geneste kaarten kunnen zijn
• Gebruikt voor metagegevensvelden

Voorbeeld:

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

Scalar Time

Het scalaire type Time vertegenwoordigt tijdstempels in ISO 8601-formaat.

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