Adicionar a integração Stripe

A Stripe é uma plataforma de processamento de pagamentos online projetada para negócios na internet. A integração da Stripe permite que seu aplicativo processe transações, assinaturas e dados financeiros de forma segura.

Etapas de configuração

Após selecionar Stripe na lista de integrações, aparecerá um modal de configuração. Você deve fornecer as seguintes credenciais do seu Painel Stripe para estabelecer a conexão:

1. Chave secreta (Secret Key)

Entrada: Insira sua Chave Secreta Stripe privada (geralmente começa com sk_) no campo Secret Key. Esta chave permite que o backend autentique solicitações seguras.

2. Chave publicável (Publishable Key)

Entrada: Insira sua Chave Publicável Stripe pública (geralmente começa com pk_) no campo Publishable Key. Esta chave é usada para a implementação frontend.

3. Ambiente

Entrada: Selecione o contexto de ambiente apropriado no menu suspenso (por exemplo, Test para modo de desenvolvimento/sandbox ou Production para processamento em tempo real).

Finalizando a conexão

Uma vez configuradas as chaves e o ambiente:

Verifique a barra de status (atualmente mostra 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 Stripe

Integração Stripe

Referência da API de integração Stripe

Gerenciamento de configuração

configureStripe

Cria uma nova configuração Stripe para o projeto e 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_..."
  }
}

Notas:

A chave secreta é criptografada com AES-256-GCM antes do armazenamento
Apenas uma configuração por combinação projeto/ambiente
Retorna erro se a configuração já existir

updateStripeConfig

Atualiza uma configuração Stripe existente.

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

Notas:

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

Gerenciamento de clientes

stripe_customer

Recupera um único cliente por ID.

Query:

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

stripe_customers

Lista clientes com paginação e filtragem opcional.

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

stripe_createCustomer

Cria um novo 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

Atualiza um cliente existente.

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

Notas:

Todos os campos são opcionais
Apenas os campos fornecidos são atualizados

stripe_deleteCustomer

Exclui um cliente.

Mutation:

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

Response:

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

Intenções de pagamento (Payment Intents)

stripe_paymentIntent

Recupera uma única intenção de pagamento por ID.

Query:

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

stripe_paymentIntents

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

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

stripe_createPaymentIntent

Cria uma nova intenção de 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
  }
}

Notas:

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

stripe_updatePaymentIntent

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

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

Notas:

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

stripe_confirmPaymentIntent

Confirma uma intenção de 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
  }
}

Notas:

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

stripe_cancelPaymentIntent

Cancela uma intenção de pagamento.

Mutation:

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

Notas:

Só pode cancelar intenções de pagamento que não tenham sido bem-sucedidas ou canceladas
O status muda para “canceled”

Assinaturas

stripe_subscription

Recupera uma única assinatura por 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

Lista assinaturas com paginação e filtragem opcional.

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por status (opcional)

stripe_createSubscription

Cria uma nova assinatura.

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

Notas:

paymentBehavior pode ser “default_incomplete” para assinaturas que exigem método de pagamento
O período de teste é especificado em dias
A última fatura e intenção de pagamento são expandidas automaticamente

stripe_updateSubscription

Atualiza uma assinatura existente.

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

Cancela uma assinatura.

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 da assinatura (obrigatório)
cancelAtPeriodEnd: Se verdadeiro, cancela no final do período; se falso, cancela imediatamente (padrão: falso)

Notas:

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

Produtos e Preços

stripe_products

Lista produtos com paginação.

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

Cria um novo produto.

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

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

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
productId: Filtrar por ID de produto (opcional)

stripe_createPrice

Cria um novo preço.

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

Notas:

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

Faturas (Invoices)

stripe_invoice

Recupera uma única fatura por 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
      }
    }
  }
}

Notas:

O ID da assinatura é preenchido via expansão de API quando disponível

stripe_invoices

Lista faturas com paginação e filtragem opcional.

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por status (opcional)

stripe_payInvoice

Paga uma fatura programaticamente.

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

Notas:

Tenta pagar a fatura usando o método de pagamento padrão do cliente
Retorna erro se o pagamento falhar
Atualiza o status da fatura para “paid” em caso de sucesso

Reembolsos (Refunds)

stripe_refunds

Lista reembolsos com paginação e filtragem opcional.

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
paymentIntentId: Filtrar por ID de intenção de pagamento (opcional)

stripe_createRefund

Cria um reembolso para uma intenção de 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
  }
}

Notas:

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

Métodos de pagamento (Payment Methods)

stripe_paymentMethods

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

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

Notas:

Apenas informações seguras do cartão são retornadas (últimos 4, marca, validade)
Os números completos dos cartões nunca são expostos

stripe_attachPaymentMethod

Anexa um método de pagamento a um 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
  }
}

Notas:

O método de pagamento deve ser criado primeiro (tipicamente via Stripe.js)
Os métodos de pagamento anexados podem ser usados para assinaturas e pagamentos

stripe_detachPaymentMethod

Separa um método de pagamento de um cliente.

Mutation:

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

Notas:

Os métodos de pagamento separados não podem mais ser usados para pagamentos
Retorna o método de pagamento com customerId definido como nulo

Eventos Webhook

stripe_webhookEvents

Lista eventos de webhook recebidos pelo serviço.

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: Número de itens a retornar (padrão: 10)
after: Cursor para paginação

Notas:

Os eventos são recebidos automaticamente através do endpoint de webhook
Os eventos são armazenados após a verificação de assinatura
O campo data contém a carga útil completa do evento como string JSON

Paginação

Todas as consultas de lista suportam paginação baseada em cursor utilizando o padrão de conexão Relay.

PageInfo

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

Exemplo de uso

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
Use pageInfo.endCursor da resposta como after no próximo pedido
Verifique hasNextPage para determinar se existem mais páginas

Valores padrão:

first: Padrão para 10 se não fornecido
after: Começa do início se não fornecido

Tratamento de erros

Todas as operações retornam erros GraphQL com mensagens amigáveis para o usuário. Os erros são mapeados a partir de erros da API Stripe para fornecer feedback claro.

Cenários de erro comuns

Erro de configuração:

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

Erro de cliente:

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

Erro 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.)

Erro 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: Códigos de erro Stripe comuns são mapeados para mensagens amigáveis:

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

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

Tipos de dados

StripeEnvironment

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

Scalar Map

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

As chaves são strings
Os valores podem ser strings, números, booleanos ou mapas aninhados
Usado para campos de metadados

Exemplo:

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

Scalar Time

O tipo escalar Time representa timestamps com formato ISO 8601.

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