Stripe

O Stripe é uma plataforma de processamento de pagamentos online voltada para negócios na internet. Integrar o Stripe permite que seu aplicativo processe transações, assinaturas e dados financeiros com segurança.

Etapas de configuração

Depois de selecionar Stripe na lista de integrações, uma janela de configuração será exibida. Você deve informar as seguintes credenciais do painel do Stripe para estabelecer a conexão:

1. Chave secreta

Entrada: Digite sua chave secreta privada do Stripe (geralmente começa com sk_) no campo Secret Key. Essa chave permite que o backend autentique solicitações seguras.

2. Chave pública

Entrada: Digite sua chave pública do Stripe (geralmente começa com pk_) no campo Publishable Key. Essa chave é usada na implementação do front-end.

3. Ambiente

Entrada: Selecione o contexto de ambiente adequado no menu suspenso (por exemplo, Test para desenvolvimento ou modo sandbox, ou Production para processamento em produção).

Concluir a conexão

Quando as chaves e o ambiente estiverem configurados:

Verifique a barra de status (mostrará Not Connected).
Clique no botão preto Add no canto inferior direito para salvar as credenciais e ativar a integração de pagamentos.

Configuração da integração Stripe

Referência da API de integração Stripe

Gestão da configuração
Gestão de clientes
Intenções de pagamento
Assinaturas
Produtos e preços
Faturas
Reembolsos
Sessões de Checkout
Sessões do portal de cobrança
Métodos de pagamento
Eventos de webhook
Paginação
Tratamento de erros

