Aggiungere l'integrazione di Stripe

Stripe è una piattaforma di elaborazione pagamenti online progettata per le aziende su internet. L’integrazione di Stripe consente alla tua applicazione di gestire transazioni, abbonamenti e dati finanziari in modo sicuro.

Passaggi di configurazione

Dopo aver selezionato Stripe dall’elenco delle integrazioni, apparirà una finestra modale di configurazione. È necessario fornire le seguenti credenziali dalla dashboard di Stripe per stabilire la connessione:

1. Chiave segreta (Secret Key)

Input: Inserisci la tua Chiave Segreta Stripe privata (solitamente inizia con sk_) nel campo Secret Key. Questa chiave consente al backend di autenticare le richieste sicure.

2. Chiave pubblicabile (Publishable Key)

Input: Inserisci la tua Chiave Pubblicabile Stripe pubblica (solitamente inizia con pk_) nel campo Publishable Key. Questa chiave viene utilizzata per l’implementazione frontend.

3. Ambiente

Input: Seleziona il contesto dell’ambiente appropriato dal menu a discesa (ad es. Test per la modalità di sviluppo/sandbox o Production per l’elaborazione live).

Finalizzare la connessione

Una volta configurate le chiavi e l’ambiente:

Controlla la barra di stato (attualmente mostra Not Connected).
Fai clic sul pulsante nero Add in basso a destra per salvare le credenziali e attivare l’integrazione dei pagamenti.

Configurazione Stripe

Integrazione Stripe

Riferimento API dell’integrazione di Stripe

Gestione della configurazione

configureStripe

Crea una nuova configurazione Stripe per il progetto e l’ambiente.

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

Note:

La chiave segreta viene crittografata con AES-256-GCM prima dell’archiviazione
Solo una configurazione per combinazione progetto/ambiente
Restituisce un errore se la configurazione esiste già

updateStripeConfig

Aggiorna una configurazione Stripe esistente.

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

Note:

Tutti i campi sono opzionali
Vengono aggiornati solo i campi forniti
La chiave segreta viene crittografata se fornita

Gestione clienti

stripe_customer

Recupera un singolo cliente tramite ID.

Query:

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

stripe_customers

Elenca i clienti con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
customerId: Filtra per ID cliente (opzionale)

stripe_createCustomer

Crea un nuovo cliente.

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

Aggiorna un cliente esistente.

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

Note:

Tutti i campi sono opzionali
Vengono aggiornati solo i campi forniti

stripe_deleteCustomer

Elimina un cliente.

Mutation:

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

Response:

Restituisce true in caso di successo
Restituisce un errore se il cliente non viene trovato

Intenti di pagamento (Payment Intents)

stripe_paymentIntent

Recupera un singolo intento di pagamento tramite ID.

Query:

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

stripe_paymentIntents

Elenca gli intenti di pagamento con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
customerId: Filtra per ID cliente (opzionale)

stripe_createPaymentIntent

Crea un nuovo intento di pagamento.

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

Note:

clientSecret viene restituito per la conferma frontend
Usa automaticPaymentMethods: true per l’integrazione con Stripe.js

stripe_updatePaymentIntent

Aggiorna un intento di pagamento prima della conferma.

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

Note:

Può essere aggiornato solo prima della conferma
Tutti i campi sono opzionali

stripe_confirmPaymentIntent

Conferma un intento di pagamento.

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

Note:

Richiesto per completare il pagamento
Potrebbe richiedere l’autenticazione 3D Secure
Restituisce lo stato aggiornato (succeeded, requires_action, ecc.)

stripe_cancelPaymentIntent

Annulla un intento di pagamento.

Mutation:

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

Note:

Può annullare solo intenti di pagamento non riusciti o annullati
Lo stato cambia in “canceled”

Abbonamenti

stripe_subscription

Recupera un singolo abbonamento tramite 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

Elenca gli abbonamenti con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
customerId: Filtra per ID cliente (opzionale)
status: Filtra per stato (opzionale)

stripe_createSubscription

Crea un nuovo abbonamento.

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

Note:

paymentBehavior può essere “default_incomplete” per gli abbonamenti che richiedono un metodo di pagamento
Il periodo di prova è specificato in giorni
L’ultima fattura e l’intento di pagamento vengono espansi automaticamente

stripe_updateSubscription

Aggiorna un abbonamento esistente.

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

Annulla un abbonamento.

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 abbonamento (richiesto)
cancelAtPeriodEnd: Se true, annulla alla fine del periodo; se false, annulla immediatamente (predefinito: false)

Note:

Annullamento immediato: l’abbonamento termina ora
Annullamento a fine periodo: l’abbonamento continua fino al termine del periodo corrente

Prodotti e Prezzi

stripe_products

Elenca i prodotti con impaginazione.

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

