Stripe

Stripe è una piattaforma di elaborazione dei pagamenti online pensata per le aziende su Internet. Integrare 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, si aprirà una finestra di configurazione. Devi fornire le seguenti credenziali dal pannello Stripe per stabilire la connessione:

1. Chiave segreta

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

2. Chiave pubblicabile

Input: Inserisci la tua chiave pubblicabile Stripe (di solito inizia con pk_) nel campo Publishable Key. Questa chiave è usata per l’implementazione lato frontend.

3. Ambiente

Input: Seleziona il contesto di ambiente appropriato dal menu a discesa (ad es. Test per sviluppo o modalità sandbox, oppure Production per l’elaborazione in produzione).

Completare la connessione

Quando chiavi e ambiente sono configurati:

Controlla la barra di stato (mostra Non connesso).
Fai clic sul pulsante nero Aggiungi in basso a destra per salvare le credenziali e attivare l’integrazione di pagamento.

Configurazione dell’integrazione Stripe

Riferimento API dell’integrazione Stripe

Gestione della configurazione
Gestione clienti
Payment Intent
Abbonamenti
Prodotti e prezzi
Fatture
Rimborsi
Sessioni Checkout
Sessioni del portale di fatturazione
Metodi di pagamento
Eventi webhook
Paginazione
Gestione degli errori

