Ajouter l'intégration Stripe

Stripe est une plateforme de traitement des paiements en ligne conçue pour les entreprises sur internet. L’intégration de Stripe permet à votre application de gérer les transactions, les abonnements et les données financières en toute sécurité.

Étapes de configuration

Après avoir sélectionné Stripe dans la liste des intégrations, une fenêtre modale de configuration apparaîtra. Vous devez fournir les informations suivantes depuis votre tableau de bord Stripe pour établir la connexion :

1. Clé secrète (Secret Key)

Entrée : Entrez votre Clé Secrète Stripe privée (commençant généralement par sk_) dans le champ Secret Key. Cette clé permet au backend d’authentifier les requêtes sécurisées.

2. Clé publiable (Publishable Key)

Entrée : Entrez votre Clé Publiable Stripe publique (commençant généralement par pk_) dans le champ Publishable Key. Cette clé est utilisée pour l’implémentation frontend.

3. Environnement

Entrée : Sélectionnez le contexte d’environnement approprié dans le menu déroulant (par exemple, Test pour le mode développement/bac à sable ou Production pour le traitement en direct).

Finaliser la connexion

Une fois les clés et l’environnement configurés :

Vérifiez la barre d’état (affiche actuellement Not Connected).
Cliquez sur le bouton noir Add en bas à droite pour enregistrer les identifiants et activer l’intégration de paiement.

Configuration Stripe

Intégration Stripe

Référence de l’API d’intégration Stripe

Gestion de la configuration

configureStripe

Crée une nouvelle configuration Stripe pour le projet et l’environnement.

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_..."
  }
}

Remarques :

La clé secrète est chiffrée avec AES-256-GCM avant stockage
Une seule configuration par combinaison projet/environnement
Renvoie une erreur si la configuration existe déjà

updateStripeConfig

Met à jour une configuration Stripe existante.

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

Remarques :

Tous les champs sont optionnels
Seuls les champs fournis sont mis à jour
La clé secrète est chiffrée si fournie

Gestion des clients

stripe_customer

Récupère un client unique par ID.

Query:

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

stripe_customers

Liste les clients avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
customerId: Filtrer par ID client (optionnel)

stripe_createCustomer

Crée un nouveau client.

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

Met à jour un client existant.

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

Remarques :

Tous les champs sont optionnels
Seuls les champs fournis sont mis à jour

stripe_deleteCustomer

Supprime un client.

Mutation:

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

Response:

Renvoie true en cas de succès
Renvoie une erreur si le client n’est pas trouvé

Intentions de paiement (Payment Intents)

stripe_paymentIntent

Récupère une intention de paiement unique par ID.

Query:

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

stripe_paymentIntents

Liste les intentions de paiement avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
customerId: Filtrer par ID client (optionnel)

stripe_createPaymentIntent

Crée une nouvelle intention de paiement.

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

Remarques :

clientSecret est renvoyé pour la confirmation frontend
Utilisez automaticPaymentMethods: true pour l’intégration Stripe.js

stripe_updatePaymentIntent

Met à jour une intention de paiement avant confirmation.

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

Remarques :

Ne peut être mis à jour qu’avant confirmation
Tous les champs sont optionnels

stripe_confirmPaymentIntent

Confirme une intention de paiement.

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

Remarques :

Requis pour finaliser le paiement
Peut nécessiter une authentification 3D Secure
Renvoie le statut mis à jour (succeeded, requires_action, etc.)

stripe_cancelPaymentIntent

Annule une intention de paiement.

Mutation:

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

Remarques :

Ne peut annuler que les intentions de paiement qui n’ont pas réussi ou été annulées
Le statut passe à “canceled”

Abonnements

stripe_subscription

Récupère un abonnement unique par 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

Liste les abonnements avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
customerId: Filtrer par ID client (optionnel)
status: Filtrer par statut (optionnel)

stripe_createSubscription

Crée un nouvel 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
      }
    }
  }
}

Remarques :

paymentBehavior peut être “default_incomplete” pour les abonnements nécessitant un mode de paiement
La période d’essai est spécifiée en jours
La dernière facture et l’intention de paiement sont automatiquement développées

stripe_updateSubscription

Met à jour un abonnement existant.

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

Annule un 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: ID de l’abonnement (requis)
cancelAtPeriodEnd: Si vrai, annule à la fin de la période; si faux, annule immédiatement (défaut : faux)

Remarques :

Annulation immédiate : l’abonnement se termine maintenant
Annulation en fin de période : l’abonnement continue jusqu’à la fin de la période en cours

Produits et Prix

stripe_products

Liste les produits avec pagination.

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

Crée un nouveau produit.

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