Crea un nuovo prodotto.

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

Elenca i prezzi con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
productId: Filtra per ID prodotto (opzionale)

stripe_createPrice

Crea un nuovo prezzo.

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

Note:

Ometti recurring per prezzi una tantum
interval deve essere uno dei seguenti: “day”, “week”, “month”, “year”

Fatture (Invoices)

stripe_invoice

Recupera una singola fattura tramite 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
      }
    }
  }
}

Note:

L’ID dell’abbonamento viene popolato tramite espansione API quando disponibile

stripe_invoices

Elenca le fatture con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
customerId: Filtra per ID cliente (opzionale)
status: Filtra per stato (opzionale)

stripe_payInvoice

Paga una fattura a livello di programmazione.

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

Note:

Tenta di pagare la fattura utilizzando il metodo di pagamento predefinito del cliente
Restituisce un errore se il pagamento non riesce
Aggiorna lo stato della fattura a “paid” in caso di successo

Rimborsi (Refunds)

stripe_refunds

Elenca i rimborsi con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
paymentIntentId: Filtra per ID intento di pagamento (opzionale)

stripe_createRefund

Crea un rimborso per un intento di pagamento.

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

Note:

Ometti amount per il rimborso completo
reason può essere: “duplicate”, “fraudulent”, “requested_by_customer”
Lo stato del rimborso inizia come “pending” e si aggiorna a “succeeded” o “failed”

Metodi di pagamento (Payment Methods)

stripe_paymentMethods

Elenca i metodi di pagamento con impaginazione e filtro opzionale.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione
customerId: Filtra per ID cliente (opzionale)

Note:

Vengono restituite solo le informazioni sicure della carta (ultime 4 cifre, marca, scadenza)
I numeri completi delle carte non vengono mai esposti

stripe_attachPaymentMethod

Collega un metodo di pagamento a un cliente.

Mutation:

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

Note:

Il metodo di pagamento deve essere creato prima (in genere tramite Stripe.js)
I metodi di pagamento collegati possono essere utilizzati per abbonamenti e pagamenti

stripe_detachPaymentMethod

Scollega un metodo di pagamento da un cliente.

Mutation:

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

Note:

I metodi di pagamento scollegati non possono più essere utilizzati per i pagamenti
Restituisce il metodo di pagamento con customerId impostato su null

Eventi Webhook

stripe_webhookEvents

Elenca gli eventi webhook ricevuti dal servizio.

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: Numero di elementi da restituire (predefinito: 10)
after: Cursore per l’impaginazione

Note:

Gli eventi vengono ricevuti automaticamente tramite l’endpoint webhook
Gli eventi vengono archiviati dopo la verifica della firma
Il campo data contiene il payload completo dell’evento come stringa JSON

Impaginazione (Pagination)

Tutte le query di elenco supportano l’impaginazione basata su cursore utilizzando il modello di connessione Relay.

PageInfo

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

Esempio di utilizzo

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

Flusso di impaginazione:

Richiesta iniziale: first: 10, after: null
Usa pageInfo.endCursor dalla risposta come after nella richiesta successiva
Controlla hasNextPage per determinare se esistono altre pagine

Valori predefiniti:

first: Predefinito a 10 se non fornito
after: Inizia dall’inizio se non fornito

Gestione errori

Tutte le operazioni restituiscono errori GraphQL con messaggi user-friendly. Gli errori sono mappati dagli errori dell’API di Stripe per fornire un feedback chiaro.

Scenari di errore comuni

Errori di configurazione:

400: Formato chiavi Stripe non valido
404: Progetto o configurazione non trovati
400: La configurazione esiste già

Errori del cliente:

404: Cliente non trovato
400: Dati cliente non validi

Errori intento di pagamento:

404: Intento di pagamento non trovato
400: Importo o valuta non validi
402: Pagamento fallito (carta rifiutata, fondi insufficienti, ecc.)

Errori abbonamento:

404: Abbonamento non trovato
400: Parametri abbonamento non validi
400: Impossibile aggiornare un abbonamento annullato

Codici di errore Stripe: I codici di errore Stripe comuni sono mappati a messaggi user-friendly:

card_declined: “La tua carta è stata rifiutata”
insufficient_funds: “Fondi insufficienti”
invalid_number: “Numero di carta non valido”
expired_card: “La carta è scaduta”
incorrect_cvc: “Codice CVC errato”

Formato risposta errore

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

Tipi di dati

StripeEnvironment

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

Scalar Map

Il tipo scalare Map rappresenta una mappa chiave-valore in cui:

Le chiavi sono stringhe
I valori possono essere stringhe, numeri, booleani o mappe nidificate
Usato per i campi di metadati

Esempio:

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

Scalar Time

Il tipo scalare Time rappresenta timestamp formattati ISO 8601.

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