Gestione della configurazione {#configuration-management}

configureStripe {#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!          # Chiave segreta Stripe (sk_test_... o sk_live_...)
  publishableKey: String!    # Chiave pubblicabile Stripe (pk_test_... o pk_live_...)
  environment: StripeEnvironment!  # TEST o LIVE
  webhookSecret: String      # Segreto di firma webhook (opzionale)
}

Risposta:

type ConfigureStripePayload {
  id: ID!                    # ID configurazione
  publishableKey: String!    # Chiave pubblicabile
  webhookUrl: String!        # URL webhook generata
}

Esempio:

{
  "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 errore se la configurazione esiste già

updateStripeConfig {#updatestripeconfig}

Aggiorna una configurazione Stripe esistente.

Mutation:

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

Input:

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

Risposta:

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 {#customer-management}

stripe_customer {#stripe_customer}

Recupera un singolo cliente per ID.

Query:

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

stripe_customers {#stripe_customers}

Elenca i clienti con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
customerId: filtra per ID cliente (opzionale)

stripe_createCustomer {#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 {#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 {#stripe_deletecustomer}

Elimina un cliente.

Mutation:

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

Risposta:

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

Payment Intent {#payment-intents}

stripe_paymentIntent {#stripe_paymentintent}

Recupera un singolo Payment Intent per ID.

Query:

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

stripe_paymentIntents {#stripe_paymentintents}

Elenca i Payment Intent con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
customerId: filtra per ID cliente (opzionale)

stripe_createPaymentIntent {#stripe_createpaymentintent}

Crea un nuovo 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
  }
}

Note:

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

stripe_updatePaymentIntent {#stripe_updatepaymentintent}

Aggiorna un Payment Intent 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:

È possibile aggiornare solo prima della conferma
Tutti i campi sono opzionali

stripe_confirmPaymentIntent {#stripe_confirmpaymentintent}

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

Note:

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

stripe_cancelPaymentIntent {#stripe_cancelpaymentintent}

Annulla un Payment Intent.

Mutation:

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

Note:

È possibile annullare solo i Payment Intent che non siano succeeded o canceled
Lo stato diventa “canceled”

Abbonamenti {#subscriptions}

stripe_subscription {#stripe_subscription}

Recupera un singolo abbonamento per 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 {#stripe_subscriptions}

Elenca gli abbonamenti con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
customerId: filtra per ID cliente (opzionale)
status: filtra per stato (opzionale)

stripe_createSubscription {#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 abbonamenti che richiedono un metodo di pagamento
Il periodo di prova è indicato in giorni
L’ultima fattura e il Payment Intent vengono espansi automaticamente

stripe_updateSubscription {#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 {#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
      }
    }
  }
}

Parametri:

id: ID abbonamento (obbligatorio)
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 alla fine del periodo corrente

Prodotti e prezzi {#products-and-prices}

stripe_products {#stripe_products}

Elenca i prodotti con paginazione.

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 {#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 {#stripe_prices}

Elenca i prezzi con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
productId: filtra per ID prodotto (opzionale)

stripe_createPrice {#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 tra: “day”, “week”, “month”, “year”

Fatture {#invoices}

stripe_invoice {#stripe_invoice}

Recupera una singola fattura per 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 abbonamento viene popolato tramite espansione API quando disponibile

stripe_invoices {#stripe_invoices}

Elenca le fatture con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
customerId: filtra per ID cliente (opzionale)
status: filtra per stato (opzionale)

stripe_payInvoice {#stripe_payinvoice}

Paga una fattura in modo programmatico.

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 con il metodo di pagamento predefinito del cliente
Restituisce errore se il pagamento fallisce
Aggiorna lo stato della fattura a “paid” in caso di successo

Rimborsi {#refunds}

stripe_refunds {#stripe_refunds}

Elenca i rimborsi con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
paymentIntentId: filtra per ID Payment Intent (opzionale)

stripe_createRefund {#stripe_createrefund}

Crea un rimborso per un 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
  }
}

Note:

Ometti amount per rimborso totale
reason puede ser: “duplicate”, “fraudulent”, “requested_by_customer”
Lo stato del rimborso inizia come “pending” e passa a “succeeded” o “failed”

Sessioni Checkout {#checkout-sessions}

stripe_createCheckoutSession {#stripe_createcheckoutsession}

Crea una sessione Stripe Checkout per pagamenti una tantum o abbonamenti. Restituisce un URL che reindirizza i clienti alla pagina di pagamento ospitata da Stripe.

Mutation:

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

Input:

input StripeCreateCheckoutSessionInput {
  customerId: String              # ID cliente Stripe esistente (opzionale)
  customerEmail: String            # Email per nuovi clienti (opzionale)
  mode: String!                   # "payment" per una tantum o "subscription" per ricorrente
  successUrl: String!             # URL di reindirizzamento dopo pagamento riuscito
  cancelUrl: String!              # URL di reindirizzamento se il cliente annulla
  lineItems: [StripeCheckoutSessionLineItemInput!]!  # Articoli da acquistare
  paymentMethodTypes: [String!]    # Metodi di pagamento consentiti (opzionale)
  metadata: Map                    # Metadati personalizzati (opzionale)
}

input StripeCheckoutSessionLineItemInput {
  priceId: String      # ID prezzo Stripe (prezzi esistenti)
  quantity: Int!        # Quantità di articoli
  amount: Float         # Importo personalizzato in dollari (pagamenti una tantum)
  currency: String      # Codice valuta (obbligatorio se si indica amount)
}

Risposta:

type StripeCheckoutSession {
  id: ID!                    # ID sessione
  object: String!            # "checkout.session"
  url: String!              # URL di reindirizzamento per il cliente
  customerId: String        # ID cliente (se esiste)
  customerEmail: String     # Email del cliente
  paymentIntentId: String   # ID Payment Intent (pagamenti una tantum)
  subscriptionId: String    # ID abbonamento (abbonamenti)
  mode: String!             # "payment" o "subscription"
  status: String!            # Stato della sessione
  currency: String          # Codice valuta
  amountTotal: Float        # Importo totale in dollari
  metadata: Map             # Metadati personalizzati
  createdAt: Time!          # Timestamp di creazione
}

Esempio — Pagamento una tantum:

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

Esempio — Pagamento una tantum con importo personalizzato:

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

Esempio — Abbonamento:

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

Note:

Il campo url contiene l’URL di reindirizzamento a cui inviare i clienti
Per pagamenti una tantum, usa mode: "payment" e fornisci priceId oppure amount + currency
Per abbonamenti, usa mode: "subscription" e fornisci priceId (deve essere un prezzo ricorrente)
Deve essere indicato customerId o customerEmail, ma non entrambi
paymentMethodTypes può includere: “card”, “us_bank_account”, “link”, ecc.
Le sessioni scadono dopo 24 ore se non vengono completate

Sessioni del portale di fatturazione {#billing-portal-sessions}

stripe_createBillingPortalSession {#stripe_createbillingportalsession}

Crea una sessione del portale di fatturazione Stripe che consente ai clienti di gestire abbonamenti, metodi di pagamento e informazioni di fatturazione nel portale ospitato da Stripe.

Mutation:

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

Input:

input StripeCreateBillingPortalSessionInput {
  customerId: String!      # ID cliente Stripe (obbligatorio)
  returnUrl: String!       # URL di reindirizzamento all’uscita dal portale
  configuration: String    # ID configurazione del portale (opzionale)
}

Risposta:

type StripeBillingPortalSession {
  id: ID!            # ID sessione
  object: String!    # "billing_portal.session"
  url: String!       # URL di reindirizzamento per il cliente
  customerId: String!  # ID de cliente
  returnUrl: String   # URL di ritorno
  createdAt: Time!   # Timestamp di creazione
}

Esempio:

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

Note:

Il campo url contiene l’URL di reindirizzamento a cui inviare i clienti
La sessione del portale è di breve durata e scade dopo l’uso
I clienti possono gestire abbonamenti, aggiornare metodi di pagamento, visualizzare fatture e aggiornare i dati di fatturazione
Le funzioni del portale sono configurate nel pannello Stripe
Se configuration non è fornita, viene usata la configurazione predefinita del portale
Il portale mostra solo abbonamenti e fatture del cliente indicato

Metodi di pagamento {#payment-methods}

stripe_paymentMethods {#stripe_paymentmethods}

Elenca i metodi di pagamento con paginazione 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
    }
  }
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione
customerId: filtra per ID cliente (opzionale)

Note:

Vengono restituite solo informazioni sicure sulla carta (last4, brand, scadenza)
I numeri completi della carta non sono mai esposti

stripe_attachPaymentMethod {#stripe_attachpaymentmethod}

Associa 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 (di solito con Stripe.js)
I metodi associati possono essere usati per abbonamenti e pagamenti

stripe_detachPaymentMethod {#stripe_detachpaymentmethod}

Dissocia 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 dissociati non possono più essere usati per i pagamenti
Restituisce il metodo di pagamento con customerId impostato su null

Eventi webhook {#webhook-events}

stripe_webhookEvents {#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
    }
  }
}

Risposta:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Tipo di evento (es. "payment_intent.succeeded")
  data: String!              # Stringa JSON dei dati dell’evento
  processed: Boolean!        # Se l’evento è stato elaborato
  createdAt: Time!
}

Parametri:

first: numero di elementi da restituire (predefinito: 10)
after: cursore per la paginazione

Note:

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

Paginazione {#pagination}

Tutte le query di elenco supportano la paginazione basata su cursore con il pattern di connessione Relay.

PageInfo {#pageinfo}

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

Esempio d’uso {#usage-example}

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

Flusso di paginazione:

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

Valori predefiniti:

first: predefinito 10 se non indicato
after: inizio dall’inizio se non indicato

Gestione degli errori {#error-handling}

Tutte le operazioni restituiscono errori GraphQL con messaggi chiari per l’utente. Gli errori sono mappati dagli errori dell’API Stripe per fornire un feedback utile.

Scenari di errore comuni {#common-error-scenarios}

Errori di configurazione:

400: formato chiavi Stripe non valido
404: progetto o configurazione non trovata
400: la configurazione esiste già

Errori cliente:

404: cliente non trovato
400: dati cliente non validi

Errori Payment Intent:

404: Payment Intent non trovato
400: importo o valuta non validi
402: pagamento non riuscito (carta rifiutata, fondi insufficienti, ecc.)

Errori abbonamento:

404: abbonamento non trovato
400: parametri abbonamento non validi
400: impossibile aggiornare un abbonamento annullato

Codici errore Stripe: I codici comuni di Stripe sono mappati su messaggi chiari:

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 {#error-response-format}

{
  "errors": [
    {
      "message": "Cliente non trovato",
      "extensions": {
        "code": "NOT_FOUND",
        "stripeErrorCode": "resource_missing"
      }
    }
  ],
  "data": null
}

Tipi di dati {#data-types}

StripeEnvironment {#stripe-environment}

enum StripeEnvironment {
  TEST  # Modalità test
  LIVE  # Modalità live / produzione
}

Scalare Map {#map-scalar}

Lo scalare Map rappresenta una mappa chiave-valore in cui:

Le chiavi sono stringhe
I valori possono essere stringhe, numeri, booleani o mappe annidate
È usato nei campi metadati

Esempio:

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

Scalare Time {#time-scalar}

Lo scalare Time rappresenta timestamp in formato ISO 8601.

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