Stripe

Stripe es una plataforma de procesamiento de pagos en línea para negocios en internet. Integrar Stripe permite que su aplicación gestione transacciones, suscripciones y datos financieros de forma segura.

Pasos de configuración

Tras seleccionar Stripe en la lista de integraciones, aparecerá un modal de configuración. Debe proporcionar las siguientes credenciales desde su panel de Stripe para establecer la conexión:

1. Clave secreta

Entrada: Introduzca su Secret Key privada de Stripe (normalmente comienza por sk_) en el campo Secret Key. Esta clave permite al backend autenticar solicitudes seguras.

2. Clave publicable

Entrada: Introduzca su Publishable Key pública de Stripe (normalmente comienza por pk_) en el campo Publishable Key. Esta clave se usa en el frontend.

3. Entorno

Entrada: Seleccione el entorno adecuado en el menú desplegable (por ejemplo, Test para desarrollo/sandbox o Production para procesamiento en vivo).

Finalizar la conexión

Una vez configuradas las claves y el entorno:

Revise la barra de estado (actualmente Not Connected).
Pulse el botón negro Add abajo a la derecha para guardar las credenciales y activar la integración de pagos.

Configuración de la integración con Stripe

Referencia de la API de integración de Stripe

Gestión de configuración
Gestión de clientes
Intenciones de pago
Suscripciones
Productos y precios
Facturas
Reembolsos
Sesiones de Checkout
Sesiones del portal de facturación
Métodos de pago
Eventos de webhook
Paginación
Manejo de errores

Configuration Management

configureStripe

Crea una nueva configuración de Stripe para el proyecto y el entorno.

Mutación:

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

Entrada:

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

Respuesta:

type ConfigureStripePayload {
  id: ID!                    # Configuration ID
  publishableKey: String!    # Publishable key
  webhookUrl: String!        # Generated webhook URL
}

Ejemplo:

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

Notas:

La clave secreta se cifra con AES-256-GCM antes de almacenarse
Solo una configuración por combinación proyecto/entorno
Devuelve error si la configuración ya existe

updateStripeConfig

Actualiza una configuración de Stripe existente.

Mutación:

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

Entrada:

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

Respuesta:

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

Notas:

Todos los campos son opcionales
Solo se actualizan los campos enviados
La clave secreta se cifra si se envía

Customer Management

stripe_customer

Obtiene un cliente por su ID.

Consulta:

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

stripe_customers

Lista clientes con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
customerId: Filtrar por ID de cliente (opcional)

stripe_createCustomer

Crea un cliente nuevo.

Mutación:

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

Actualiza un cliente existente.

Mutación:

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 los campos son opcionales
Solo se actualizan los campos enviados

stripe_deleteCustomer

Elimina un cliente.

Mutación:

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

Respuesta:

Devuelve true si tiene éxito
Devuelve error si no se encuentra el cliente

Payment Intents

stripe_paymentIntent

Obtiene una intención de pago por su ID.

Consulta:

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

stripe_paymentIntents

Lista intenciones de pago con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
customerId: Filtrar por ID de cliente (opcional)

stripe_createPaymentIntent

Crea una nueva intención de pago.

Mutación:

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:

Se devuelve clientSecret para la confirmación en el frontend
Use automaticPaymentMethods: true para la integración con Stripe.js

stripe_updatePaymentIntent

Actualiza una intención de pago antes de confirmarla.

Mutación:

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:

Solo puede actualizarse antes de la confirmación
Todos los campos son opcionales

stripe_confirmPaymentIntent

Confirma una intención de pago.

Mutación:

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:

Necesario para completar el pago
Puede requerir autenticación 3D Secure
Devuelve el estado actualizado (succeeded, requires_action, etc.)

stripe_cancelPaymentIntent

Cancela una intención de pago.

Mutación:

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

Notas:

Solo puede cancelar intenciones de pago que no estén succeeded ni canceled
El estado pasa a “canceled”

Subscriptions

stripe_subscription

Obtiene una suscripción por su 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

Lista suscripciones con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por estado (opcional)

stripe_createSubscription

Crea una nueva suscripción.

Mutación:

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 puede ser “default_incomplete” si la suscripción requiere método de pago
El periodo de prueba se indica en días
La última factura y la intención de pago se expanden automáticamente

