Добавление интеграции Stripe

Stripe — это платформа для онлайн-обработки платежей, разработанная для интернет-бизнеса. Интеграция Stripe позволяет вашему приложению безопасно обрабатывать транзакции, подписки и финансовые данные.

Шаги настройки

После выбора Stripe из списка интеграций появится модальное окно настройки. Вам необходимо предоставить следующие учетные данные из вашей панели управления Stripe для установления соединения:

1. Секретный ключ (Secret Key)

Ввод: Введите ваш приватный Секретный ключ Stripe (обычно начинается с sk_) в поле Secret Key. Этот ключ позволяет бэкенду аутентифицировать безопасные запросы.

2. Публикуемый ключ (Publishable Key)

Ввод: Введите ваш публичный Публикуемый ключ Stripe (обычно начинается с pk_) в поле Publishable Key. Этот ключ используется для реализации фронтенда.

3. Окружение (Environment)

Ввод: Выберите соответствующий контекст окружения из выпадающего меню (например, Test для режима разработки/песочницы или Production для реальной обработки).

Завершение подключения

Как только ключи и окружение настроены:

Проверьте строку состояния (в настоящее время отображается Not Connected).
Нажмите черную кнопку Add в правом нижнем углу, чтобы сохранить учетные данные и включить платежную интеграцию.

Настройка Stripe

Интеграция Stripe

Справочник API интеграции Stripe

Управление конфигурацией

configureStripe

Создает новую конфигурацию Stripe для проекта и окружения.

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_..."
  }
}

Примечания:

Секретный ключ шифруется с помощью AES-256-GCM перед сохранением
Только одна конфигурация на комбинацию проект/окружение
Возвращает ошибку, если конфигурация уже существует

updateStripeConfig

Обновляет существующую конфигурацию Stripe.

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

Примечания:

Все поля являются необязательными
Обновляются только предоставленные поля
Секретный ключ шифруется, если предоставлен

Управление клиентами (Customer Management)

stripe_customer

Получает одного клиента по ID.

Query:

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

stripe_customers

Перечисляет клиентов с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
customerId: Фильтр по ID клиента (необязательно)

stripe_createCustomer

Создает нового клиента.

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

Обновляет существующего клиента.

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

Примечания:

Все поля являются необязательными
Обновляются только предоставленные поля

stripe_deleteCustomer

Удаляет клиента.

Mutation:

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

Response:

Возвращает true при успехе
Возвращает ошибку, если клиент не найден

Намерения платежа (Payment Intents)

stripe_paymentIntent

Получает одно намерение платежа по ID.

Query:

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

stripe_paymentIntents

Перечисляет намерения платежа с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
customerId: Фильтр по ID клиента (необязательно)

stripe_createPaymentIntent

Создает новое намерение платежа.

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

Примечания:

clientSecret возвращается для подтверждения на фронтенде
Используйте automaticPaymentMethods: true для интеграции со Stripe.js

stripe_updatePaymentIntent

Обновляет намерение платежа перед подтверждением.

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

Примечания:

Может обновляться только перед подтверждением
Все поля являются необязательными

stripe_confirmPaymentIntent

Подтверждает намерение платежа.

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

Примечания:

Требуется для завершения платежа
Может потребоваться аутентификация 3D Secure
Возвращает обновленный статус (succeeded, requires_action и т.д.)

stripe_cancelPaymentIntent

Отменяет намерение платежа.

Mutation:

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

Примечания:

Можно отменить только те намерения платежа, которые не были успешными или уже отмененными
Статус меняется на “canceled”

Подписки (Subscriptions)

stripe_subscription

Получает одну подписку по 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

Перечисляет подписки с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
customerId: Фильтр по ID клиента (необязательно)
status: Фильтр по статусу (необязательно)

stripe_createSubscription

Создает новую подписку.

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

Примечания:

paymentBehavior может быть “default_incomplete” для подписок, требующих метода оплаты
Пробный период указывается в днях
Последний счет и намерение платежа разворачиваются автоматически

stripe_updateSubscription

Обновляет существующую подписку.

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

Отменяет подписку.

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 подписки (обязательно)
cancelAtPeriodEnd: Если true, отменяет в конце периода; если false, отменяет немедленно (по умолчанию: false)

Примечания:

Немедленная отмена: подписка заканчивается сейчас
Отмена в конце периода: подписка продолжается до конца текущего периода

Продукты и цены (Products and Prices)

stripe_products

Перечисляет продукты с пагинацией.

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

Создает новый продукт.

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

