Интеграция IZI с CloudPayments

Интеграция IZI с CloudPayments

CloudPayments — один из поддерживаемых платёжных шлюзов в IZI. После подключения клиенты клуба могут пополнять баланс картой, через Apple Pay или Google Pay прямо из CRM или мобильного приложения — без перехода на сторонние страницы.

Что нужно перед началом

• Аккаунт мерчанта в CloudPayments (с пройденным KYC)
• Public ID и API Secret из личного кабинета CloudPayments
• Токен IZI API с ролью OWNER или ADMIN на уровне организации

Шаг 1 — Настройка в IZI API

mutation ConfigurePaymentGateway($input: PaymentGatewayInput!) {
  configurePaymentGateway(input: $input) {
    id
    type
    isActive
    publicId
  }
}

{
  "input": {
    "organizationId": "org_abc123",
    "type": "CLOUDPAYMENTS",
    "publicId": "pk_your_public_id",
    "apiSecret": "your_api_secret",
    "description": "Основной эквайринг"
  }
}

apiSecret хранится зашифрованным, в ответе не возвращается. Для его обновления нужно вызвать мутацию повторно.

Шаг 2 — Webhook от CloudPayments

В личном кабинете CloudPayments: Настройки → Уведомления → Check (проверка платежа) и Pay (успешный платёж).

URL для обоих типов:

https://api.izi.is/payments/cloudpayments/callback

IZI принимает Check и Pay уведомления. При Check валидирует сумму и существование клиента. При Pay зачисляет баланс и создаёт транзакцию.

Шаг 3 — Инициировать платёж через API

Для пополнения баланса клиента через виджет:

mutation InitiateTopUp($input: InitiatePaymentInput!) {
  initiateTopUpPayment(input: $input) {
    paymentUrl
    transactionId
    expiresAt
  }
}

{
  "input": {
    "clientId": "client_xyz",
    "clubId": "club_abc123",
    "amount": 500,
    "returnUrl": "https://yourapp.example.com/payment/success",
    "description": "Пополнение баланса"
  }
}

В ответе — paymentUrl для редиректа клиента. После оплаты CloudPayments отправит уведомление на IZI, баланс зачислится автоматически.

Шаг 4 — Тестирование

CloudPayments предоставляет тестовые карты:

Карта	Результат
4111 1111 1111 1111	Успешная оплата
4444 4444 4444 4441	Отказ банка
5500 0000 0000 0004	3DS-подтверждение

Тестовый режим включается в панели CloudPayments. Все транзакции в тестовом режиме не списывают реальные деньги, но проходят полный цикл через IZI включая зачисление баланса в тестовый профиль клиента.

Отслеживание статуса платежа

query PaymentStatus($transactionId: ID!) {
  payment(id: $transactionId) {
    id
    status
    amount
    clientId
    createdAt
    confirmedAt
    gatewayTransactionId
  }
}

Статусы: PENDING → AUTHORIZED → CONFIRMED | CANCELLED | FAILED.

Или через webhook от IZI — подпишитесь на PAYMENT_RECEIVED:

mutation CreatePaymentWebhook {
  createWebhook(input: {
    url: "https://your-service.example.com/payments",
    events: ["PAYMENT_RECEIVED", "PAYMENT_FAILED"]
  }) {
    id
    secret
  }
}

Возврат платежа

mutation RefundPayment($input: RefundInput!) {
  refundPayment(input: $input) {
    success
    refundId
    amount
  }
}

{
  "input": {
    "transactionId": "txn_abc123",
    "amount": 500,
    "reason": "Запрос клиента"
  }
}

Частичные возвраты поддерживаются. amount не может превышать сумму исходной транзакции.

Связанные страницы

• Авторизация и токены — токен для вызова мутаций
• Webhooks — события PAYMENT_RECEIVED
• Коды ошибок API — ошибки платёжных операций
• Примеры SDK — готовые обёртки для платёжных операций

См. также

• IZI API: обзор для разработчиков
• Интеграция IZI с кассой: ОФД и фискальный регистратор
• Подключение CloudPayments к IZI CRM
• Проблемы с эквайрингом CloudPayments
• Авторизация и токены IZI API