stripe_updateSubscription

Actualiza una suscripción existente.

Mutación:

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 una suscripción.

Mutación:

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 de suscripción (obligatorio)
cancelAtPeriodEnd: Si es true, cancela al final del periodo; si es false, cancela al instante (por defecto: false)

Notas:

Cancelación inmediata: la suscripción termina ahora
Cancelación al final del periodo: la suscripción sigue hasta el final del periodo actual

Products and Prices

stripe_products

Lista productos con paginación.

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

Crea un producto nuevo.

Mutación:

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 precios con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
productId: Filtrar por ID de producto (opcional)

stripe_createPrice

Crea un precio nuevo.

Mutación:

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 precios de un solo pago
interval debe ser uno de: “day”, “week”, “month”, “year”

Invoices

stripe_invoice

Obtiene una factura por su 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:

El ID de suscripción se rellena mediante expansión de la API cuando está disponible

stripe_invoices

Lista facturas con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
customerId: Filtrar por ID de cliente (opcional)
status: Filtrar por estado (opcional)

stripe_payInvoice

Paga una factura de forma programática.

Mutación:

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:

Intenta pagar la factura con el método de pago predeterminado del cliente
Devuelve error si el pago falla
Actualiza el estado de la factura a “paid” si tiene éxito

Refunds

stripe_refunds

Lista reembolsos con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
paymentIntentId: Filtrar por ID de intención de pago (opcional)

stripe_createRefund

Crea un reembolso para una intención de pago.

Mutación:

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 puede ser: “duplicate”, “fraudulent”, “requested_by_customer”
El estado del reembolso comienza en “pending” y pasa a “succeeded” o “failed”

Checkout Sessions

stripe_createCheckoutSession

Crea una sesión de Stripe Checkout para pagos únicos o suscripciones. Devuelve una URL que redirige al cliente a la página de pago alojada por Stripe.

Mutación:

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              # Existing Stripe customer ID (optional)
  customerEmail: String            # Customer email for new customers (optional)
  mode: String!                   # "payment" for one-time or "subscription" for recurring
  successUrl: String!             # URL to redirect after successful payment
  cancelUrl: String!              # URL to redirect if customer cancels
  lineItems: [StripeCheckoutSessionLineItemInput!]!  # Items to purchase
  paymentMethodTypes: [String!]    # Allowed payment methods (optional)
  metadata: Map                    # Custom metadata (optional)
}

input StripeCheckoutSessionLineItemInput {
  priceId: String      # Stripe Price ID (for existing prices)
  quantity: Int!        # Quantity of items
  amount: Float         # Custom amount in dollars (for one-time payments)
  currency: String      # Currency code (required if amount is provided)
}

Respuesta:

type StripeCheckoutSession {
  id: ID!                    # Session ID
  object: String!            # "checkout.session"
  url: String!              # Redirect URL for customer
  customerId: String        # Customer ID (if customer exists)
  customerEmail: String     # Customer email
  paymentIntentId: String   # Payment Intent ID (for one-time payments)
  subscriptionId: String    # ID de suscripción (suscripciones)
  mode: String!             # "payment" or "subscription"
  status: String!            # Session status
  currency: String          # Currency code
  amountTotal: Float        # Total amount in dollars
  metadata: Map             # Custom metadata
  createdAt: Time!          # Creation timestamp
}

Ejemplo – pago único:

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

Ejemplo – pago único con importe 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
      }
    ]
  }
}

Ejemplo – suscripción:

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

Notas:

El campo url contiene la URL de redirección a la que debe enviarse al cliente
Para pagos únicos, use mode: "payment" e indique priceId o amount + currency
Para suscripciones, use mode: "subscription" e indique priceId (debe ser un precio recurrente)
Debe indicarse customerId o customerEmail, pero no ambos
paymentMethodTypes puede incluir: “card”, “us_bank_account”, “link”, etc.
Las sesiones caducan a las 24 horas si no se completan

Billing Portal Sessions

stripe_createBillingPortalSession

Crea una sesión del portal de facturación de Stripe para que los clientes gestionen suscripciones, métodos de pago y datos de facturación en el portal alojado por Stripe.

Mutación:

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

Entrada:

input StripeCreateBillingPortalSessionInput {
  customerId: String!      # Stripe customer ID (required)
  returnUrl: String!       # URL to redirect after customer exits portal
  configuration: String    # Portal configuration ID (optional)
}