Перечисляет цены с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
productId: Фильтр по ID продукта (необязательно)

stripe_createPrice

Создает новую цену.

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

Примечания:

Опустите recurring для разовых цен
interval должен быть одним из: “day”, “week”, “month”, “year”

Счета (Invoices)

stripe_invoice

Получает один счет по 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
      }
    }
  }
}

Примечания:

ID подписки заполняется через расширение API, когда доступно

stripe_invoices

Перечисляет счета с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
customerId: Фильтр по ID клиента (необязательно)
status: Фильтр по статусу (необязательно)

stripe_payInvoice

Оплачивает счет программно.

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

Примечания:

Пытается оплатить счет, используя метод оплаты клиента по умолчанию
Возвращает ошибку, если оплата не удалась
Обновляет статус счета на “paid” при успехе

Возвраты (Refunds)

stripe_refunds

Перечисляет возвраты с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
paymentIntentId: Фильтр по ID намерения платежа (необязательно)

stripe_createRefund

Создает возврат для намерения платежа.

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

Примечания:

Опустите amount для полного возврата
reason может быть: “duplicate”, “fraudulent”, “requested_by_customer”
Статус возврата начинается как “pending” и обновляется до “succeeded” или “failed”

Методы оплаты (Payment Methods)

stripe_paymentMethods

Перечисляет методы оплаты с пагинацией и опциональной фильтрацией.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации
customerId: Фильтр по ID клиента (необязательно)

Примечания:

Возвращается только безопасная информация о карте (последние 4 цифры, бренд, срок действия)
Полные номера карт никогда не раскрываются

stripe_attachPaymentMethod

Прикрепляет метод оплаты к клиенту.

Mutation:

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

Примечания:

Метод оплаты должен быть создан первым (обычно через Stripe.js)
Прикрепленные методы оплаты могут использоваться для подписок и платежей

stripe_detachPaymentMethod

Открепляет метод оплаты от клиента.

Mutation:

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

Примечания:

Открепленные методы оплаты больше не могут использоваться для платежей
Возвращает метод оплаты с customerId установленным в null

Вебхук события (Webhook Events)

stripe_webhookEvents

Перечисляет события вебхука, полученные сервисом.

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: Количество возвращаемых элементов (по умолчанию: 10)
after: Курсор для пагинации

Примечания:

События принимаются автоматически через конечную точку вебхука
События сохраняются после проверки подписи
Поле data содержит полную полезную нагрузку события в виде JSON-строки

Пагинация

Все списочные запросы поддерживают курсорную пагинацию, используя шаблон подключения Relay.

PageInfo

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

Пример использования

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

Поток пагинации:

Начальный запрос: first: 10, after: null
Используйте pageInfo.endCursor из ответа как after в следующем запросе
Проверьте hasNextPage, чтобы определить, есть ли еще страницы

Значения по умолчанию:

first: По умолчанию 10, если не предоставлено
after: Начинается с начала, если не предоставлено

Обработка ошибок

Все операции возвращают ошибки GraphQL с удобными для пользователя сообщениями. Ошибки сопоставляются с ошибками Stripe API для обеспечения четкой обратной связи.

Распространенные сценарии ошибок

Ошибки конфигурации:

400: Неверный формат ключа Stripe
404: Проект или конфигурация не найдены
400: Конфигурация уже существует

Ошибки клиента:

404: Клиент не найден
400: Неверные данные клиента

Ошибки намерения платежа:

404: Намерение платежа не найдено
400: Неверная сумма или валюта
402: Платеж не удался (карта отклонена, недостаточно средств и т.д.)

Ошибки подписки:

404: Подписка не найдена
400: Неверные параметры подписки
400: Невозможно обновить отмененную подписку

Коды ошибок Stripe: Распространенные коды ошибок Stripe сопоставляются с удобными сообщениями:

card_declined: “Ваша карта была отклонена”
insufficient_funds: “Недостаточно средств”
invalid_number: “Неверный номер карты”
expired_card: “Срок действия карты истек”
incorrect_cvc: “Неверный код CVC”

Формат ответа об ошибке

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

Типы данных

StripeEnvironment

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

Scalar Map

Скалярный тип Map представляет собой сопоставление ключ-значение, где:

Ключи являются строками
Значения могут быть строками, числами, логическими значениями или вложенными картами
Используется для полей метаданных

Пример:

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

Scalar Time

Скалярный тип Time представляет временные метки в формате ISO 8601.

Пример: "2025-11-16T00:28:48.081Z"