Gestão da configuração {#configuration-management}

configureStripe {#configurestripe}

Cria uma nova configuração do Stripe para o projeto e o ambiente.

Mutação:

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

Entrada:

input ConfigureStripeInput {
  secretKey: String!          # Chave secreta Stripe (sk_test_... ou sk_live_...)
  publishableKey: String!    # Chave pública Stripe (pk_test_... ou pk_live_...)
  environment: StripeEnvironment!  # TEST ou LIVE
  webhookSecret: String      # Segredo de assinatura do webhook (opcional)
}

Resposta:

type ConfigureStripePayload {
  id: ID!                    # ID de configuração
  publishableKey: String!    # Chave pública
  webhookUrl: String!        # URL de webhook gerada
}

Exemplo:

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

Notas:

A chave secreta é criptografada com AES-256-GCM antes de ser armazenada
Só uma configuração por combinação projeto/ambiente
Retorna erro se a configuração já existir

updateStripeConfig {#updatestripeconfig}

Atualiza uma configuração Stripe existente.

Mutação:

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

Entrada:

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

Resposta:

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

Notas:

Todos os campos são opcionais
Só são atualizados os campos fornecidos
A chave secreta é criptografada se fornecida

Gestão de clientes {#customer-management}

stripe_customer {#stripe_customer}

Obtém um único cliente por ID.

Consulta:

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

stripe_customers {#stripe_customers}

Lista clientes com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

stripe_createCustomer {#stripe_createcustomer}

Cria um novo cliente.

Mutação:

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}

Atualiza um cliente existente.

Mutação:

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

Notas:

Todos os campos são opcionais
Só são atualizados os campos fornecidos

stripe_deleteCustomer {#stripe_deletecustomer}

Elimina um cliente.

Mutação:

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

Resposta:

Retorna true em caso de sucesso
Retorna erro se o cliente não for encontrado

Intenções de pagamento {#payment-intents}

stripe_paymentIntent {#stripe_paymentintent}

Obtém uma única intenção de pagamento por ID.

Consulta:

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

stripe_paymentIntents {#stripe_paymentintents}

Lista intenções de pagamento com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

stripe_createPaymentIntent {#stripe_createpaymentintent}

Cria uma nova intenção de pagamento.

Mutação:

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

Notas:

É retornado clientSecret para confirmação no frontend
Utilize automaticPaymentMethods: true para integração com Stripe.js

stripe_updatePaymentIntent {#stripe_updatepaymentintent}

Atualiza uma intenção de pagamento antes da confirmação.

Mutação:

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

Notas:

Só pode ser atualizada antes da confirmação
Todos os campos são opcionais

stripe_confirmPaymentIntent {#stripe_confirmpaymentintent}

Confirma uma intenção de pagamento.

Mutação:

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

Notas:

Necessário para concluir o pagamento
Pode exigir autenticação 3D Secure
Retorna o estado atualizado (succeeded, requires_action, etc.)

stripe_cancelPaymentIntent {#stripe_cancelpaymentintent}

Cancela uma intenção de pagamento.

Mutação:

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

Notas:

Só podem ser canceladas intenções que não estejam em succeeded ou canceled
O estado passa a “canceled”

Assinaturas {#subscriptions}

stripe_subscription {#stripe_subscription}

Obtém uma única assinatura por ID.

Consulta:

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}

Lista assinaturas com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por estado (opcional)

stripe_createSubscription {#stripe_createsubscription}

Cria uma nova assinatura.

Mutação:

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

Notas:

paymentBehavior pode ser “default_incomplete” para assinaturas que exijam método de pagamento
O período experimental indica-se em dias
A última fatura e a intenção de pagamento são expandidas automaticamente

stripe_updateSubscription {#stripe_updatesubscription}

Atualiza uma assinatura existente.

Mutação:

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}

Cancela uma assinatura.

Mutação:

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

Parâmetros:

id: ID da assinatura (obrigatório)
cancelAtPeriodEnd: Se for true, cancela no fim do período; se for false, cancela de imediato (predefinição: false)

Notas:

Cancelamento imediato: a assinatura termina agora
Cancelamento no fim do período: a assinatura continua até o fim do período atual

Produtos e preços {#products-and-prices}

stripe_products {#stripe_products}

Lista produtos com paginação.

Consulta:

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}

Cria um novo produto.

Mutação:

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}

Lista preços com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
productId: Filtrar por ID do produto (opcional)

stripe_createPrice {#stripe_createprice}

Cria um novo preço.

Mutação:

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

Notas:

Omita recurring para preços únicos
interval tem de ser um de: “day”, “week”, “month”, “year”

Faturas {#invoices}

stripe_invoice {#stripe_invoice}

Obtém uma única fatura por ID.

Consulta:

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

Notas:

O ID da assinatura é preenchido através da expansão da API quando disponível

stripe_invoices {#stripe_invoices}

Lista faturas com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por estado (opcional)

stripe_payInvoice {#stripe_payinvoice}

Paga uma fatura de forma programática.

Mutação:

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

Notas:

Tenta pagar a fatura com o método de pagamento predefinido do cliente
Retorna erro se o pagamento falhar
Atualiza o estado da fatura para “paid” em caso de sucesso

Reembolsos {#refunds}

stripe_refunds {#stripe_refunds}

Lista reembolsos com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
paymentIntentId: Filtrar por ID da intenção de pagamento (opcional)

stripe_createRefund {#stripe_createrefund}

Cria um reembolso para uma intenção de pagamento.

Mutação:

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

Notas:

Omita amount para reembolso total
reason pode ser: “duplicate”, “fraudulent”, “requested_by_customer”
O estado do reembolso começa como “pending” e passa a “succeeded” ou “failed”

Sessões de Checkout {#checkout-sessions}

stripe_createCheckoutSession {#stripe_createcheckoutsession}

Cria uma sessão Stripe Checkout para pagamentos únicos ou assinaturas. Retorna uma URL que redireciona os clientes para a página de pagamento hospedada pelo Stripe.

Mutação:

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

Entrada:

input StripeCreateCheckoutSessionInput {
  customerId: String              # ID de cliente Stripe existente (opcional)
  customerEmail: String            # E-mail para novos clientes (opcional)
  mode: String!                   # "payment" para único ou "subscription" para recorrente
  successUrl: String!             # URL de redirecionamento após pagamento bem-sucedido
  cancelUrl: String!              # URL de redirecionamento se o cliente cancelar
  lineItems: [StripeCheckoutSessionLineItemInput!]!  # Itens a comprar
  paymentMethodTypes: [String!]    # Métodos de pagamento permitidos (opcional)
  metadata: Map                    # Metadados personalizados (opcional)
}

input StripeCheckoutSessionLineItemInput {
  priceId: String      # ID de preço Stripe (preços existentes)
  quantity: Int!        # Quantidade de itens
  amount: Float         # Montante personalizado em dólares (pagamentos únicos)
  currency: String      # Código de moeda (obrigatório se amount for indicado)
}

Resposta:

type StripeCheckoutSession {
  id: ID!                    # ID de sessão
  object: String!            # "checkout.session"
  url: String!              # URL de redirecionamento para o cliente
  customerId: String        # ID do cliente (se existir)
  customerEmail: String     # E-mail do cliente
  paymentIntentId: String   # ID de intenção de pagamento (pagamentos únicos)
  subscriptionId: String    # ID de assinatura (assinaturas)
  mode: String!             # "payment" ou "subscription"
  status: String!            # Estado da sessão
  currency: String          # Código de moeda
  amountTotal: Float        # Montante total em dólares
  metadata: Map             # Metadados personalizados
  createdAt: Time!          # Data e hora de criação
}

Exemplo — Pagamento único:

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

Exemplo — Pagamento único com montante personalizado:

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

Exemplo — Assinatura:

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

Notas:

O campo url contém a URL de redirecionamento para onde os clientes devem ser enviados
Para pagamentos únicos, utilize mode: "payment" e forneça priceId ou amount + currency
Para assinaturas, utilize mode: "subscription" e forneça priceId (tem de ser um preço recorrente)
Deve indicar-se customerId ou customerEmail, mas não ambos
paymentMethodTypes pode incluir: “card”, “us_bank_account”, “link”, etc.
As sessões expiram ao fim de 24 horas se não forem concluídas

Sessões do portal de cobrança {#billing-portal-sessions}

stripe_createBillingPortalSession {#stripe_createbillingportalsession}

Cria uma sessão do portal de cobrança Stripe para os clientes gerenciarem assinaturas, métodos de pagamento e informações de cobrança no portal hospedado pelo Stripe.

Mutação:

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

Entrada:

input StripeCreateBillingPortalSessionInput {
  customerId: String!      # ID de cliente Stripe (obrigatório)
  returnUrl: String!       # URL de redirecionamento ao sair do portal
  configuration: String    # ID de configuração do portal (opcional)
}

Resposta:

type StripeBillingPortalSession {
  id: ID!            # ID de sessão
  object: String!    # "billing_portal.session"
  url: String!       # URL de redirecionamento para o cliente
  customerId: String!  # ID do cliente
  returnUrl: String   # URL de regresso
  createdAt: Time!   # Data e hora de criação
}

Exemplo:

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

Notas:

O campo url contém a URL de redirecionamento para onde os clientes devem ser enviados
A sessão do portal é de curta duração e expira após o uso
Os clientes podem gerenciar assinaturas, atualizar métodos de pagamento, ver faturas e atualizar dados de cobrança
As funções do portal configuram-se no painel Stripe
Se configuration não for fornecida, é utilizada a configuração predefinida do portal
O portal só mostra assinaturas e faturas do cliente indicado

Métodos de pagamento {#payment-methods}

stripe_paymentMethods {#stripe_paymentmethods}

Lista métodos de pagamento com paginação e filtragem opcional.

Consulta:

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

Parâmetros:

first: Número de itens a retornar (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

Notas:

Somente informações seguras do cartão são retornadas (last4, marca, validade)
Os números completos do cartão nunca são expostos

stripe_attachPaymentMethod {#stripe_attachpaymentmethod}

Associa um método de pagamento a um cliente.

Mutação:

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

Notas:

O método de pagamento tem de ser criado antes (normalmente com Stripe.js)
Os métodos associados podem ser usados em assinaturas e pagamentos

stripe_detachPaymentMethod {#stripe_detachpaymentmethod}

Desassocia um método de pagamento de um cliente.

Mutação:

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

Notas:

Os métodos desassociados já não podem ser usados para pagamentos
Retorna o método de pagamento com customerId a null

Eventos de webhook {#webhook-events}

stripe_webhookEvents {#stripe_webhookevents}

Lista os eventos de webhook recebidos pelo serviço.

Consulta:

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

Resposta:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Tipo de evento (p. ex., "payment_intent.succeeded")
  data: String!              # Cadeia JSON com os dados do evento
  processed: Boolean!        # Se o evento foi processado
  createdAt: Time!
}

Parâmetros:

first: Número de itens a retornar (padrão: 10)
after: Cursor para paginação

Notas:

Os eventos são recebidos automaticamente no endpoint do webhook
Os eventos são armazenados após verificação da assinatura
O campo data contém a carga completa do evento como cadeia JSON

Paginação {#pagination}

Todas as consultas de listagem suportam paginação baseada em cursores com o padrão de link Relay.

PageInfo {#pageinfo}

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

Exemplo de uso {#usage-example}

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

Fluxo de paginação:

Pedido inicial: first: 10, after: null
Utilize pageInfo.endCursor da resposta como after no pedido seguinte
Verifique hasNextPage para saber se existem mais páginas

Valores predefinidos:

first: Por predefinição 10 se não for indicado
after: Começa do início se não for indicado

Tratamento de erros {#error-handling}

Todas as operações retornam erros GraphQL com mensagens claras para o usuário. Os erros são mapeados a partir dos erros da API Stripe para fornecer feedback útil.

Cenários de erro frequentes {#common-error-scenarios}

Erros de configuração:

400: Formato de chaves Stripe inválido
404: Projeto ou configuração não encontrado
400: A configuração já existe

Erros de cliente:

404: Cliente não encontrado
400: Dados de cliente inválidos

Erros de intenção de pagamento:

404: Intenção de pagamento não encontrada
400: Montante ou moeda inválidos
402: Pagamento falhou (cartão recusado, fundos insuficientes, etc.)

Erros de assinatura:

404: Assinatura não encontrada
400: Parâmetros de assinatura inválidos
400: Não é possível atualizar uma assinatura cancelada

Códigos de erro Stripe: Os códigos habituais do Stripe são mapeados para mensagens claras:

card_declined: “Seu cartão foi recusado”
insufficient_funds: “Fundos insuficientes”
invalid_number: “Número de cartão inválido”
expired_card: “O cartão expirou”
incorrect_cvc: “Código CVC incorreto”

Formato de resposta de erro {#error-response-format}

{
  "errors": [
    {
      "message": "Cliente não encontrado",
      "extensions": {
        "code": "NOT_FOUND",
        "stripeErrorCode": "resource_missing"
      }
    }
  ],
  "data": null
}

Tipos de dados {#data-types}

StripeEnvironment {#stripe-environment}

enum StripeEnvironment {
  TEST  # Modo de teste
  LIVE  # Modo em produção / live
}

Escalar Map {#map-scalar}

O tipo escalar Map representa um mapa chave-valor onde:

As chaves são cadeias
Os valores podem ser cadeias, números, booleanos ou mapas aninhados
É usado em campos de metadados

Exemplo:

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

Escalar Time {#time-scalar}

O tipo escalar Time representa data/hora em formato ISO 8601.

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