Respuesta:

type StripeBillingPortalSession {
  id: ID!            # Session ID
  object: String!    # "billing_portal.session"
  url: String!       # Redirect URL for customer
  customerId: String!  # Customer ID
  returnUrl: String   # Return URL
  createdAt: Time!   # Creation timestamp
}

Ejemplo:

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

Notas:

El campo url contiene la URL de redirección a la que debe enviarse al cliente
La sesión del portal es de corta duración y caduca tras usarse
Los clientes pueden gestionar suscripciones, métodos de pago, facturas y datos de facturación
Las funciones del portal se configuran en el panel de Stripe
Si no se proporciona configuration, se usa la configuración predeterminada del portal
El portal solo muestra suscripciones y facturas del cliente indicado

Payment Methods

stripe_paymentMethods

Lista métodos de pago con paginación y filtrado 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 elementos a devolver (por defecto: 10)
after: Cursor para la paginación
customerId: Filtrar por ID de cliente (opcional)

Notas:

Solo se devuelve información segura de la tarjeta (last4, marca, caducidad)
Nunca se exponen los números completos de tarjeta

stripe_attachPaymentMethod

Asocia un método de pago a un cliente.

Mutación:

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

Notas:

El método de pago debe crearse antes (normalmente con Stripe.js)
Los métodos asociados sirven para suscripciones y pagos

stripe_detachPaymentMethod

Desasocia un método de pago de un cliente.

Mutación:

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

Notas:

Los métodos desasociados ya no pueden usarse para pagos
Devuelve el método de pago con customerId en null

Webhook Events

stripe_webhookEvents

Lista los eventos de webhook recibidos por el servicio.

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

Respuesta:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Event type (e.g., "payment_intent.succeeded")
  data: String!              # JSON string of event data
  processed: Boolean!        # Si el evento ya fue procesado
  createdAt: Time!
}

Parámetros:

first: Número de elementos a devolver (por defecto: 10)
after: Cursor para la paginación

Notas:

Los eventos se reciben automáticamente en el endpoint de webhook
Los eventos se almacenan tras verificar la firma
El campo data contiene el payload completo del evento como cadena JSON

Pagination

Todas las consultas de listado admiten paginación basada en cursor con el patrón de conexión Relay.

PageInfo

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

Ejemplo de uso

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

Flujo de paginación:

Solicitud inicial: first: 10, after: null
Use pageInfo.endCursor de la respuesta como after en la siguiente solicitud
Compruebe hasNextPage para saber si hay más páginas

Valores predeterminados:

first: 10 si no se indica
after: comienza desde el inicio si no se indica

Error Handling

Todas las operaciones devuelven errores GraphQL con mensajes claros. Los errores se mapean desde la API de Stripe para ofrecer información comprensible.

Escenarios de error frecuentes

Errores de configuración:

400: Formato de claves de Stripe no válido
404: Proyecto o configuración no encontrada
400: La configuración ya existe

Errores de cliente:

404: Cliente no encontrado
400: Datos de cliente no válidos

Errores de intención de pago:

404: Intención de pago no encontrada
400: Importe o divisa no válidos
402: Pago fallido (tarjeta rechazada, fondos insuficientes, etc.)

Errores de suscripción:

404: Suscripción no encontrada
400: Parámetros de suscripción no válidos
400: No se puede actualizar una suscripción cancelada

Códigos de error de Stripe: Los códigos habituales se mapean a mensajes claros:

card_declined: “Su tarjeta fue rechazada”
insufficient_funds: “Fondos insuficientes”
invalid_number: “Número de tarjeta no válido”
expired_card: “La tarjeta ha caducado”
incorrect_cvc: “Código CVC incorrecto”

Formato de respuesta de error

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

Data Types

StripeEnvironment

enum StripeEnvironment {
  TEST  # Modo prueba
  LIVE  # Modo en vivo / producción
}

Escalar Map

El tipo escalar Map representa un mapa clave-valor donde:

Las claves son cadenas
Los valores pueden ser cadenas, números, booleanos o mapas anidados
Se usa en campos de metadatos

Ejemplo:

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

Time Scalar

El tipo escalar Time representa marcas de tiempo en formato ISO 8601.

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