Liste les prix avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
productId: Filtrer par ID produit (optionnel)

stripe_createPrice

Crée un nouveau prix.

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

Remarques :

Omettre recurring pour les prix uniques
interval doit être l’un des suivants : “day”, “week”, “month”, “year”

Factures (Invoices)

stripe_invoice

Récupère une facture unique par 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
      }
    }
  }
}

Remarques :

L’ID d’abonnement est rempli via l’expansion de l’API lorsqu’il est disponible

stripe_invoices

Liste les factures avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
customerId: Filtrer par ID client (optionnel)
status: Filtrer par statut (optionnel)

stripe_payInvoice

Paie une facture de manière programmatique.

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

Remarques :

Tente de payer la facture en utilisant le mode de paiement par défaut du client
Renvoie une erreur si le paiement échoue
Met à jour le statut de la facture à “paid” en cas de succès

Remboursements (Refunds)

stripe_refunds

Liste les remboursements avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
paymentIntentId: Filtrer par ID d’intention de paiement (optionnel)

stripe_createRefund

Crée un remboursement pour une intention de paiement.

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

Remarques :

Omettre amount pour un remboursement complet
reason peut être : “duplicate”, “fraudulent”, “requested_by_customer”
Le statut du remboursement commence par “pending” et passe à “succeeded” ou “failed”

Méthodes de paiement (Payment Methods)

stripe_paymentMethods

Liste les méthodes de paiement avec pagination et filtrage optionnel.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination
customerId: Filtrer par ID client (optionnel)

Remarques :

Seules les informations de carte sécurisées sont renvoyées (4 derniers chiffres, marque, expiration)
Les numéros de carte complets ne sont jamais exposés

stripe_attachPaymentMethod

Attache une méthode de paiement à un client.

Mutation:

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

Remarques :

La méthode de paiement doit être créée d’abord (généralement via Stripe.js)
Les méthodes de paiement attachées peuvent être utilisées pour les abonnements et les paiements

stripe_detachPaymentMethod

Détache une méthode de paiement d’un client.

Mutation:

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

Remarques :

Les méthodes de paiement détachées ne peuvent plus être utilisées pour les paiements
Renvoie la méthode de paiement avec customerId défini à null

Événements Webhook

stripe_webhookEvents

Liste les événements webhook reçus par le service.

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: Nombre d’éléments à retourner (défaut : 10)
after: Curseur pour la pagination

Remarques :

Les événements sont reçus automatiquement via le point de terminaison webhook
Les événements sont stockés après vérification de la signature
Le champ data contient la charge utile complète de l’événement sous forme de chaîne JSON

Pagination

Toutes les requêtes de liste prennent en charge la pagination basée sur un curseur en utilisant le modèle de connexion Relay.

PageInfo

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

Exemple d’utilisation

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

Flux de pagination :

Requête initiale : first: 10, after: null
Utilisez pageInfo.endCursor de la réponse comme after dans la requête suivante
Vérifiez hasNextPage pour déterminer si d’autres pages existent

Valeurs par défaut :

first : Par défaut à 10 si non fourni
after : Commence depuis le début si non fourni

Gestion des erreurs

Toutes les opérations renvoient des erreurs GraphQL avec des messages conviviaux. Les erreurs sont mappées à partir des erreurs de l’API Stripe pour fournir un retour clair.

Scénarios d’erreur courants

Erreurs de configuration :

400: Format de clés Stripe invalide
404: Projet ou configuration non trouvé
400: La configuration existe déjà

Erreurs client :

404: Client non trouvé
400: Données client invalides

Erreurs d’intention de paiement :

404: Intention de paiement non trouvée
400: Montant ou devise invalide
402: Paiement échoué (carte refusée, fonds insuffisants, etc.)

Erreurs d’abonnement :

404: Abonnement non trouvé
400: Paramètres d’abonnement invalides
400: Impossible de mettre à jour un abonnement annulé

Codes d’erreur Stripe : Les codes d’erreur Stripe courants sont mappés à des messages conviviaux :

card_declined: “Votre carte a été refusée”
insufficient_funds: “Fonds insuffisants”
invalid_number: “Numéro de carte invalide”
expired_card: “La carte a expiré”
incorrect_cvc: “Code CVC incorrect”

Format de réponse d’erreur

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

Types de données

StripeEnvironment

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

Scalaire Map

Le type scalaire Map représente un mappage clé-valeur où :

Les clés sont des chaînes
Les valeurs peuvent être des chaînes, des nombres, des booléens ou des mappages imbriqués
Utilisé pour les champs de métadonnées

Exemple :

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

Scalaire Time

Le type scalaire Time représente des horodatages au format ISO 8601.

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