@lmapp/react-native-cloudpayments
Version:
🚀 Мощный SDK для интеграции платежей CloudPayments в React Native. Поддержка Apple Pay, Google Pay, СБП, банковских карт. Полная типизация TypeScript. iOS 12+ и Android 21+
403 lines • 15.7 kB
TypeScript
/**
* @fileoverview Интерфейсы ответов API CloudPayments SDK
* @description Содержит типы данных для ответов от CloudPayments API и внутренних операций SDK
* @author Leonid Molchanov
* @since 1.0.0
*/
import type { IBaseResponseWithTransaction, IBaseError } from './base';
/**
* Информация о транзакции CloudPayments
*
* @description Базовая информация о созданной транзакции в системе CloudPayments.
* Содержит уникальный идентификатор и может быть расширена дополнительными полями.
*
* @example Использование информации о транзакции
* ```typescript
* const handlePaymentSuccess = (transaction: ITransaction) => {
* console.log('Транзакция создана с ID:', transaction.id);
*
* // Сохраняем ID для отслеживания
* await saveTransactionToDatabase({
* transactionId: transaction.id,
* timestamp: new Date(),
* status: 'completed'
* });
* };
* ```
*
* @since 1.0.0
*/
export interface ITransaction {
/**
* Уникальный идентификатор транзакции
* @description Числовой ID транзакции в системе CloudPayments.
* Используется для отслеживания статуса, возвратов и в отчетах.
*/
id: number;
}
/**
* Ответ при создании платежного намерения (Intent)
*
* @description Содержит полную информацию о созданном Intent, включая
* уникальный идентификатор, сумму, статус и URL для оплаты.
* Intent используется для альтернативных способов оплаты.
*
* @example Обработка созданного Intent
* ```typescript
* import { PaymentService } from '@lmapp/react-native-cloudpayments';
*
* const intent = await PaymentService.createIntent(paymentData);
*
* console.log('Intent создан:', intent.id);
* console.log('Сумма:', intent.amount, intent.currency);
* console.log('Статус:', intent.status);
*
* if (intent.paymentUrl) {
* console.log('Ссылка для оплаты:', intent.paymentUrl);
* // Можно открыть в браузере или показать QR-код
* }
*
* if (intent.transaction) {
* console.log('Транзакция:', intent.transaction.id);
* }
* ```
*
* @example Проверка статуса Intent
* ```typescript
* const checkIntentStatus = (intent: IIntentResponse) => {
* switch (intent.status) {
* case 'Created':
* console.log('Intent создан, ожидает оплаты');
* break;
* case 'Succeeded':
* console.log('Оплата успешно завершена');
* break;
* case 'Failed':
* console.log('Оплата отклонена');
* break;
* default:
* console.log('Неизвестный статус:', intent.status);
* }
* };
* ```
*
* @see {@link https://developers.cloudpayments.ru/#intent} Документация по Intent API
* @since 1.0.0
*/
export interface IIntentResponse {
/**
* Уникальный идентификатор Intent
* @description Строковый ID платежного намерения в системе CloudPayments.
* Используется для отслеживания статуса и связи с транзакциями.
* @example 'intent_1234567890abcdef'
*/
id: string;
/**
* Сумма платежа
* @description Сумма в указанной валюте в числовом формате.
* @example 1000.50
*/
amount: number;
/**
* Валюта платежа
* @description Трехбуквенный код валюты по стандарту ISO 4217.
* @example 'RUB'
*/
currency: string;
/**
* Статус платежного намерения
* @description Текущее состояние Intent в процессе оплаты.
* Возможные значения: 'Created', 'Pending', 'Succeeded', 'Failed', 'Cancelled'
* @example 'Created'
*/
status: string;
/**
* Описание платежа (опционально)
* @description Назначение платежа, переданное при создании Intent.
* @example 'Оплата заказа №12345'
*/
description?: string;
/**
* URL для оплаты (опционально)
* @description Ссылка для завершения оплаты через веб-интерфейс
* или для генерации QR-кода. Доступна для некоторых способов оплаты.
* @example 'https://checkout.cloudpayments.ru/pay/intent_123'
*/
paymentUrl?: string;
/**
* Информация о связанной транзакции (опционально)
* @description Данные о транзакции, если она была создана.
* Появляется после успешного завершения платежа.
*/
transaction?: ITransaction;
}
/**
* Ответ API при оплате через Intent с криптограммой
*
* @description Специальный ответ для операций оплаты через Intent
* с использованием криптограммы карты. Содержит HTTP статус код
* и детальную информацию об операции.
*
* @example Обработка ответа API оплаты
* ```typescript
* const apiResponse: IIntentApiPayResponse = await apiPayWithCryptogram(
* paymentData,
* cryptogram,
* intentId
* );
*
* if (apiResponse.statusCode === 200) {
* console.log('Оплата успешна');
* console.log('Intent ID:', apiResponse.response.id);
* console.log('Статус:', apiResponse.response.status);
* } else {
* console.log('Ошибка оплаты, код:', apiResponse.statusCode);
* }
* ```
*
* @since 1.0.0
*/
export interface IIntentApiPayResponse {
/**
* HTTP статус код ответа
* @description Стандартный HTTP код результата операции.
* 200 - успех, 400 - ошибка запроса, 500 - ошибка сервера.
* @example 200
*/
statusCode: number;
/**
* Детальная информация об Intent
* @description Полные данные о платежном намерении после операции оплаты.
*/
response: IIntentResponse;
}
/**
* Информация о банке-эмитенте карты
*
* @description Содержит данные о банке, выпустившем карту,
* включая название и логотип. Получается по BIN номера карты.
*
* @example Отображение информации о банке
* ```typescript
* import { CardService } from '@lmapp/react-native-cloudpayments';
*
* const bankInfo = await CardService.getBankInfo('4111111111111111');
*
* console.log('Банк-эмитент:', bankInfo.bankName);
*
* if (bankInfo.logoUrl) {
* // Показываем логотип банка в UI
* setBankLogo(bankInfo.logoUrl);
* }
* ```
*
* @example Использование в компоненте React Native
* ```typescript
* const [bankInfo, setBankInfo] = useState<IBankInfo | null>(null);
*
* const handleCardInput = async (cardNumber: string) => {
* if (cardNumber.length >= 6) {
* try {
* const info = await CardService.getBankInfo(cardNumber);
* setBankInfo(info);
* } catch (error) {
* setBankInfo(null);
* }
* }
* };
*
* return (
* <View>
* <TextInput onChangeText={handleCardInput} placeholder="Номер карты" />
* {bankInfo && (
* <View style={styles.bankInfo}>
* <Text>{bankInfo.bankName}</Text>
* {bankInfo.logoUrl && (
* <Image source={{ uri: bankInfo.logoUrl }} style={styles.logo} />
* )}
* </View>
* )}
* </View>
* );
* ```
*
* @since 1.0.0
*/
export interface IBankInfo {
/**
* Название банка-эмитента
* @description Полное или сокращенное название банка на русском языке.
* @example 'Сбербанк России', 'Тинькофф Банк', 'ВТБ'
*/
bankName: string;
/**
* URL логотипа банка (опционально)
* @description Ссылка на изображение логотипа банка.
* Может отсутствовать для некоторых банков или при ошибке определения.
* @example 'https://static.cloudpayments.ru/banks/sberbank.png'
*/
logoUrl?: string;
}
/**
* Ответ платежной формы CloudPayments
*
* @description Стандартный ответ от платежной формы, наследующий базовую
* структуру с информацией о транзакции. Используется как основной тип
* для результатов операций платежной формы.
*
* @example Обработка ответа платежной формы
* ```typescript
* import { PaymentService } from '@lmapp/react-native-cloudpayments';
*
* try {
* const result: IPaymentFormResponse = await PaymentService.presentPaymentForm(paymentData);
*
* if (result.success) {
* console.log('Платеж успешен!');
* console.log('Сообщение:', result.message);
*
* if (result.transactionId) {
* console.log('ID транзакции:', result.transactionId);
* // Сохраняем или отправляем на сервер
* await processSuccessfulPayment(result.transactionId);
* }
* } else {
* console.log('Платеж не удался:', result.message);
* }
* } catch (error) {
* console.log('Ошибка при оплате:', error);
* }
* ```
*
* @since 1.0.0
*/
export interface IPaymentFormResponse extends IBaseResponseWithTransaction {
}
/**
* Успешный ответ платежной формы
*
* @description Специализированный тип для гарантированно успешных операций.
* Содержит флаг success: true и обязательную информацию о транзакции.
*
* @example Типизированная обработка успешного платежа
* ```typescript
* const handleSuccessfulPayment = (response: IPaymentFormSuccessResponse) => {
* // TypeScript гарантирует, что success === true
* console.log('Платеж точно успешен');
* console.log('Сообщение:', response.message);
*
* // transactionId может быть undefined, но success точно true
* if (response.transactionId) {
* sendAnalytics('payment_success', {
* transactionId: response.transactionId,
* timestamp: Date.now()
* });
* }
* };
* ```
*
* @since 1.0.0
*/
export interface IPaymentFormSuccessResponse extends IBaseResponseWithTransaction {
/**
* Флаг успешности операции
* @description Всегда true для этого типа ответа.
*/
success: true;
}
/**
* Ошибка платежной формы
*
* @description Специализированный тип для ошибок платежной формы,
* наследующий базовую структуру ошибок с кодом и сообщением.
*
* @example Обработка ошибок платежной формы
* ```typescript
* import { EPaymentFormErrorCode } from '@lmapp/react-native-cloudpayments';
*
* const handlePaymentError = (error: IPaymentFormError) => {
* console.log('Код ошибки:', error.code);
* console.log('Сообщение:', error.message);
*
* switch (error.code) {
* case EPaymentFormErrorCode.PAYMENT_FAILED:
* showUserMessage('Платеж отклонен банком', 'error');
* break;
* case EPaymentFormErrorCode.CONFIGURATION_ERROR:
* showUserMessage('Ошибка настройки приложения', 'error');
* logError('Payment configuration error', error);
* break;
* default:
* showUserMessage('Произошла ошибка при оплате', 'error');
* }
* };
* ```
*
* @since 1.0.0
*/
export interface IPaymentFormError extends IBaseError {
}
/**
* Ответ с публичным ключом для шифрования
*
* @description Содержит публичный ключ CloudPayments в формате PEM
* и его версию. Используется для шифрования данных карты при создании
* криптограммы для безопасной передачи на сервер.
*
* @example Получение и использование публичного ключа
* ```typescript
* import { CardService } from '@lmapp/react-native-cloudpayments';
*
* const publicKey = await CardService.getPublicKey();
*
* console.log('Версия ключа:', publicKey.Version);
* console.log('PEM ключ получен, длина:', publicKey.Pem.length);
*
* // Используем для создания криптограммы
* const cryptogram = await createCardCryptogram({
* cardNumber: '4111111111111111',
* expDate: '12/25',
* cvv: '123'
* }, publicKey.Pem, publicKey.Version);
* ```
*
* @example Кэширование публичного ключа
* ```typescript
* let cachedPublicKey: IPublicKeyResponse | null = null;
* let keyExpirationTime = 0;
*
* const getPublicKey = async (): Promise<IPublicKeyResponse> => {
* const now = Date.now();
*
* // Кэшируем ключ на 1 час
* if (cachedPublicKey && now < keyExpirationTime) {
* return cachedPublicKey;
* }
*
* cachedPublicKey = await CardService.getPublicKey();
* keyExpirationTime = now + 60 * 60 * 1000; // 1 час
*
* return cachedPublicKey;
* };
* ```
*
* @see {@link https://developers.cloudpayments.ru/#kriptogramma-karty} Документация по криптограммам
* @since 1.0.0
*/
export interface IPublicKeyResponse {
/**
* Публичный ключ в формате PEM
* @description RSA публичный ключ для шифрования данных карты.
* Представлен в стандартном формате PEM (Privacy-Enhanced Mail).
* @example '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEF...'
*/
Pem: string;
/**
* Версия публичного ключа
* @description Числовая версия ключа для отслеживания обновлений.
* Увеличивается при ротации ключей CloudPayments.
* @example 1
*/
Version: number;
}
//# sourceMappingURL=responses.d.ts.map