Stripe

O Stripe é uma plataforma de processamento de pagamentos online destinada a negócios na internet. Integrar o Stripe permite que a sua aplicação trate transações, subscrições e dados financeiros de forma segura.

Passos de configuração

Depois de selecionar Stripe na lista de integrações, será apresentada uma janela de configuração. Deve indicar as seguintes credenciais a partir do painel do Stripe para estabelecer a ligação:

1. Chave secreta

Entrada: Introduza a sua chave secreta privada do Stripe (normalmente começa por sk_) no campo Secret Key. Esta chave permite ao backend autenticar pedidos seguros.

2. Chave pública

Entrada: Introduza a sua chave pública do Stripe (normalmente começa por pk_) no campo Publishable Key. Esta chave é utilizada na implementação do frontend.

3. Ambiente

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

Concluir a ligação

Quando as chaves e o ambiente estiverem configurados:

Consulte a barra de estado (mostrará Não ligado).
Clique no botão preto Adicionar no canto inferior direito para guardar 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
Subscrições
Produtos e preços
Faturas
Reembolsos
Sessões de Checkout
Sessões do portal de faturação
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 é encriptada com AES-256-GCM antes de ser armazenada
Só uma configuração por combinação projeto/ambiente
Devolve 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 é encriptada 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 devolver (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:

Devolve true em caso de sucesso
Devolve 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 devolver (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:

É devolvido 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
Devolve 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”

Subscrições {#subscriptions}

stripe_subscription {#stripe_subscription}

Obtém uma única subscrição 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 subscrições 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 devolver (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 subscrição.

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 subscrições 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 subscrição 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 subscrição.

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 subscrição (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 subscrição termina agora
Cancelamento no fim do período: a subscrição continua até ao 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 devolver (predefinição: 10)
after: Cursor para paginação
productId: Filtrar por ID de 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 subscrição é 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 devolver (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
Devolve 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 devolver (predefinição: 10)
after: Cursor para paginação
paymentIntentId: Filtrar por ID de 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 subscrições. Devolve um URL que redireciona os clientes para a página de pagamento alojada 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 subscrição (subscrições)
  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/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 — Subscrição:

{
  "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 o URL de redirecionamento para onde os clientes devem ser enviados
Para pagamentos únicos, utilize mode: "payment" e forneça priceId ou amount + currency
Para subscrições, 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 faturação {#billing-portal-sessions}

stripe_createBillingPortalSession {#stripe_createbillingportalsession}

Cria uma sessão do portal de faturação Stripe para os clientes gerirem subscrições, métodos de pagamento e informação de faturação no portal alojado 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/hora de criação
}

Exemplo:

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

Notas:

O campo url contém o URL de redirecionamento para onde os clientes devem ser enviados
A sessão do portal é de curta duração e expira após a utilização
Os clientes podem gerir subscrições, atualizar métodos de pagamento, ver faturas e atualizar dados de faturação
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 subscrições 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 devolver (predefinição: 10)
after: Cursor para paginação
customerId: Filtrar por ID de cliente (opcional)

Notas:

Só é devolvida informação segura do cartão (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 subscrições 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
Devolve 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 devolver (predefiniçã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 ligação Relay.

PageInfo {#pageinfo}

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

Exemplo de utilização {#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 devolvem erros GraphQL com mensagens claras para o utilizador. 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 subscrição:

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

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

card_declined: “O 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"