# Zetplat API — Full Documentation ## Быстрый старт - [Быстрый старт](https://docs.zetplat.com/starting): Начало работы: получение ключей, тестовые транзакции, запуск в продакшн. Чтобы начать пользоваться нашим API, выполните следующие шаги: 1. Свяжитесь с нами на [сайте Zetplat](https://www.zetplat.com). 2. Поговорите с вашим менеджером в Zetplat. - Выпустите [открытый и секретный ключи](/api-rules/signature) и обменяйтесь открытыми ключами. - Предоставьте менеджеру Zetplat IP-адрес сервера, с которого будут направляться запросы. В случае изменения IP-адреса на вашей стороне, сообщите об этом вашему менеджеру заранее, чтобы избежать возможных сетевых ошибок. - Сообщите менеджеру Zetplat адрес в вашей системе, на который вы будете, если хотите, получать [вебхуки](/spec/webhooks) (уведомления о событиях — например, об успешных платежах и выплатах). - Получите идентификатор вашего проекта. 3. Проведите [тестовые транзакции](/api-rules/testing) (без реальных данных). 4. Заключите договор с Zetplat. 5. Обменяйтесь данными для реальных операций и проверьте, что все операции проходят. - Для выплат, пополните ваш баланс. - Сервер для реальных транзакций: **api.zetplat.com** 6. Договоритесь о дате старта и начинайте зарабатывать с нами. --- ## Как подписать запрос - [Как подписать запрос](https://docs.zetplat.com/api-rules/signature): Формирование RSA-подписи с алгоритмом SHA-256 для аутентификации запросов и проверка входящих вебхуков. Все запросы к Zetplat должны быть подписаны. В заголовках запросов необходимо передавать данные для идентификации: идентификатор вашего проекта и подпись запроса. | Название | Обязательность | Тип | Описание | |--------------------|----------------|--------|-------------------------------------------------| | `X-Project-Id` | + | string | Идентификатор проекта. Выдается менеджером Zetplat | | `X-Signature` | + | string | [Подпись запроса](#signature) | | `X-Submerchant-Id` | - | string | Идентификатор плательщика (юридического лица) | #### Пример запроса с аутентификацией ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // тело запроса }' ``` ### Подпись запросов Подпись нужна для проверки подлинности (запрос действительно пришел от отправителя) и целостности (данные не были изменены при передаче). Принцип двусторонней проверки: - Zetplat проверяет, что запросы к нам пришли именно от вас и дошли без изменений. - Вы точно так же проверяете уведомления, которые приходят от Zetplat. Для формирования и проверки подписи используется пара ключей: публичный (открытый) и секретный (приватный). #### Генерация ключевой пары Вы самостоятельно генерируете ключевую пару на своей стороне. Алгоритм подписи — RSA. >Свой публичный ключ вы передаете Zetplat (чтобы мы могли проверять ваши запросы), а секретный ключ храните у себя и никому не передаете. #### Формирование подписи тела запроса Каждый запрос к Zetplat должен сопровождаться подписью. Что именно подписывать: тело запроса целиком, в том виде, в котором оно отправляется на сервер (после сериализации в JSON). Алгоритм: SHA-256. Формат подписи: Base64. Чем подписывать: вашим секретным ключом. #### Проверка входящих запросов от Zetplat Все запросы, которые Zetplat отправляет вам (например, уведомления), подписываются на нашей стороне с использованием нашего секретного ключа. Для проверки подлинности запросов от Zetplat используйте наш [публичный ключ](#publicKeys). Проверяйте подпись каждого входящего запроса с алгоритмом SHA‑256 — подпись передаётся в формате Base64. Любой запрос, не прошедший проверку подписи, должен отвергаться как недостоверный. ### Публичные ключи Zetplat - [Для реальных операций](/assets/zetplat_prod_public.pem) - [Для тестирования](/assets/zetplat_demo_public.pem) ### Примеры генерации и проверки подписи ```openssl showLineNumbers # Генерация приватного ключа $ openssl genrsa -out private.pem 2048 # Генерация публичного ключа из приватного $ openssl rsa -in private.pem -pubout > public.pem # Формирование содержимого файла myfile.txt $ echo test > myfile.txt # Генерация подписи $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Готовая подпись для передачи $ base64 sha256.sign # Проверка подписи $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Получение указателя на приватный и публичный ключи $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Генерация подписи по данным с использованием приватного ключа openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Для передачи подпись кодируем в формат Base64 $base64Signature = base64_encode($signature); //При получении подписи декодируем ее обратно из Base64 $decodedSignature = base64_decode($base64Signature); //Проверяем полученную подпись с использованием публичного ключа (1 - успех) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` --- ## Как послать запрос - [Как послать запрос](https://docs.zetplat.com/api-rules/request): Формат запросов и ответов API, URL для тестовой и реальной среды, обработка ошибок. Все операции в API проходят в рамках [платежной сессии](/spec/objects#payment_session). Одна платежная сессия может объединять несколько операций, например, платеж и возврат. Каждый запрос должен быть [подписан](/api-rules/signature). ## Адрес для отправки запросов ` + /api/v1 + ` Например: `https://api-demo.zetplat.com/api/v1/transaction/init/transfer` #### Адрес сервера - Для тестирования `https://api-demo.zetplat.com` - Для реальных операций `https://api.zetplat.com` --- ## Как тестировать - [Как тестировать](https://docs.zetplat.com/api-rules/testing): Проведение тестовых транзакций с тестовыми картами и сценариями. Перед тем, как проводить операции с настоящими деньгами, нужно всё проверить на тестовой среде. [Подпись](/api-rules/signature) и [отправка](/api-rules/request) запросов такая же, как при работе с реальными данными. Отличаются только адрес сервера (`https://api-demo.zetplat.com`), на который нужно отправлять запросы, и [публичный ключ Zetplat](/assets/zetplat_demo_public.pem). ## Данные для тестовых операций ### Банковские карты > При тестировании используйте хотя бы одну карту с 3D Secure и хотя бы одну — без 3D Secure #### С 3D Secure - 4100000000000004 - 5510000000000003 >Чтобы успешно пройти процедуру 3D Secure, используйте код `12345`. >Чтобы завершить процедуру неуспехом, используйте любое другое значение. #### Без 3D Secure - 4200000000000002 - 5520000000000002 ## Тестирование неуспешных операций По умолчанию все операции завершаются успешно. Чтобы протестировать неуспешный сценарий, передайте в запросе объект `user_info`, в поле `customer.reference` одно из следующих значений. | Значение | Результат | |----------|--------------------------------------------------------------------------------------------------------------| | `thief` | Только для платежей. Платеж отменится на этапе холдирования | | `loser` | Для платежей и выплат. Платеж отменится на этапе списания захолдированных средств, выплата пройдет с ошибкой | --- ## Идемпотентность - [Идемпотентность](https://docs.zetplat.com/api-rules/idempotency): Обеспечение идемпотентности запросов для безопасных повторных отправок. Ключ идемпотентности - это уникальный идентификатор операции. Вы можете его самостоятельно генерировать и использовать, когда есть необходимость запретить повторное выполнение той же операции до её завершения. Например, чтобы не сделать двойную выплату или списание. Срок действия ключа составляет 24 часа. ### Формат Идентификатор ключа идемпотентности указывается в заголовке запроса. | Название | Обязательность | Тип | Описание | | --------------------------- | -------------- | ------ | ----------------------------------------------- | | `X-PARTNER-IDEMPOTENCY-KEY` | - | string | Ключ идемпотентности. Формат: от 4 до 64 знаков | #### Пример запроса с ключом идемпотентности ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \ -d '{ // тело запроса }' ``` ### Список методов с поддержкой ключа идемпотентности - [`transaction/initiate`](/spec/methods#transactioninitiate) - [`transaction/init/transfer`](/spec/methods#transactioninittransfer) - [`transaction/start/transfer`](/spec/methods#transactionstartcheckout) - [`transaction/init/checkout`](/spec/methods#transactioninitcheckout) - [`transaction/start/checkout`](/spec/methods#transactionstartcheckout) - [`transaction/approve`](/spec/methods#transactionapprove) - [`transaction/finalize`](/spec/methods#transactionfinalize) - [`transaction/cancel`](/spec/methods#transactioncancel) - [`transaction/refund`](/spec/methods#transactionrefund) ### Список возможных ошибок - `idempotency_key_params_mismatch` — Ключ уже был использован ранее для другой сессии. - `idempotency_key_already_exists` — Предыдущий запрос с таким же ключом еще не обработан. - `idempotency_key_not_supported` — Метод не поддерживает использование ключа идемпотентности. --- ## Обзор выплат - [Обзор выплат](https://docs.zetplat.com/transfers/payouts-intro): Как проводить выплаты физическим лицам на карты Visa/MasterCard и через СБП. API позволяет проводить выплаты удобно и безопасно. Можно отправлять выплаты любым физическим лицам на [банковские карты Visa и MasterCard](/transfers/payout-pcidss). ### Как получать данные карт для выплат Вы можете узнать данные карты получателя одним из трех способов в зависимости от вашей модели безопасности и интеграции. #### Наш виджет Встройте на сайт наш виджет, чтобы получатель мог сам ввести номер карты, а виджет вернул вам токен для выплаты — для этого способа достаточно соблюдать требования PCI DSS, предъявляемые к работе с виджетом. > [Как провести выплату на карту с виджетом](/transfers/payout-widget) #### Самостоятельный сбор данных Вы можете собирать номера карт на своей стороне и передавать их напрямую в запросе на выплату. Для этого способа нужно выполнять требования стандарта PCI DSS. > [Как провести выплату на карту](/transfers/payout-pcidss) #### Выплата по существующему токену Если у вас уже есть один из токенов, используйте его вместо номера карты: - хешированный номер карты от нашего виджета, - [токен для рекуррентных платежей](/checkouts/payment-recurring#token). > [Как провести выплату на карту по токену](/transfers/payout-tokenized-card) ### Как провести выплату Процесс состоит из нескольких этапов. 1. **Проверьте остаток** на вашем выплатном балансе. Если его не хватит для перевода — пополните счет. 2. **Запросите у получателя реквизиты**, например, номер карты. 3. **Отправьте нам запрос** на проведение перевода. 4. **Получите подтверждение** от системы об успешной операции. ### Техническая реализация через API Все API-операции осуществляются в рамках [платежной сессии](/spec/objects#payment_session). Чтобы сделать выплату, выполните следующие шаги: 1. Создайте платежную сессию. Для этого отправьте запрос [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. >Еще вы можете использовать запрос [`transaction/init/transfer`](/spec/methods#transactioninittransfer). Тогда сразу передайте все параметры выплаты и пропустите следующий шаг. Все статьи о выплатах в этом разделе будут описывать только первый путь — через создание платежной сессии. 2. Начните выплату запросом [`transaction/start/transfer`](/spec/methods#transactionstartcheckout). 3. Дождитесь вебхука для выплаты [`approve_pending`](/spec/webhooks#approve_pending). Его получение значит, что Zetplat готов провести выплату и ждет подтверждения или отмены. 4. Подтвердите или отмените выплату. Для подтверждения отправьте запрос [`transaction/approve`](/spec/methods#transactionapprove), для отмены — запрос [`transaction/cancel`](/spec/methods#transactioncancel). 5. Дождитесь результата выплаты. Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results) со всеми данными. Результат выплаты — в поле `transaction_status` массива `payouts`. Статус `successful` означает успешную выплату. [Подробнее о статусах выплаты](/spec/objects#payout-statuses) ### Схема выплаты ![SequencePCIDSS](/img/docs/payouts/payout_scenario_ru.png) ```plantuml @startuml Payout autonumber header Выплата participant Партнер participant Zetplat as pike Партнер -> pike: отправляет ""transaction/initiate"" pike -> pike: создает сессию pike --> Партнер: отправляет 200 OK Партнер -> pike: отправляет ""transaction/start/transfer"" pike -> pike: начинает выплату pike --> Партнер: отправляет 200 OK pike -> Партнер: отправляет вебхук ""approve_pending"" Партнер --> pike: отправляет 200 OK Партнер -> Партнер: проверяет детали Партнер -> pike: отправляет ""transaction/approve"" pike --> Партнер: отправляет 200 OK pike ->pike: осуществляет выплату pike -> Партнер: отправляет ""checkout_results"" Партнер --> pike: отправляет 200 OK @enduml ``` --- ## Выплаты на карту - [Выплаты на карту](https://docs.zetplat.com/transfers/payout-pcidss): Выплаты с самостоятельным сбором данных карты (требуется PCI DSS). Этот способ подходит, если вы храните данные банковских карт на своей стороне и соблюдаете соответствующие требования стандарта PCI DSS. ## Как сделать выплату на карту ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "order123" }' ``` ### 2. Начните выплату Отправьте запрос на проведение выплаты с помощью метода [`transaction/start/transfer`](/spec/methods#transactionstartcheckout). В запросе передайте: - В параметре `session_id` — идентификатор сессии, созданной на шаге 1. - В параметре `type` внутри `payout_info` — значение `card_info`. - В объекте `card_details` — данные банковской карты получателя. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/session/start \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "session_id": "3230", "payout_info": { // highlight-next-line "type": "card_info", "card_info": { "type": "card_details", // highlight-next-line "card_details": { "card_number": "4242424242424242" } } }, "participant_info": { "payee_info": { "full_name": "Ivanov Ivan" } }, "extra_info": "good" }' ``` ### 3. Дождитесь вебхука для выплаты Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", "payouts": [{ "id": "po_1234", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } }' ``` ### 4. Подтвердите или отмените выплату Проверьте данные для выплаты, а затем подтвердите или отмените ее: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/cancel \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ### 5. Дождитесь результата выплаты Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешную выплату. [Подробнее о статусах выплаты](/spec/objects#payout-statuses) [Описание кодов ошибок и их значений](/spec/errors) --- ## Выплаты на карту с виджетом - [Выплаты на карту с виджетом](https://docs.zetplat.com/transfers/payout-widget): Выплаты через встраиваемый виджет, минимальные требования PCI DSS. Этот способ подходит для ситуаций, когда вы решили не собирать и не хранить данные банковских карт на своей стороне. В таком случае предлагаем использовать специальный [виджет для токенизации](/iframe/tokenize-widget). С ним вы можете получить токенизированные данные карты и безопасно провести выплату. ## Как сделать выплату на карту с виджетом ### 1. Получите токен Выполните запрос на создание токена [`public_token`](/spec/methods#public_token) и укажите в теле тип виджета `allow_tokenization`. В ответе вы получите публичный токен. >По умолчанию виджет на английском языке. Чтобы получить виджет на русском языке, передайте `"lang":"ru"`. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "card_tokenize": { // highlight-next-line "allow_tokenization": true, // highlight-next-line "lang":"ru" } }' ``` ### 2. Соберите данные карты через виджет Подключите JavaScript-библиотеку Zetplat и добавьте виджет токенизации на нужную страницу. Инициализируйте виджет, передав ему публичный токен, полученный на предыдущем этапе. Получатель вводит данные карты в форму виджета. В ответ вы получаете токенизированные данные — именно их нужно будет использовать для проведения выплаты. [Как добавить виджет для токенизации](/iframe/tokenize-widget) ### 3. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "order123" }' ``` ### 4. Начните выплату Отправьте запрос на проведение выплаты с помощью метода [`transaction/start/transfer`](/spec/methods#transactionstartcheckout). В объекте [`hashed_card_details`](/spec/objects#hashed_card_details) передайте токенизированные данные банковской карты, полученные из виджета. >Уточнить информацию о токене или карте можно с помощью метода [`public_token/state`](/spec/methods#public_tokenstate). Например, оттуда можно извлечь последние 4 цифры номера карты, чтобы показать клиенту, куда придет выплата. Набор обязательных параметров зависит от типа карты получателя. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/transfer \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230", "payout_info": { "type": "card_info", "card_info": { "type": "hashed_card_details", // highlight-start "hashed_card_details": { "hashed_card_number": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09", "hashed_card_exp_date":"f4286b9a8e0eb7974f34a996ee732fd861868f2fc7aaa7ed5cca8de2489534ad", "hashed_name_on_card":"dd6cce1e06790019dd266c6f70430f87dd378df802c6b7494395156f62533ce6", "hashed_card_code":"7756b897e88c035f34c6658a147e263b29b480a5cdf76581012ff10ede478c4c" } // highlight-end } }, "extra_info": "good" }' ``` ### 5. Дождитесь вебхука для выплаты Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", "payouts": [{ "id": "po_1234", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } }' ``` ### 6. Подтвердите или отмените выплату Проверьте данные для выплаты, а затем подтвердите или отмените ее: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/cancel \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ### 7. Дождитесь результата выплаты Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешную выплату. [Подробнее о статусах выплаты](/spec/objects#payout-statuses) [Описание кодов ошибок и их значений](/spec/errors) --- ## Выплаты на карту по токену - [Выплаты на карту по токену](https://docs.zetplat.com/transfers/payout-tokenized-card): Выплаты по существующему токену карты. Этот способ подходит, если: - У вас уже есть [токенизированный номер карты](/iframe/tokenize-widget). - Вы принимаете платежи и создаете [рекуррентные платежи](/checkouts/payment-recurring). В таком случае вы можете использовать рекуррентные токены для совершения выплат. >Возможность выплаты не зависит от проекта (`X-Project-Id` в header запроса), на котором был получен токен. ## Как сделать выплату на карту по токену ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{}' ``` ### 2. Начните выплату Отправьте запрос на проведение выплаты с помощью метода [`transaction/start/transfer`](/spec/methods#transactionstartcheckout). В запросе передайте: * В параметре `session_id` — идентификатор сессии, созданной на предыдущем шаге. * Один из следующих параметров, в зависимости от типа имеющихся у вас данных: * Токен — в объекте [`tokenized_card`](/spec/objects#tokenized_card). * Хеш — в объекте [`hashed_card_details`](/spec/objects#hashed_card_details). * Токен для рекуррентных выплат — в объекте [`recurring_token_info`](/spec/objects#recurrent). >Уточнить информацию о токене или карте получится с помощью метода [`public_token/state`](/spec/methods#public_tokenstate). Например, оттуда можно извлечь последние 4 цифры номера карты, чтобы показать клиенту, куда придет выплата. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/session/start \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "session_id": "3230", "payout_info": { "type": "card_info", "card_info": { "type": "tokenized_card", // highlight-next-line "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "participant_info": { "payee_info": { "full_name": "Ivanov Ivan" } }, "extra_info": "good" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/session/start \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "session_id": "3230", "payout_info": { "type": "card_info", "card_info": { "type": "hashed_card_details", // highlight-next-line "hashed_card_details": { "hashed_card_number": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } }, "participant_info": { "payee_info": { "full_name": "Ivanov Ivan" } }, "extra_info": "good" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/session/start \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "session_id": "3230", "payout_info": { "type": "recurring_token_info", // highlight-next-line "recurring_token_info": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } }, "participant_info": { "payee_info": { "full_name": "Ivanov Ivan" } }, "extra_info": "good" }' ``` ### 3. Дождитесь вебхука для выплаты Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", "payouts": [{ "id": "po_1234", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user", "contact_info": [{ "email_address": "user@test.ru" }] }, "payout_info": { "type": "card_info", "card_info": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } }' ``` ### 4. Подтвердите или отмените выплату Проверьте данные для выплаты, а затем подтвердите или отмените ее: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/cancel \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ### 5. Дождитесь результата выплаты Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешную выплату. [Подробнее о статусах выплаты](/spec/objects#payout-statuses) [Описание кодов ошибок и их значений](/spec/errors) --- ## Выплаты через СБП - [Выплаты через СБП](https://docs.zetplat.com/transfers/payout-sbp): Выплаты через Систему быстрых платежей. Вы можете отправить выплату физическому лицу, используя его номер телефона в Системе быстрых платежей (СБП). ### Дополнительные проверки - **Проверка регистрации получателя в СБП** — используйте метод [`sbp/identity_check`](/spec/methods#sbpidentity_check). Делать это перед каждым переводом необязательно: достаточно однократной проверки при первом использовании реквизитов. - **Получение списка банков-участников СБП** — используйте метод [`sbp/banks`](/spec/methods#banks_fps), чтобы проверить, подключен ли нужный банк к СБП. ### Параметры | Название | Обязательность | Тип | Описание | |-------------------------------------------------------|----------------|--------|---------------------------------------------------------------------------------------------------------| | `payout_info` | + | object | [Платежные данные](/spec/objects#payout_info) | |   `type` | + | string | значение: `account_info` | |   `account_info` | + | object | [Банковский счет](/spec/objects#account_info) | |     `payment_system` | + | string | Система банковских платежей. Всегда: `fps_info` | |     `fps_info` | + | object | [Данные СБП](/spec/objects#fps_info) | |       `phone_number` | + | string | Телефон получателя | |       `bank_identifier` | + | string | Идентификатор банка получателя в СБП | |       `money_purpose` | + | string | Назначение выплаты | | `sum_info` | + | object | [Сумма](/spec/objects#sum_info) | |   `sum` | + | int | Сумма в копейках. Значение должно быть больше нуля. Если отправляете 100 рублей, нужно передать `10000` | |   `currency_code` | + | string | Код валюты согласно ISO 4217. Регистр не важен. Всегда: `rub` | ## Как сделать выплату на карту через СБП ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. ### 2. Начните выплату Отправьте запрос на проведение выплаты с помощью метода [`transaction/start/transfer`](/spec/methods#transactionstartcheckout). Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/transfer \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_2704", "payout_info": { "type": "account_info", "account_info": { "payment_system": "fps_info", // highlight-start "fps_info": { "phone_number": "79680000000", "bank_identifier": "100000000069", "money_purpose": "Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается" } // highlight-end } }, "sum_info": { "sum": 30000, "currency_code": "rub" }, "extra_info": "good" }' ``` ### 3. Дождитесь вебхука для выплаты Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. ### 4. Подтвердите или отмените выплату Проверьте данные для выплаты, а затем подтвердите или отмените ее: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). ### 5. Дождитесь результата выплаты Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешную выплату. [Подробнее о статусах выплаты](/spec/objects#payout-statuses) [Описание кодов ошибок и их значений](/spec/errors) --- ## Возвраты выплат - [Возвраты выплат](https://docs.zetplat.com/transfers/payout-refunds): Возврат успешных выплат. Даже после успешного зачисления денег на банковский счет получателя возможен возврат. Это происходит, например, если в реквизитах была ошибка или счет получателя перестал действовать. В такой ситуации деньги возвращает банк, обслуживающий получателя. > Вы не можете сами отменить или вернуть успешную выплату. Единственный способ — попросить получателя перевести деньги обратно вам. ### Как узнать, что выплата вернулась Есть три способа отследить возврат. #### Через вебхук Дождитесь входящего вебхука [`checkout_refunded`](/spec/webhooks#checkout_refunded). В его теле будут данные выплаты, которая вернулась. Идентификатор исходной выплаты находится в поле `id` внутри массива `payouts`. #### Через запрос статуса сессии Если вы не используете вебхуки или предпочитаете активный опрос, отправьте запрос `transaction/state`. В ответе придет информация о [статусе платежной сессии](/spec/methods#transactionstate). При наличии возврата в ответе также будут данные о возврате. #### Через реестр выплат Информация о возврате выплаты приходит в [реестре выплат](/logs/daily-payout-report). На следующий день после того, как выплата вернется, в реестре появится строка с ее описанием: в поле `typeOfPayment` будет `Refund`. --- ## Обзор платежей - [Обзор платежей](https://docs.zetplat.com/checkouts/payment-intro): Как принимать платежи банковскими картами и через СБП. С помощью нашего API можно принимать платежи банковскими картами Visa и MasterCard. ### Какие платежи можно принимать - [обычный платеж картой](/checkouts/payment-cards), - [платежи с холдированием](/checkouts/payment-hold), - [платежи через виджет](/checkouts/payment-with-form), - [рекуррентные платежи](/checkouts/payment-recurring), - [платежи через СБП](/checkouts/fps), - [рекуррентные платежи через СБП](/checkouts/recurring-fps). ### Как получать данные карт для платежей Вы можете узнать данные карты получателя одним из двух способов в зависимости от вашей модели безопасности и интеграции. #### Виджет Zetplat Встройте на сайт наш виджет — вариант подходит, если вы приняли решение не собирать и не хранить данные банковских карт на своей стороне. > [Как провести платеж на карту с виджетом](/checkouts/payment-with-form) #### Самостоятельный сбор данных Вы можете собирать номера карт на своей стороне и передавать их напрямую в запросе на проведение платежа. Для этого способа нужно выполнять требования стандарта PCI DSS. > [Как провести платеж на карту](/checkouts/payment-cards) ### Техническая реализация через API 1. Создайте платежную сессию. Для этого отправьте запрос [`transaction/initiate`](/spec/methods#transactioninitiate). В теле вебхука придут все данные, с которыми проводился платеж. Результат платежа приходит в поле `transaction_status`. >Еще вы можете использовать запрос ([`transaction/init/checkout`](/spec/methods#transactioninitcheckout)). Тогда сразу передайте все параметры платежа и пропустите следующий шаг. Все статьи о платежах в этом разделе будут описывать только первый путь — через создание платежной сессии. 2. Начните платеж запросом [`transaction/start/checkout`](/spec/methods#transactionstartcheckout). 3. Дождитесь вебхука для платежа [`approve_pending`](/spec/webhooks#approve_pending). Его получение значит, что Zetplat готов провести платеж и ждет подтверждения или отмены. 4. Подтвердите или отмените платеж. Для подтверждения отправьте запрос [`transaction/approve`](/spec/methods#transactionapprove), для отмены — запрос [`transaction/cancel`](/spec/methods#transactioncancel). 5. Выполните дополнительные действия. Если вы получите вебхук [`action_pending`](/spec/webhooks#action_pending) от Zetplat, это значит, что для проведения платежа нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure. В этом случае, перенаправьте пользователя на адрес для 3D Secure. 6. Дождитесь результата платежа. Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Результат платежа приходит в поле `transaction_status` массива `payments`. Статус `successful` означает успешный платеж. [Подробнее о статусах платежа](/spec/objects#payment_status) ### Тарифы и лимиты Тарифы на эквайринг фиксируются в договоре с Zetplat, их можно обсудить с вашим менеджером. --- ## Платежи с холдированием - [Платежи с холдированием](https://docs.zetplat.com/checkouts/payment-hold): Двухстадийные платежи: холдирование и последующее списание. Обычный платеж банковской картой проходит в две стадии: 1. Авторизация — Zetplat проверяет, что нужная сумма есть на карте, и блокирует ее. 2. Клиринг — Zetplat списывает деньги с карты. При **обычном платеже** между авторизацией и клирингом практически нет паузы. При **холдировании** вы сами решаете, когда проводить клиринг. Сначала сумма замораживается на карте покупателя, а списание происходит отдельным запросом позже — например, после того как заказ собран или отправлен. **Как включить холдирование** По умолчанию все ваши платежи могут проходить без холдирования: деньги списываются сразу после авторизации. Если вы хотите проводить платежи с холдированием, обратитесь к вашему менеджеру в Zetplat. Настройка действует на все платежи — они все будут с холдированием или без него. **Срок холдирования** Сумма замораживается на карте **3 дня 23 часа**. Если за это время вы не списали деньги и не разблокировали их, блокировка снимается автоматически. Если вам нужно, чтобы по истечении срока деньги списывались, а не разблокировались, сообщите об этом вашему менеджеру в Zetplat. ### Как провести платеж c холдированием #### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. #### 2. Дождитесь вебхука для платежа Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. #### 3. Подтвердите или отмените платеж Проверьте данные для платежа, а затем подтвердите или отмените его: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). #### 4. Выполните дополнительные действия Если вы получите вебхук [`action_pending`](/spec/webhooks#action_pending) от Zetplat, это значит, что для проведения платежа нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure. В этом случае, перенаправьте пользователя на адрес для 3D Secure. #### 5. Дождитесь заморозки денег Zetplat отправит вам вебхук [`finalization_pending`](/spec/webhooks#finalization_pending). Это значит, что деньги для оплаты заморожены на банковской карте пользователя. Их можно списать сразу или через некоторое время, полную сумму или меньше — передайте нужную сумму в [`sum_info`](/spec/objects#sum_info). #### 6. Спишите нужную сумму или отмените платеж Это может быть захолдированная сумма или меньшая сумма ([`transaction/finalize`](/spec/methods#transactionfinalize)). Для отмены платежа используйте ([`transaction/cancel`](/spec/methods#transactioncancel)). #### 7. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема платежа с холдированием ![Схема платежа с холдированием](/img/docs/payments/schema_payment_hold_ru.png) #### 1. Выполните [шаги 1—5](/checkouts/payment-with-form). #### 2. Дождитесь заморозки денег Zetplat отправит вам вебхук [`finalization_pending`](/spec/webhooks#finalization_pending). Это значит, что деньги для оплаты заморожены на банковской карте пользователя. Их можно списать сразу или через некоторое время, полную сумму или меньше — передайте нужную сумму в [`sum_info`](/spec/objects#sum_info). #### 3. Спишите нужную сумму или отмените платеж Это может быть захолдированная сумма или меньшая сумма ([`transaction/finalize`](/spec/methods#transactionfinalize)). Для отмены платежа используйте ([`transaction/cancel`](/spec/methods#transactioncancel)). #### 4. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема платежа с холдированием ![Схема платежа с холдированием](/img/docs/payments/schema_payment_with_form_hold_ru.png) --- ## Платежи банковской картой - [Платежи банковской картой](https://docs.zetplat.com/checkouts/payment-cards): Платежи с самостоятельным сбором данных карты. Этот способ подходит, если вы храните данные банковских карт на своей стороне и соблюдаете соответствующие требования стандарта PCI DSS. Вы можете принимать платежи банковскими картами Visa и MasterCard. >Способ не учитывает шаг с холдированием платежа. [Как провести платеж с холдированием](/checkouts/payment-hold). ## Как провести платеж картой ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "order123" }' ``` ### 2. Начните платеж Отправьте запрос на проведение платежа [`transaction/start/checkout`](/spec/methods#transactionstartcheckout). - В параметре `session_id` передайте идентификатор платежной сессии, созданной на первом шаге. - В поле `type` объекта `payment_info` передайте значение `card_info`. - В объекте [`card_details`](/spec/reference-objects.mdx#bankcard) передайте данные банковской карты пользователя. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/checkout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_info": { // highlight-next-line "type": "card_info", "card_info": { "type": "card_details", // highlight-start "card_details": { "card_number": "4242424242424242", "card_exp_month": "01", "card_exp_year": "26", "card_code": "123" } // highlight-end } }, "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "extra_info": "good" }' ``` ### 3. Дождитесь вебхука для платежа Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "ongoing", "created_date": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2018", "transaction_status": "pending", "created_date": "2018-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payment_info": { "type": "card", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } }' ``` ### 4. Подтвердите или отмените платеж Проверьте данные для платежа, а затем подтвердите или отмените его: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 5. Выполните дополнительные действия Если вы получите вебхук [`action_pending`](/spec/webhooks#action_pending) от Zetplat, это значит, что для проведения платежа нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure. В этом случае перенаправьте пользователя на адрес для 3D Secure. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "type": "action_pending", "session_info": { "id": "ps_3230", "transaction_status": "ongoing", "created_date": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_131", "transaction_status": "pending", "created_date": "2018-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "8801" } }, "sum_info": { "sum": 15000, "currency_code": "rub" }, "user_action": { "type": "redirect", "destination_info": { // highlight-next-line "url_address": "https://zetplat.com?foo=bar", "domain": "https://zetplat.com", "http_method": "POST", "additional_params": { "foo": "bar" }, "extra_params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ### 6. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема платежа картой ![Схема платежа картой](/img/docs/payments/schema_payment_no_hold_ru.png) --- ## Платежи через виджет - [Платежи через виджет](https://docs.zetplat.com/checkouts/payment-with-form): Платежи через встраиваемую форму оплаты. Этот способ описывает отправку платежа на банковскую карту через виджет (платежную форму). Подходит, если вы приняли решение не собирать и не хранить данные банковских карт на своей стороне. >Способ не учитывает шаг с холдированием платежа. [Как провести платеж с холдированием](/checkouts/payment-hold). ## Как провести платеж через виджет ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "order123" }' ``` ### 2. Начните платеж Отправьте запрос на создание токена [`token`](/spec/methods#public_token). Передайте в нем идентификатор сессии и тип виджета, который будете вызывать. В ответе придет токен. > Если хотите добавить в платежную форму чекбокс согласия на автоплатежи **Соглашаюсь на автоплатежи**, передайте в поле `show_autopay_option` значение `true`. Это нужно, чтобы проводить [рекуррентные списания](/checkouts/payment-recurring). Флажок в этом чекбоксе может отсутствовать по умолчанию. Если вы хотите, чтобы флажок был предустановлен, обратитесь к вашему менеджеру Zetplat. >По умолчанию виджет на английском языке. Чтобы получить виджет на русском языке, передайте `"lang":"ru"`. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_form_config": { "session_id": "ps_123456", "show_autopay_option": true, // highlight-next-line "lang":"ru" } }' ``` ### 3. Отправьте получателю платежную форму. Для этого нужно подключить нашу JavaScript-библиотеку и добавить виджет платежной формы. [Как добавить платежную форму](/iframe/payment-widget) ### 4. Дождитесь вебхука для платежа Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2705", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payment_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } }' ``` ### 5. Подтвердите или отмените платеж Проверьте данные для платежа, а затем подтвердите или отмените его: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). ### 6. Выполните дополнительные действия Если вы получите вебхук [`action_pending`](/spec/webhooks#action_pending) от Zetplat, это значит, что для проведения платежа нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure. В этом случае, перенаправьте пользователя на адрес для 3D Secure. Примеры ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/cancel \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "3230" }' ``` ### 7. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема оплаты через платежную форму ![Схема платежа через платежную форму](/img/docs/payments/schema_payment_with_form_ru.png) --- ## Рекуррентные платежи - [Рекуррентные платежи](https://docs.zetplat.com/checkouts/payment-recurring): Автоматические регулярные списания по токену карты. Рекуррентный платеж — это повторное списание денег с карты пользователя. Такие платежи бывают двух типов в зависимости от участия пользователя и проверки 3DS: - Без участия пользователя, по токену. Такие платежи называются **Merchant Initialized Transaction** (MIT). - С идентификацией пользователя через 3DS. Такие платежи называются **Customer Initialized Transaction** [(CIT)](#recurring-cit). Сейчас проводить рекуррентные платежи можно только банковской картой, позже появятся другие способы. ## Рекуррентные платежи MIT MIT — это платежи, которые вы инициируете без участия пользователя, используя ранее полученный токен карты. Пользователь не подтверждает каждый платеж, а только видит списание. **Основные шаги** 1. [Получить согласие пользователя](#agreement) на безакцептные списания. 2. [Провести первый успешный платеж](/checkouts/payment-recurring#step1) и получить [токен](#token). 3. [Выполнять следующие платежи по этому токену](/checkouts/payment-recurring#step3). ## Согласие пользователя Рекуррентные платежи происходят автоматически, без участия пользователя. Вы несете полную ответственность за сумму, периодичность и за то, что пользователь действительно согласился на такие списания. Согласие потребуется в спорных ситуациях, например, если пользователь заявит, что не разрешал списывать деньги. **Как получить согласие** Любым способом, который позволит вам подтвердить факт согласия в спорной ситуации. Главное, чтобы пользователь узнал о последующих списаниях. 1. Опишите условия подключения автоплатежей так, чтобы пользователь их точно прочел. 2. Добавьте чекбокс с понятной подписью, например, **Сохранить карту**, **Подключить автоплатеж**, **Подписаться на пожертвования** и т.п. Если пользователь отмечает чекбокс — автоплатеж включается, если нет — не включается. Где разместить чекбокс: - На вашей стороне — вы сами решаете, как он выглядит и где находится. - В [платежном виджете Zetplat](/checkouts/payment-recurring#step1) — готовая опция, которую можно показать пользователю. ## Токен для рекуррентных платежей Токен — это безопасный заменитель данных карты. Чтобы его получить, нужно провести первый успешный платеж с указанием сохранить данные карты. В ответ на такой платеж вернется [токен](/spec/objects#recurrent_token_info). Полученный токен можно сохранить и использовать для: - последующих рекуррентных платежей, - выплат на ту же карту. **Способы получить токен** - Через API (с чекбоксом на своей стороне). При [создании платежной сессии](/spec/methods#transactioninitiate) или в любом запросе на проведение платежа передайте параметр `allow_recurring=true` (в объекте [`payment_settings`](/spec/objects#payment_settings)). Если платеж успешен, в ответе вернется токен. При этом согласие пользователя вы должны получить заранее, например, через свой чекбокс. - Через платежный виджет Zetplat. В виджете можно включить отображение чекбокса с текстом **Соглашаюсь на автоплатежи**. Если пользователь отметит его и платеж пройдет успешно, токен будет возвращен автоматически. **Статусы токена** | Статус (`token_active`) | Значение | |-------------------------|------------------------------------------------------| | `true` | Токен активен, по нему можно проводить платежи | | `false` | Токен неактивен, платеж не пройдет (вернется ошибка) | Чтобы проверить статус токена, отправьте запрос [`public_token/state`](/spec/methods#public_tokenstate). В поле `type` передайте значение `recurring_token`, в поле `recurring_token.token` — токен, статус которого нужно узнать. В ответ придет [`token_info`](/spec/objects#info_recurrent) дата окончания действия токена (`completed_date`) и его статус (`token_active`). Дата окончания действия токена `completed_date` никак не проверяется на стороне Zetplat — токен останется активным и после даты, указанной в этом параметре. > Важно помнить, что активный токен не гарантирует успешное прохождения платежа, отказ может быть получен от банка-эмитента карты. **Как отключить токен** Если токен больше не нужен (например, пользователь отключил автоплатеж), отправьте запрос [`recurring_token/disable`](/spec/methods#recurring_tokendisable). В ответ придет [`recurring_token_info`](/spec/objects#recurrent_token_info). Если статус `token_active: false`, значит, токен отключен, по нему больше нельзя проводить платежи. > После отключения в параметре `completed_date` может появиться дата, относящаяся к 2000 году. Это техническое значение, на которое можно не обращать внимания. ## Как сделать рекуррентный платеж MIT ### 1. Проведите успешный платеж с указанием создать токен > [Как провести платеж без виджета](/checkouts/payment-cards) При создании платежной сессии или в запросе на создание платежа в [`payment_settings`](/spec/objects#payment_settings) передайте в поле `allow_recurring` значение `true`. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/init/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_info": { "type": "card_info", "card_info": { "type": "card_details", "card_details": { "card_number": "4242424242424242", "card_exp_month": "01", "card_exp_year": "22", "card_code": "087" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" }, "payment_settings": { // highlight-next-line "allow_recurring": true } }' ``` > [Как провести платеж с виджетом](/checkouts/payment-with-form.mdx) Если вы проводите платеж с виджетом, можете показать пользователю на виджете чекбокс **Соглашаюсь на автоплатежи**. Для этого в запросе на [создание токена](/spec/methods#public_token) для виджета передайте в поле `show_autopay_option` значение `true`. > Это необязательно: вы можете получить согласие пользователя раньше, передать `allow_recurring: true` при создании платежной сессии и показать пользователю виджет без галочки, как при обычном платеже. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_form_config": { "session_id": "ps_34851", // highlight-next-line "show_autopay_option": true } }' ``` Потом [сформируйте платежную форму](/iframe/payment-widget) с этим токеном. Если пользователь поставит галочку в чекбоксе **Соглашаюсь на автоплатежи**, то есть согласится на проведение рекуррентных списаний с карты, вам придет токен. ### 2. Сохраните токен после успешного платежа Если платеж пройдет успешно и при оплате через платежную форму пользователь согласится на рекуррентные списания, в вебхуке [`checkout_results`](/spec/webhooks#checkout_results) вернется токен. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2705", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id":"lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "recurring_token_info": { // highlight-next-line "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_date": "2020-07-14T13:17:11+03:00", "completed_date": "2020-07-31T16:05:42+03:00", "token_active": true, "type": "recurring_token" }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "payment_settings": { "allow_recurring": true } }] } }' ``` ### 3. Проводите платежи с использованием токена Отправьте запрос на проведение платежа с типом оплаты `recurring_token_info`. Вместо данных банковской карты передайте токен, который вы сохранили при предыдущем платеже. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/init/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_info": { // highlight-next-line "type": "recurring_token_info", "recurring_token_info": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" } }' ``` ## Как сделать рекуррентный платеж CIT Рекуррентный платеж CIT (**Customer Initialized Transaction**) — это возможность проводить оплату по токену с верификацией плательщика через 3DS. Для гарантии успешной оплаты платежей CIT мы рекомендуем использовать [идентификатор проекта](/api-rules/signature), предназначенный для платежей с 3DS. ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/init/checkout`](/spec/methods#transactioninitcheckout). В запросе передайте значение [`payment_info.recurrent.initiated_by:client`](/spec/objects#recurrent_token_info) и URL для возврата плательщика после прохождения верификации 3DS в параметре `back_url`. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/init/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_info": { "type": "recurring_token_info", "recurring_token_info": { "token": "token_value", // highlight-next-line "initiated_by": "client" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" }, "payment_settings": { // highlight-next-line "back_url": "https://zetplat.com" } }' ``` ### 2. Получите данные для редиректа Получите от Zetplat вебхук [`action_pending`](/spec/webhooks#action_pending) с [данными для редиректа](/spec/objects#customer_interaction_redirect) на страницу прохождения 3DS. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "type": "action_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2705", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id":"user@152.ru" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "user_action": { "type": "destination_info", "destination_info": { "url_address": "https://api.zetplat.com?foo=bar", "domain": "https://api.zetplat.com", "http_method": "GET", "additional_params": { "foo": "bar" }, "extra_params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ### 3. Перенаправьте пользователя на 3DS Получите из ответа Zetplat: - `user_action.destination_info.url` — адрес для перенаправления, - `user_action.destination_info.method` — метод запроса (GET или POST). Выполните перенаправление указанным методом. >После прохождения 3DS пользователь вернется на ваш `back_url`. Метод вызова `back_url` также может быть GET или POST. Если это POST, а ваш обработчик ожидает GET, настройте преобразование (редирект) из POST в GET. ### 4. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "type": "checkout_results", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2705", // highlight-next-line "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id":"lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "recurring_token_info": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_date": "2020-07-14T13:17:11+03:00", "completed_date": "2020-07-31T16:05:42+03:00", "token_active": true, "type": "recurring_token" }, "sum_info": { "sum": 10000, "currency_code": "rub" } }] } }' ``` [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема рекуррентного платежа CIT ![](/img/docs/payments/cit_ru.png) --- ## Платежи через СБП - [Платежи через СБП](https://docs.zetplat.com/checkouts/fps): Платежи через Систему быстрых платежей. Вы можете принимать платежи через Систему быстрых платежей (СБП). Для этого разместите на нужной странице ссылку на оплату через СБП. ## Способы приема платежей - Если платеж проводится в десктопном браузере — с использованием QR-кода (`user_action.type.payment_qr.qr_data.img` из вебхука `action_pending`). - Если платеж проводится с мобильного устройства — с использованием диплинка для перехода в приложение банка, который выпустил карту (`user_action.type.payment_qr.qr_data.qr_content` из вебхука `action_pending`). >После успешной оплаты в параметре `phone_number` в объекте [`contact_info`](/spec/objects#customer_contact) будет передан маскированный номер телефона плательщика. Если хотите получить полный номер, обратитесь к своему менеджеру в Zetplat. [Как получить токен для приема рекуррентных платежей через СБП](/checkouts/recurring-fps) ## Как провести платеж через СБП ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). Укажите `fps_info` в `payment_info.type`. При необходимости укажите назначение платежа в параметре `money_purpose` объекта [fps_info](/spec/objects#fps_info). В ответе придет идентификатор платежной сессии. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_info": { // highlight-next-line "type": "fps_info", "fps_info": { // highlight-next-line "money_purpose": "Оплата услуг" } }, "sum_info": { "sum": 5000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" } }' ``` ### 2. Начните платеж Отправьте запрос на проведение платежа [`transaction/start/checkout`](/spec/methods#transactionstartcheckout). Укажите уникальный идентификатор клиента в `user_info.user_id` и/или IP пользователя в `participant_info.payer_info.ipv4_address` (хотя бы одно из этих значений должно быть передано). В параметре `payment_settings.back_url` передается URL для возврата из приложения эмитента. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_123456789", "payment_info": { "type": "fps_info", "fps_info": { "money_purpose": "Оплата услуг" } }, "payment_settings": { // highlight-next-line "back_url": "https:\/\/acme.com\/api\/payments\/01hp306zyxxznp7tdrwq7dygaf\/redirect" }, "user_info": { // highlight-next-line "user_id": "lucky" }, "participant_info": { "payer_info": { // highlight-next-line "ipv4_address": "192.168.0.1" } } }' ``` ### 3. Дождитесь вебхука для платежа Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. ### 4. Подтвердите или отмените платеж Проверьте данные для платежа, а затем подтвердите или отмените его: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). ### 5. Выполните дополнительные действия Дождитесь вебхука [`action_pending`](/spec/webhooks#action_pending). В параметре `user_action.payment_qr.qr_data.qr_content` передается диплинк на оплату. Его можно показать плательщику в виде QR-кода или отправить по нему плательщика в приложение банка-эмитента. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "action_pending", "session_info": { "id": "ps_120285623", "transaction_status": "active", "created_date": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:53.847595Z", "payments": [{ "id": "pm_94939668", "transaction_status": "pending", "created_date": "2024-02-07T23:59:53.160440Z", "user_info": { "user_id": "95.24.204.116" }, "participant_info": { "payer_info": { "ipv4_address": "192.168.0.1" } }, "payment_info": { "type": "fps_info", "fps_info": { "money_purpose": "Оплата услуг" } }, "sum_info": { "sum": 1000, "currency_code": "RUB" }, "user_action": { "type": "payment_qr", "payment_qr": { "qr_data": { // highlight-next-line "qr_content": "https://qr.nspk.ru/AD1000269CKIK8M09C1RB40LB7QAM8IH?type=02&bank=100000000143&sum=1000&cur=RUB&crc=C900", // highlight-next-line "qr_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAATw0lEQVR42u3deXBURR7Acba2at3aqt2tPRRh5dBFWBQUWFYBCVqIS4mCuF5EQiGHohwCyuGFHCpGRUAsISACGw5RWK6AAV3FFbkhCgQLiCEc4QhHCCEkmVy/zYxmYEIyCWHy+tdvvr+q/gOmJzPzXvfnHb/X3TWEIAjCkqjBJiAIArAIgiAAiyAIwCIIggAsgiAIwCIIArAuerFGDTWlst+v0j/8Cj7X2M4ytK2u5PuFup4T7cqJtmaqHdjYzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlqmOqakRaYdXExKmOo1bDgza+4ITvw2wAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACvswDLVgW38ftqLEx3JVDtwc7ZT076szv0GWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWEqzZpoygqb+nqbspKlsopsPjoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWOqyPpqGLWhvlJqG0tjYqbXP1wVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYzIdlFCInsn+aMqDat4upbKJbwDfVzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlo0rP1OPetSzY942wKIe9agHWIBFPeoBFmABFvWoB1iART3qUc/VYGkPTcMgtM+HpSmLZOO8aNrbn6bsX7X2ecACLMACLMACLMACLMACLMACLMACLMACLMACrHAAS/uE/6Y6g5vnBHPLfFja8dS+CIrTnwFYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgGU1WG4eXqM9q2LjECgbs8qa9pum7KRWFAELsAALsAALsAALsAALsAALsAALsAALsAALsABLQZZQO6jaF1YIdYPWnsXUhKL29uf4QQewAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACscwLIxI2PjAhvhMvyiukBwy8FME3ZOZ/QBC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7BcB5aphqWpQZv6ztqHc2iCSDsc2hdB0RqABViABViABViABViABViABViABViABViABVhhC5amDa19OIxbMLERVLcsWuKWkwbAAizAAizAAizAAizAAizAAizAAizAAizAAixXg+VE5zcFpanGa6qzakJHUyZNe9u1MUtYnZ8BWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIDlOrA0IWHjnFumtrOmrFS4rRSuvQ1p6jOABViABViABViABViABViABViABViABViABViuBsstQ1pM7STtnZoMlJ3bwNTvCHVbC3mWELAAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AASztYNnYkTSsSu2UeJDevthxukGvfLoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWGEHlo2Nw1RH15RN1D7nlo0LgJjab9rbs/r5sAALsAALsAALsAALsAALsAALsAALsAALsAALsJjTXVe2RNNnaMrWhdvqzcyH5fxQJMACLMACLMACLMACLMACLMACLMACLMACLMACLKvBcstKyDZ2JO3zZmnKIGvvwJoO/LbvD8ACLMACLMACLMACLMACLMACLMACLMACLMACLKvBMpW90p7lqs5GTugMtwwX03SQUj+BH2ABFmABFmABFgFYgAVYgEUAFmABFmABFmCFGiwbV/I1NeeRG4ddEPaAoH0OL0fmwwIswCIAC7AAC7AAC7AAC7AIwAIswAIsArBsBMvNG9VUIwIsO1HS1Pltz/4BFmARgAVYgAVYgAVYgAVYgAVYgAVYgEUAVtiC5ZZVnp0AuirvdS6K0MihDux0p64uFE0ZAViAJYWntkr2irFSlHUGeQALsABLN1hFp9fL+TmNJf2l2yV346Li/+CMC7AAC7AUg5UXX1syxjSV04MbytnJj0nBkT0oBFiABVhawbpWchY29IHlK0Mby/kl46Uo5xwaAZZ9YJnaCE58rimMtYHlLWffanoBreJy5tUI8SSsQqQQtT8nOrqNC6gAFmBVCazcJTf4zq4uRstbMqf1loLjyWgFWIAFWHrA8pZzU5pcApa3pD/fRLI/myxFebmABViABVg6wPLE1ZX04TeViZbvMnFse8nb/TVgARZgAZZ5sLwla0bjcsEqKec+GiCF6UcBC7D0gRVuwGho5Jcbc789JFmegpCAlfffppK9arLvMjAYWukjmknOFzEiBXlhA5UTnVrrHG2agAYsy8HqM/IzaTH1e4nfl37FYOV/dYvvtcITByRzaq8Kz7Yy3uwk+UmbAQuwAAuwKhcD+i2S20etlT+/uVkeX7RXDmXkXjFYJeH5Ll7OjG4XHK4hjSRrwQtSdO60Y9s1Py9fzp/PBizAAiwbwerW6xOp/dZmH1p1JmyVyRuOiKegqAqXhI0DYUg9JUe7jZf9DR4LWlI7DRVPYmifkt+1c488N/g1afX3rnJjvTvlr3UipE7NVnLdNbf7yrP9RwMWYAGWjWB1fyxW2o383AdWSbnjw52y4VDmZYLV6KfXPPmSPmmZJP0pUvZe9WC5JekP3eR09CIpyg3tvax3354hda9t7cepdPHilXr4GGABlvNgOZ2F0zhHUSjA6t5jgdR7c1MAWldHb5YBcclyIiuv0mBlf5MoKc2eDQqVt6R2eU3yUo6HHIgpk2aXC1VJeW3MFLUHJE0ZRk1zvoXKF8ByC1jFpePznwWAVVJumLhNPtqeJoVFFYC1uoHs/fW/gkKV3OBJObd0Y5X21949+2X+3GUyacJMeX/yHPlizTrxeC5gmrQvRerXvsMP023Nu8jKFV/K2YxMyc31+EthYaH/PVlZ2bJh/fZKlW1bdgIWYAGWFrCiIudKo/EbykTLWzrMSZSEo1nBwSoHqn2/fUROvhwrhedyLvs7JmxPlAc69S3zbKl5k06++1XeGP7ceP//33RjBzmSelwyirHaunmHbN2yQ06dvDQTunvXvgrPyC7+LMACLMBSApa3PDBweblgeUvN6C0ycs0BST/yTaXBOtThZfH8cKhK+yh+1Vq5/i9ty0Wk5a2dfRm/oqIiueVvHf3/P6DfKHm670tSr1Yb//9572tFPjJIkn88CFiABVhuAMtbes3ZIdcUwxQMrsYT/yfzF/YVT3ytcsFKrttLzs7/usqzKR89kiYNr7/LD4YXn75PjJDXx74vfXqO8N08/8+ieF/dQwePBOBycUawdLm1cUdJTT1eJlg3XBfhOzsrKfVqtQYswLKrXqhB1ZTZLAusH3Yf9136tZ+dGBQtb+n8wQJJXB4RCNZvHpK0QdOlIP3K5sV6J3p6AFbrv90W8Prp0xlS+PONte8Tdl96RnTzvT7c3nx9qrRoel/Aa889O65MsEa/MingMzq27xESsLQOVamu9qz1BAawXAqWNwqKL7NmbDvuu+keDK1ab22SMXNelYz4W+Rg2xGSsy0pJJ0o8uGBfix6dBsStO6unXsD4Klfu40cSDnsf/3ggdTiS8sLN+SbNvonYAEWYLkJLG/k5+TLyqnr5IERa+TqCs62mk/+UuL3hO6J9Ye69PNj8cyTLwete/JkegA87SMiL6lzd7vIgDreDCNgARZguQSslI37ZV7PWIm59wNfGRM1V5qPXVfhZWLU4n1y+KznijvRiIuyfk0a3lN8CRh8hZ42LR/017/5xg6Sl3fhkQfvcJybi/9GyesN69/JGRZgAZYbwNqyNklWj13lhyqgdI6R3gOXS51SD5mWLnUnbJUpG49KXkHVV9PZtCEhAJN2rR+RTz6Oky2bd/hutvd/6pUAxN6JjgmoP3jgWDl27ITv7GvYkNcDXuvVYxhgAVb1bnxNi0aY2nGhjtJg9Xl8rkzrElM2Vj+XmV2ny8J5cdIyZmGFZ1veIT7fHsys8vcbPnR80EcNRr30rr+u95mr25p1rvDxhAZ12xWfRSY5CpaprLImKAELsEIO1huRc4JiFT9mlWQez5Q9p7ZKnxW3StePB0n9iV8FRct776t/XLKkZV3+mMH8/AJ5Y9z7ATfMS+Nz8VnWvr0pEtHq4XKxatG0k6xfdyHbCFiABViWgtU/ap5Mv39amVDN7xnru6dVEiVgeUuv5W0k4qMJUjM6+NmWN9s4KyHNl3283PA+tR7zwTzfA6FR3QbLgKdHybTif3ufvyodnlyPfLIgzvfg6H3/fEI63fOE9Ov9osyPXSpZWecD6p45c1Y+XbjSX75L2B3w+uerv/G/tmLZF4AFWIClBawJj866BKoPiy8PN83aKPm5+QHvuxisktJzaaTcN/eHCi8T756dKN8fy5JwD8ACLMCqIlhDi8+uSmO1YuQyST9Y9mMKZYE1KL6tb8X6+TtOSKP3tgdFy/sk/bDVKZKRUwBYgGUXWG6Zi0dDNqcqYEV1i5UpD830QxXbfbYkrd0XdEhNeWCVRHp2vgyN318MU/CzrcZTEmRR4qmwRMnUwcwtfbBKvx2w7Afrxcd/etZq+v1TZX3MOvFkVfwMVUVgeaOgsECejpsjNd8eGrTUn/iCfJ3yI2ABFmABVvAY0n+xTO06QxYP/FTS9qZV+n0VgbXh0E5pNq27/GL0bUHLvXMHS9Lpw5xhARZgAVbFMXX4Mtm1fIcUFV5e5q48sE6cPyO9lo6TX45pFRSquhM7y+LdX4b1fSrAAizAuszIyaraEJqywIpaEiF/jL47KFS/GttGhq15T855siUcArAsB8tUxs3UBnR6IQ6noiywGrwXERSrdrOeksS0ZCHMtl1TfdUJUAELsCoFVteFd5QL1TVvd5R/f7dSiqQIpQALsADLLFh941pI7QntLoHKex/rmZXRkp6diU6ABViApQOse2LbXoJVi5gesjl1NyoBFmABlh6wei9vKb8ff+Fy8Hfj75JJGxdIfmEBIgGWO8EytfGd+H5Ow+Y0WK1mXji7evTTFyX1bBoSVbLtmALBFGIahqQBVhiDFbXkH3LVuNbScMrDsubHjegEWIAFWHrBajm9g4xZ+6Hk5HuQCbAAC7D0gnXifJokp6ciEmABFmDpB4sArLAFy4mdpAmd6mwIhD1wae/8Ng4nAizAIgALsAALsAALsAALsAjAAizAAiwCsABLGQimGq+mObcIZ/a19gN1qPughvYMWIBFABZgARZgARZgARZgEYAFWIAFWARghQVYTvxgTfNXVefnEnZjpulAbaq/VSdigAVYBGABFmABFmABFmABFgFYgAVYgEUAltVgacLJ1Iq1mhqgE43SiU7jxD534mBmCkVNJxJObyvAAizAAizAAizAAizAAizAAizAAizAAizAAizXgaUpC6dpjiJTHc7GzJJ2PLXDq+nA6vTvBSzAAizAAizAAizAAizAAizAAizAAizAAizAshosTUMKtGdaNHUQUx3Oxm1vKmum6QBnU/YUsAALsAALsAALsAALsAALsAALsAALsAALsADLarBMNWjtGUZTmRu3DHMx1da0Z/U0gOBkOwUswAIswAIswAIswAIswAIswAIswAIswAIswAIsF3UGJ7J62ocxadqX2r9LuAEIWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWNUAllsam/ahEZo6jakskpuzpzZms00dqAELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlhMZPO2LD5iCSHvmVRN22r+zJpxszMADFmABFmABFmABFmABFmABFmABFmABFmABFmC5BixT2TVT2GnPfGlfpCDc5q9yc+Za6xAjwAIswAIswAIswAIswAIswAIswAIswAIswAIsq8FyItOifSVaG4dp2FhPe9vQPreZjVnWqvw9wAIswAIswAIswAIswAIswAIswAIswAIswAIs14GlKYOnfaiFqU5jY4ZMawdxEg7tC2yYOmkALMACLMACLMACLMACLMACLMACLMACLMACLMByDVjaG5abV5d28+INNs4FpWneMRtXsDY2HxZgARZgARZgARZgARZgARZgARZgARZgARZgAZZ2sLQ3Sicah1t+r6kO55bQPk+Ypow5YAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYLmoITjxXk1waJ+/StOq1po+w4n3ajooq5oPC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAy81gaYdNU8My9fdCvd9YhEIXlFqzooAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWFaDpT07pH0nac8waloIwdSiEdpXv7bxt1VnuwcswAIswAIswAIswAIswAIswAIswAIswAIswHIdWJqyf6FuCNqzk6bm4bJx+7k5k6u9HajKEgIWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYNkIlo0ZmVDvOFPzPtk4p5WNbUPDAgxuy+gbyxICFmABFmABFmABFmABFmABFmABFmABFmABFmABlq5GZOPQIaezOaaznW4BWlObBCzAAizAAizAAizAAizAAizAAizAAizAAizAAqwwBEvThP9uWViBYSnuWfnZ9gAswAIswAIswAIswAIswAIswAIswAIswAIswAoLsEL+pSycD8vUkBsntoumoUM2dkyGQAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAGWug1tKvPlBDDaF6vQhI5b5h1zoj1rOsAZW/kZsAALsAALsAALsAALsAALsAALsAALsAALsABLE1gEQRCqMq5sAoIgAIsgCAKwCIIALIIgCMAiCIIALIIgAIsgCEJn/B/u92LX9SrJTQAAAABJRU5ErkJggg==" } } }, "payment_settings": { "back_url": "https://acme.com/api/checkouts/01hp306zyxxznp7tdrwq7dygaf/redirect", "allow_recurring": false } }], "actions": { "approve": "2024-02-07T23:59:53.310721Z" } } }' ``` >Если вы получили ошибку `qr_expired`, это значит, что срок действия QR-кода истек и надо начать заново. ### 6. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Статус `successful` означает успешный платеж. Также в вебхуке будет передан маскированный или полный номер телефона плательщика, в зависимости от настроек приема платежей. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_123456789", "transaction_status": "completed", "created_date": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-08T00:00:06.202928Z", "payments": [{ "id": "pm_12345678", // highlight-next-line "transaction_status": "successful", "created_date": "2024-02-07T23:59:53.160440Z", "completed_date": "2024-02-08T00:00:06.125704Z", "user_info": { "user_id": "lucky", "contact_info": [{ "phone_number": "7965****385" }] }, "participant_info": { "payer_info": { "ipv4_address": "192.168.0.1" } }, "payment_info": { "type": "fps_info", "fps_info": { "money_purpose": "Оплата услуг" }, }, "sum_info": { "sum": 1000, "currency_code": "RUB" }, "payment_settings": { "back_url": "https://acme.com/api/checkouts/01hp306zyxxznp7tdrwq7dygaf/redirect", "allow_recurring": false } }], "actions": { "approve": "2024-02-07T23:59:53.310721Z", "finalize": "2024-02-08T00:00:05.967084Z" }, "transaction_info": { "fps_transaction_id": "A50581324524670W0000040011450701" } } }' ``` [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) #### Схема оплаты через СБП ![](/img/docs/payments/fps_ru.png) --- ## Рекуррентные платежи через СБП - [Рекуррентные платежи через СБП](https://docs.zetplat.com/checkouts/recurring-fps): Регулярные списания через СБП. API Zetplat позволяет: - получить токен для рекуррентных платежей через СБП [со списанием средств](#with_charge), - получить токен для рекуррентных платежей через СБП [без списания средств](#no_charge). ## Как получить токен со списанием средств ### 1. Создайте платежную сессию Отправьте запрос на создание сессии [`transaction/initiate`](/spec/methods#transactioninitiate). В ответе придет идентификатор платежной сессии. ### 2. Начните платеж Отправьте запрос на проведение платежа [`transaction/start/checkout`](/spec/methods#transactionstartcheckout). ### 3. Дождитесь вебхука для платежа Zetplat отправит вам вебхук [`approve_pending`](/spec/webhooks#approve_pending) и будет ждать подтверждения или отмены. ### 4. Подтвердите или отмените платеж Проверьте данные для платежа, а затем подтвердите или отмените его: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). ### 5. Выполните дополнительные действия Дождитесь вебхука [`action_pending`](/spec/webhooks#action_pending). В параметре `user_action.payment_qr.qr_data.qr_content`передается диплинк на оплату. Его можно показать плательщику в виде QR-кода или отправить по нему плательщика в приложение банка-эмитента. ### 6. Дождитесь результата платежа Zetplat отправит вам вебхук [`checkout_results`](/spec/webhooks#checkout_results). Если платеж успешен, в вебхуке будут переданы значения `status=completed` (объект `session_info`) и `status=successful` (массив `payouts`), а в параметре `recurring_token_info.token` будет передан токен для последующих оплат. Если платеж неуспешен, в вебхуке будут переданы значения `status=canceled` (объект transaction) и `status=unsuccessful` (массив `payouts`), а рекуррентного токена не будет. Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_713610", // highlight-next-line "transaction_status": "completed", "created_date": "2024-08-08T08:06:51.841432Z", "updated_at": "2024-08-08T08:14:56.168219Z", "payments": [{ "id": "pm_308906", // highlight-next-line "transaction_status": "successful", "created_date": "2024-08-08T08:06:51.931193Z", "completed_date": "2024-08-08T08:14:55.996273Z", "user_info": { "user_id": "user123", "contact_info": [{ "phone_number": "7123****345" }] }, "payment_info": { "type": "fps_info" }, "recurring_token_info": { // highlight-next-line "token": "6a6a29c4193a8e1049231e1497a3c5f180e120b20db81b39f53ec478029b53cf", "created_date": "2024-08-08T10:10:27+03:00", "completed_date": "2034-08-08T10:10:27+03:00", "token_active": true, "type": "recurring_token" }, "sum_info": { "sum": 1000, "currency_code": "RUB" }, "fee_info": { "net": { "sum": 1000, "currency_code": "RUB" }, "gross": { "sum": 1000, "currency_code": "RUB" } } }], "actions": { "approve": "2024-08-08T08:06:52.184593Z", "finalize": "2024-08-08T08:14:55.699095Z" } } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_713610", // highlight-next-line "transaction_status": "canceled", "created_date": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payments": [{ "id": "pm_308906", // highlight-next-line "transaction_status": "unsuccessful", "created_date": "2022-03-01T11:57:31.895773Z", "completed_date": "2022-03-01T11:57:31.895773Z", "user_info": { "user_id": "user123" }, "payment_info": { "type": "fps_info" }, "sum_info": { "sum": 229600, "currency_code": "RUB" }, "fee_info": { "fee": { "merchant_fee": { "sum": 1607, "currency_code": "RUB" } } }, "extra_info": { "parent_session_id": "ps_1667788995" }, "error": { "error_description": "QR expired", "error_code": "qr_expired" }, "payment_settings": { "back_url": "https://zetplat.com", "allow_recurring": false } }], "error": { "error_description": "Session cancelled", "error_code": "session_cancelled" }, "actions": { "approve": "2022-03-01T11:57:31.895773Z" } } }' ``` #### Схема привязки счета к СБП ![](/img/docs/payments/recurring_fps_ru.png) ## Как получить токен без списания средств Чтобы получить токен для рекуррентных платежей через СБП без фактического списания денег, выполните [стандартные шаги по проведению платежа через СБП](#with_charge). При создании запроса [`transaction/initiate`](/spec/methods#transactioninitiate) укажите `"type": "faster_payment_system_binding"` и `"allow_recurring": true`. В объекте `sum_info` укажите любое положительное числом (например, 1 рубль). В этом случае значение объекта игнорируется, и сумма списана не будет. Токен для рекуррентных платежей вернется в вебхуке `checkout_results`. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_info": { // highlight-next-line "type": "faster_payment_system_binding" }, // highlight-next-line "sum_info": { "sum": 100, "currency_code": "rub" }, "user_info": { "user_id": "lucky" }, "payment_settings": { // highlight-next-line "allow_recurring": true } }' ``` Когда получите токен, принимайте рекуррентные платежи стандартным образом. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_info": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" } }' ``` [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) --- ## Возвраты платежей - [Возвраты платежей](https://docs.zetplat.com/checkouts/payment-refund): Возврат денег по успешным платежам. Успешный платеж может быть возвращен пользователю двумя способами: - в рамках операции **refund** — это наиболее распространенный случай, платеж может быть возвращен полностью или частично; - в рамках процедуры **chargeback** — партнер не может инициировать ее самостоятельно, уведомление приходит от Zetplat, сумма списывается из возмещения. Записи о **refund** и **chargeback** заносятся в [реестры](/logs/daily-payment-report). ## Как провести возврат платежа ### 1. Создайте возврат >Отправить запрос можно только на **refund**, но не на **chargeback**. Отправьте запрос [`transaction/refund`](/spec/methods#transactionrefund). В поле `session_id` передайте идентификатор [платежной сессии](/spec/objects#payment_session) из платежа, который нужно вернуть. В поле `sum_info.sum` укажите сумму возврата. Если не укажете, сумма платежа вернется полностью. Пример ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/refund \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230" }' ``` ### 2. Дождитесь результата возврата Zetplat отправит вам вебхук [`checkout_refunded`](/spec/webhooks#checkout_refunded). Статус `successful` означает успешный возврат. Пример ```json showLineNumbers curl - X POST \ https: //partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_refunded", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_2705", // highlight-next-line "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "sum_info": { "sum": 1000, "currency_code": "rub" }, "extra_info": "good", // highlight-start "moneyback": [{ "id": "rf_203", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "sum_info": { "sum": 1000, "currency_code": "rub" } }], // highlight-end "transaction_info": { "fps_transaction_id": "A50581324524670W0000040011450701" } }] } }' ``` [Подробнее о статусах платежа](/spec/objects#payment_status) [Описание кодов ошибок и их значений](/spec/errors) --- ## Виджет платежной формы - [Виджет платежной формы](https://docs.zetplat.com/iframe/payment-widget): Встраиваемая JS-форма для приёма платежей с настройкой внешнего вида и текстов. Виджет платежной формы позволяет провести оплату. Добавьте виджет на страницу, и дальше пользователь взаимодействует с виджетом. [Как провести платеж через форму оплаты](/checkouts/payment-with-form.mdx) ```html showLineNumbers Виджет платежной формы document.addEventListener('DOMContentLoaded', function () { if (!window.ZetplatPaymentForm) { return; } const paymentForm = new ZetplatPaymentForm('publicToken', { isCvcMasked: true, customerInteractionRedirect: { target: "_blank", }); paymentForm.render(); }); ``` ## Как добавить виджет на страницу #### 1. Подключите скрипты и стили ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Добавьте контейнер с виджетом ```html showLineNumbers ``` #### 3. Создайте экземпляр виджета После подключения скрипта к странице в глобальной области видимости появится класс `ZetplatPaymentForm`. Для создания платежной формы передайте в конструктор публичный токен, полученный для работы с этим виджетом. ```js showLineNumbers const paymentForm = new ZetplatPaymentForm('public token'); ``` Для отображения платежной формы вызовите метод `render()`: ```js showLineNumbers paymentForm.render(); ``` ## API виджета ### `ZetplatPaymentForm` Конструктор класса платежной формы. ```js showLineNumbers const paymentForm = new ZetplatPaymentForm(publicToken[, options]) ``` | Параметр | Тип | Описание | | ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `publicToken` | string | Публичный токен (обязательный) | | `options` | object | Дополнительные настройки | | `options.container` | HTMLElement | Контейнер, в который будет вставлена форма. Значение по умолчанию: `` | ### Метод `paymentForm.render()` Метод отображает форму на странице, в контейнере, определенном параметром `options.container`. ```js showLineNumbers paymentForm.render([options]) ``` | Параметр | Тип | Описание | | ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `options` | object | Дополнительные настройки | | `options.container` | HTMLElement | Контейнер, в который будет вставлена форма. Значение по умолчанию: `` | ### Обработчик события `paymentForm.onReady` Обработчик события готовности формы к работе. ```js showLineNumbers paymentForm.onReady = function () { /* обработчик */ } ``` ### Обработчик события `paymentForm.onPaymentStart` Обработчик события при старте процесса оплаты. ```js showLineNumbers paymentForm.onPaymentStart = function () { /* обработчик */ } ``` ### Обработчик события `paymentForm.onPaymentSuccess` Обработчик события при успешном завершении процесса оплаты. ```js showLineNumbers paymentForm.onPaymentSuccess = function () { /* обработчик */ }; ``` ### Обработчик события `paymentForm.onPaymentFail` Обработчик события при неуспешном завершении процесса оплаты. ``` js showLineNumbers paymentForm.onPaymentFail = function (error) { /* обработчик */ } ``` ### Обработчик события `paymentForm.onDestroy` Обработчик события закрытия формы. ```js showLineNumbers paymentForm.onDestroy = () => { /* обработчик */ } ``` ## Настройка виджета ### Маскировка кода CVV/CVC при вводе Вы можете настроить поле ввода кода CVV/CVC таким образом, чтобы пользователь при вводе видел только последнюю введенную цифру, а остальные введенные цифры отображались как *. Для этого добавьте в конструктор класса платежной формы флаг `isCvcMasked`: ``` js showLineNumbers const paymentForm = new ZetplatPaymentForm('publicToken', { isCvcMasked: true, }); ``` ### Управление открытием окна 3DS Вы можете открыть окно 3DS для пользователя несколькими способами с помощью параметра `target` объекта `customerInteractionRedirect`: - `_blank` - в новой вкладке, - `_self` - в том же фрейме, - `_parent` - во фрейме выше уровнем, если фреймы вложены один в другой, - `_top` - поверх всех фреймов. Значение по умолчанию: `_top`. >Обратите внимание: >- Мы не рекомендуем использовать значение `_self` из соображений безопасности. >- Если вы используете значение `_blank`, пользователю будет нужно разрешить всплывающие окна в браузере или перейти по ссылке из окна виджета. ### Скрытие поля имени владельца карты Чтобы скрыть поле **Cardholder**, передайте параметр `hideCardHolderField: true`. По умолчанию поле отображается. ### Внешний вид Подключив собственные стили после стилей библиотеки, вы можете таким образом переопределить их. ```html showLineNumbers ``` ```css showLineNumbers /* custom-styles.css */ .zetplat-Field__label { color: green; } ``` > Настроить внешний вид значений, которые вводятся в форму внутри iframe, пока нельзя. Позже такая возможность появится. Также есть возможность отредактировать текстовое содержимое различных элементов виджета оплаты. Можно поменять: - метки полей ввода, - тексты плейсхолдеров, - тексты ошибок, - тексты подписей под полями ввода, - метки кнопок, - текст футера. Для этого надо передать объект `options` с параметрами элементов виджета в конструкторе класса платежной формы [ZetplatPaymentForm](#zetplatpaymentform). | Элемент виджета | Параметр | Тип | Значение по умолчанию | | ---------------------------------------------------------------------------------- | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | Настройка текстов виджета | `texts` | object | | | Экран неуспешной оплаты | `failedPaymentScreen` | string | `Error` | | Форма оплаты | `paymentForm` | object | | | Кнопка оплаты | `buttonPayLabel` | string | `Pay` | | Метка поля держателя карты | `cardholderLabel` | string | `Cardholder` | | Подсказка к полю держателя карты | `cardholderNote` | string | отсутствует | | Плейсхолдер поля держателя карты | `cardholderPlaceholder` | string | `Full name` | | Метка поля номера карты | `cardNumberLabel` | string | `Card number` | | Подсказка к полю номера карты | `cardNumberNote` | string | отсутствует | | Плейсхолдер поля номера карты | `cardNumberPlaceholder` | string | `0000 0000 0000 0000` | | Метка поля секретного кода карты | `cvvLabel` | string | `CVC` | | Подсказка к полю секретного кода карты | `cvvNote` | string | отсутствует | | Плейсхолдер поля секретного кода карты | `cvvPlaceholder` | string | `CVC` | | Метка поля срока действия карты | `expireDateLabel` | string | `Expiration date` | | Подсказка к полю срока действия карты | `expireDateNote` | string | `As stated on the card` | | Плейсхолдер поля срока действия карты | `expireDatePlaceholder` | string | `MM/YY` | | Метка чекбокса согласия на автоплатежи | `recurrentLabel` | string | `I agree to recurring payments` | | Согласие с условиями | | | | | Текст предупреждения о согласии с условиями. Разметка `{{#link}}{{/link}}` обязательна, ей выделяется часть фразы, которая будет преобразована в ссылку на соглашение. | `termsAgreement` | string | `By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}` | | Ошибки валидации полей | `validationErrors` | object | | | Ошибка в номере карточного номера | `invalidCardNumber` | string | `Invalid card number` | | Ошибка в секретном коде карты | `invalidCvv` | string | `CVV/CVC has 3 digits` | | Ошибка в сроке действия карты | `invalidExpiryDate` | string | `Invalid date` | | Не заполнено обязательное поле | `isRequired` | string | `Required field` | | Экран процесса оплаты | `paymentProcessScreen` | object | | | Описание экрана процесса оплаты | `description` | string | `Just a moment` | | Заголовок экрана процесса оплаты | `title` | string | `Payment processing...` | | Экран перенаправления на страницу банка (3D Secure) | `redirectionScreen` | object | | | Предложение перейти по ссылке, если автоматического перенаправления не произошло. Разметка `{{#link}}{{/link}}` обязательна, ей выделяется часть фразы, которая будет преобразована в ссылку. | `followTheLink` | string | `If you haven't been redirected automatically, use {{#link}}this link.{{/link}}` | | Заголовок экрана процесса оплаты | `title` | string | `Payment processing...` | | Предупреждение об автоматическом перенаправлении с обратным отсчетом от 3-х секунд.Переменная `{{countdown}}` обязательна, вместо нее подставляется отсчет обратного времени.Разметкой `{{#strong}}{{/strong}}` можно выделить жирным шрифтом счетчик времени | `waitForRedirectToBanksPage` | string | `You will be redirected to the issuer bank's page in {{#strong}}{{countdown}} seconds.{{/strong}}` | | Экран успешной оплаты | `successPaymentScreen` | object | | | Заголовок экрана успешной оплаты | `title` | string | `Payment success` | | Информация о транзакции | `transactionData` | object | | | Метка суммы | `amountLabel` | string | `Amount` | | Метка информации о способе оплаты (тип и маскированный номер карты) | `creditCardLabel` | string | `Card` | | Метка ID транзакции | `transactionIdLabel` | string | `Transaction ID` | | Неизвестная ошибка | `unknownError` | string | `Something went wrong...` | #### Пример кода для изменения текстов: ```javascript showLineNumbers const paymentForm = new ZetplatPaymentForm('', { isCvcMasked: true, texts: { failedPaymentScreen: { title: 'Error', }, paymentForm: { buttonPayLabel: 'Pay', cardholderLabel: 'Cardholder', cardholderNote: '', cardholderPlaceholder: 'Full name', cardNumberLabel: 'Card number', cardNumberNote: '', cardNumberPlaceholder: '0000 0000 0000 0000', cvvLabel: 'CVC', cvvNote: '', cvvPlaceholder: 'CVC', expireDateLabel: 'Expiration date', expireDateNote: '', expireDatePlaceholder: 'As stated on the card', recurrentLabel: 'I agree to recurring payments', termsAgreement: 'By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}', validationErrors: { invalidCardNumber: 'Invalid card number', invalidCvv: 'CVV/CVC has 3 digits', invalidExpiryDate: 'Invalid date', isRequired: 'Required field', }, }, paymentProcessScreen: { description: 'Just a moment', title: 'Payment processing...', }, redirectionScreen: { followTheLink: 'If you haven`t been redirected automatically, use {{#link}}this link.{{/link}}', title: 'Payment processing...', waitForRedirectToBanksPage: 'You will be redirected to the issuer bank`s page in {{#strong}}{{countdown}} seconds.{{/strong}}', }, successPaymentScreen: { title: 'Payment success', }, transactionData: { amountLabel: 'Amount', creditCardLabel: 'Card', transactionIdLabel: 'Transaction ID', }, unknownError: 'Something went wrong...', }, }); ``` ### Ошибки для конечных пользователей При взаимодействии с виджетом, конечные пользователи могут получать ошибки, описанные ниже. | Код ошибки | Описание ошибки | |---------------------------|---------------------------------------------------------------------| | `3DS_error` | Проблемы с прохождением 3DS | | `activity_count_exceeded` | Достигнут лимит по сумме или количеству операций для карты/кошелька | | `bank_card_expired` | Карта просрочена | | `declined_by_issuer_bank` | Банк, выпустивший карту, отклонил операцию | | `insufficient_funds` | Недостаточно средств на карте | --- ## Виджет токенизации карты - [Виджет токенизации карты](https://docs.zetplat.com/iframe/tokenize-widget): Виджет для безопасной токенизации данных карты. С нашим виджетом вы можете безопасно проводить операции с банковскими картами. Подключите виджет на странице в своем сервисе. После взаимодействия пользователя с виджетом, вы получите данные карты в токенизированном виде. Далее проводите выплаты с этим токеном. > Чтобы получить информацию о токене или о карте, используйте метод [`public_token/state`](/spec/reference-methods.mdx#public_tokenstate). Например, чтобы получить последние 4 цифры номера карты и показать пользователю, куда придет выплата. [Как провести выплату на карту через виджет](/transfers/payout-widget.mdx) ```html showLineNumbers Виджет токенизации карточного номера document.addEventListener('DOMContentLoaded', function () { if (!window.ZetplatCardTokenizer) { return; } const cardTokenizer = new ZetplatCardTokenizer('public token'); cardTokenizer.onTokenizationSuccess = function (cardToken) { // Обработка события успешного получения токена }; cardTokenizer.render(); }); ``` ## Как добавить виджет на страницу Для использования виджета подключите на страницу JavaScript-библиотеку и получите публичный токен (с помощью метода [public_token](/spec/reference-methods.mdx#public_token)). #### 1. Подключите скрипты и стили Необходимо подключить скрипт и стили виджета к странице. ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Добавьте контейнер с виджетом ```html showLineNumbers ``` #### 3. Создайте экземпляр виджета После подключения скрипта к странице в глобальной области видимости появится класс `ZetplatCardTokenizer`. Для создания формы токенизации передайте в конструктор публичный токен, созданный для работы с этим виджетом: ```js showLineNumbers const cardTokenizer = new ZetplatCardTokenizer('public token'); ``` Обработайте событие успешного получения токена: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { // ... }; ``` Для отображения формы вызовите метод `render()`: ```js showLineNumbers cardTokenizer.render(); ``` ## API виджета ### `ZetplatCardTokenizer` Конструктор класса формы токенизации. ```js showLineNumbers new ZetplatCardTokenizer(publicToken[, options]) ``` | Параметр | Тип | Описание | |-----------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------| | `publicToken` | string | Публичный токен (обязательный) | | `options` | object | Дополнительные настройки | | `options.container` | HTMLElement | Контейнер, в который будет вставлена форма. Значение по умолчанию: `` | | `options.texts` | object | | | `options.texts.cardNumberLabel` | string | Метка к полю ввода карточного номера. Значение по умолчанию `Card number` | | `options.texts.submitButtonLabel` | string | Метка кнопки токенизации. Значение по умолчанию `Bind card` | ### Метод `cardTokenizer.render()` Метод отображает форму на странице в контейнере, определенном параметром `options.container`. ```js showLineNumbers cardTokenizer.render(); ``` ### Обработчик события `cardTokenizer.onReady` Обработчик события готовности формы к работе. ```js showLineNumbers cardTokenizer.onReady = function () { /* обработчик */ }; ``` ### Обработчик события `cardTokenizer.onTokenizationStart` Обработчик события при старте процесса токенизации. ```js showLineNumbers cardTokenizer.onTokenizationStart = function () { /* обработчик */ }; ``` ### Обработчик события `cardTokenizer.onTokenizationSuccess` Обработчик события при успешном завершении процесса токенизации. ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { /* обработчик */ }; ``` | Параметр | Тип | Описание | |-------------------------------------|--------|---------------------------------------------------------------------------------------| | `cardToken` | object | | | `cardToken.info` | object | Дополнительная информация по карте | | `cardToken.info.card_network` | string | Тип карточной системы. Возможные значения: `visa`, `mastercard`, `mir` | | `cardToken.info.card_type` | string | Тип карты. Дополнительно включает подбренд (`visa_electron`, `maestro`, `mirmaestro`) | | `cardToken.info.masked_card_number` | string | Маскированное значение номера карты, например `424242******4242` | | `cardToken.token` | string | Токен карточного номера | ### Обработчик события `cardTokenizer.onTokenizationFail` Обработчик события при неуспешном завершении процесса токенизации. ```js showLineNumbers cardTokenizer.onTokenizationFail = function (error) { /* обработчик */ }; ``` ## Как настроить виджет ### Внешний вид Подключив собственные стили после стилей библиотеки, вы можете таким образом переопределить их. ```html showLineNumbers ``` ```css showLineNumbers /* custom-styles.css */ .zetplat-Field__label { color: green; } ``` > Настроить внешний вид значения, которое вводится в форму (внутри iframe), пока нельзя. Позже такая возможность появится. ### Тексты Чтобы заменить тексты в форме, используйте параметр `options.texts` в конструкторе [`ZetplatCardTokenizer`](/iframe/widget-tokenize.mdx#zetplatcardtokenizer). --- ## Ежедневный реестр выплат - [Ежедневный реестр выплат](https://docs.zetplat.com/logs/daily-payout-report): CSV-реестр всех выплат за сутки, описание полей. Реестр отправляется в формате CSV по электронной почте, которая указана в вашем договоре с Zetplat. Если вы хотите получать реестры в формате XLSX или другим способом, например по SFTP, свяжитесь с менеджером Zetplat. ## Как использовать реестр В реестре Zetplat присылает перечень всех успешных операций за сутки. Вам необходимо проводить сверку операций на вашей стороне с теми, что есть в реестре. Если вы найдете разногласия с реестром, обязательно сообщите своему менеджеру в Zetplat. Срок, в который можно вносить исправления, указан в вашем договоре с Zetplat. ## Название файла с реестром `_ГГГГ-ММ-ДД-ГГГГ-ММ-ДД` ## Поля в реестре | Название поля | Формат | Описание | Пример | |------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------|-----------------------| | **Payout ID** | string | Идентификатор выплаты в Zetplat | `po_2196490` | | **Payout date** | string (дата в формате YYYY-MM-DD H:I:S) | Дата создания выплаты на стороне Zetplat | `2024-06-21 23:17:55` | | **Payout completed** | string (дата в формате YYYY-MM-DD H:I:S) | Дата завершения выплаты на стороне Zetplat | `2024-06-21 23:17:56` | | **Payout type** | string | [Тип выплаты](#payout_types) | `Advice` | | **Fast payout** | int | Признак срочной выплаты. `0` — обычная выплата, `1` — срочная выплата | `0` | | **Session ID** | string | Идентификатор платежной сессии | `ps_2525018` | | **Additional info** | string | Дополнительные данные, которые вы передавали в запросе на операцию | `"good"` | | **Payment instrument** | string | Платежное средство: маскированный номер карты, номер счета | `420080******8800` | | **Product ID** | string | Идентификатор продукта или услуги по договору с Zetplat | `new_payouts` | | **Transaction amount** | decimal | Полная сумма выплаты с комиссией | `110` | | **Payout amount** | decimal | Сумма выплаты после вычета комиссии | `100` | | **Fee** | decimal | Комиссия Zetplat (`grossLocalAmount - paymentLocalAmount`) | `10` | | **Payout currency** | string | Трехбуквенный код валюты операции (ISO) | `RUB` | | **Fee currency** | string | Валюта комиссии | `RUB` | | **RRN** | string | RRN (Retrieval Reference Number) — уникальный идентификатор транзакции в Zetplat (опциональное поле) | `12345678` | ### Типы выплат - `Advice` — успешная выплата, - `Refund` — возврат успешной выплаты. ## Особенности отправки реестра При необходимости Zetplat также может отправить вам реестр одним из следующих способов: - несколькими файлами в формате CSV или XLSX (файл CSV или XLSX, разбитый на части); - единым файлом архива ZIP (архивированный файл CSV или XLSX); - несколькими файлами ZIP (архивированный файл CSV или XLSX, разбитый на части). Может быть полезно, если ваш почтовый сервер не принимает файлы больше определенного объема. Если для вас это актуально, свяжитесь с вашим менеджером в Zetplat. При большом объеме отправляемых данных Zetplat может самостоятельно принять решение об отправке реестра по частям и/или в архивированном виде. Разбивка реестра на части производится по количеству транзакций. --- ## Ежедневный реестр платежей - [Ежедневный реестр платежей](https://docs.zetplat.com/logs/daily-payment-report): CSV-реестр всех платежей за сутки. Реестр отправляется в формате CSV по электронной почте, которая указана в вашем договоре с Zetplat. Если вы хотите получать реестры в формате XLSX или другим способом, например по SFTP, свяжитесь с менеджером Zetplat. ## Как использовать реестр В реестре Zetplat присылает перечень всех успешных операций за сутки. Вам необходимо проводить сверку операций на вашей стороне с теми, что есть в реестре. Если вы найдете разногласия с реестром, обязательно сообщите своему менеджеру в Zetplat. Срок, в который можно вносить исправления, указан в вашем договоре с Zetplat. ## Название файла с реестром `_ГГГГ-ММ-ДД-ГГГГ-ММ-ДД` ## Поля в реестре | Название поля | Описание | Длина поля | Пример | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------|------------|-----------------------| | **Payment ID** | Идентификатор платежа в Zetplat | 15—32 | `pm_1313` | | **Session ID** | Идентификатор платежной сессии | 0—100 | `ps_3230` | | **Project name** | Название вашего проекта в Zetplat | 2—100 | `acquiring_card` | | **Payment type** | [Тип платежа](#payment_types) | 10—16 | `Advice` | | **Payment amount** | Размер платежа в рублях | 1—12 | `110` | | **Amount due** | Сумма возмещения, которую Zetplat должен вам перечислить. Может быть отрицательной, например, по операциям `Refund` или `Chargeback` | 1—12 | `-2` | | **Fee** | Сумма комиссии Zetplat по договору. Указывается в отрицательном значении | 1—12 | `-2` | | **Payment date** | Дата и время транзакции на стороне Zetplat | 19 | `11.01.2020 00:00:08` | | **Card number** | Маскированный номер карты, по которому был совершен платеж, а также номер кошелька | 9—19 | `4...1878` | | **RRN** | RRN (Retrieval Reference Number) — уникальный идентификатор транзакции в Zetplat (опциональное поле) | 12 | `12345678` | | **Additional info** | Дополнительные данные, которые вы передавали в запросе на операцию | 6—20 | `1Di732vw57` | ### Типы платежей - `Adjustment` — частичная отмена транзакции, - `Advice` — успешная транзакция, - `Refund` — возврат успешной транзакции, - `Recurrent` — [рекуррентный платеж](/checkouts/payment-recurring) (автоплатеж или повтор платежа). ## Особенности отправки реестра При необходимости Zetplat также может отправить вам реестр одним из следующих способов: - несколькими файлами в формате CSV или XLSX (файл CSV или XLSX, разбитый на части); - единым файлом архива ZIP (архивированный файл CSV или XLSX); - несколькими файлами ZIP (архивированный файл CSV или XLSX, разбитый на части). Может быть полезно, если ваш почтовый сервер не принимает файлы больше определенного объема. Если для вас это актуально, свяжитесь с вашим менеджером в Zetplat. При большом объеме отправляемых данных Zetplat может самостоятельно принять решение об отправке реестра по частям и/или в архивированном виде. Разбивка реестра на части производится по количеству транзакций. --- ## Объекты - [Объекты](https://docs.zetplat.com/spec/objects): Все модели данных API: платежи, выплаты, сессии, токены, ошибки. ## `account_info` Описание банковского счета получателя выплаты. | Название | Обязательность | Тип | Описание | |-------------------------|-------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------------| | `payment_system` | + | string | Система банковских платежей. Варианты: `fps_info`, `fps_info_verification` | | `fps_info` | - (обязателен для `payment_system = fps_info`) | object | [Данные получателя в Системе быстрых платежей](/spec/objects#fps_info) | | `fps_info_verification` | - (обязателен для `payment_system = fps_info_verification`) | object | [Данные для проверки регистрации получателя в Системе быстрых платежей](/spec/objects#fps_info_verification) | ## `card_details` Данные карты в открытом виде. | Название | Обязательность | Тип | Описание | |------------------|---------------------------------------------------------|--------|---------------------| | `card_number` | + | string | Номер карты | | `card_exp_month` | - (обязателен для приема платежей при наличии на карте) | string | Месяц | | `card_exp_year` | - (обязателен для приема платежей при наличии на карте) | string | Год | | `card_code` | - (обязателен для приема платежей при наличии на карте) | string | Секретный код CVC | | `name_on_card` | - | string | Имя владельца карты | ## `card_elements` Данные банковской карты для токенизации. | Название | Обязательность | Тип | Описание | |---------------|----------------|--------|----------------------------------------------| | `ref` | + | string | Фиксированное значение, всегда `number` | | `type` | + | string | Фиксированное значение, всегда `card_number` | | `card_number` | + | string | Номер карты | ## `card_info` Данные банковской карты получателя выплаты. | Название | Обязательность | Тип | Описание | |-----------------------|-------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------| | `type` | + (не возвращается в ответе) | string | Тип передачи данных карты. Возможные варианты: `card_details`, `hashed_card_details`, `tokenized_card` | | `card_details` | - (обязателен для `type = card_details`) | object | [Данные карты](/spec/objects#bankcard) | | `hashed_card_details` | - (обязателен для `type = hashed_card_details`) | object | [Шифрованные данные карты](/spec/objects#hashed_card_details) | | `tokenized_card` | - (обязателен для `type = tokenized_card`) | object | [Токенизированный номер карты](/spec/objects#tokenized_card) | | `card_network` | - | string | Информация о карте. Возвращается в уведомлениях, нужна для отображения пользователям | | `card_last4` | - | string | Информация о карте. Возвращается в уведомлениях, нужна для отображения пользователям | | `card_bin` | - | string | Идентификационный номер банка (первые 6 цифр номера карты) | | `card_identifier` | - | string | Сквозной идентификатор карты | | `country_code_alpha3` | - | string | Код страны (ISO 3166-1 alpha-3) | ## `card_token` Токен и данные токенизированной карты. | Название | Обязательность | Тип | Описание | |----------|----------------|--------|----------------------------------------------------| | `token` | + | string | Токен | ## `card_tokenize` Настройки для виджета токенизации. | Название | Обязательность | Тип | Описание | | -------- | -------------- | ---- | ------------------------------------------------------------ | | `allow_tokenization` | + | bool | Может ли этот публичный ключ использовать виджет токенизации | ## `contact_info` Контакты пользователя (получателя выплаты или отправителя платежа). | Название | Обязательность | Тип | Описание | |-----------------|----------------|--------|--------------------------------| | `email_address` | - | string | Электронная почта пользователя | | `phone_number` | - | string | Телефон пользователя | ## `data` Токен и токенизированный номер карты. | Название | Обязательность | Тип | Описание | | -------- | -------------- | ------ | -------- | | `card_token` | + | object | [Данные о токене](/spec/objects#tokenize_number) | ## `destination_info` Данные для редиректа (перенаправления пользователя). | Название | Обязательность | Тип | Описание | |---------------------|----------------|--------------------------|----------------------------------------------------------------| | `url_address` | + | string | Адрес для редиректа вместе с GET-параметрами | | `domain` | + | string | Адрес для редиректа | | `http_method` | + | string | Метод отправки. Возможные значения: `GET`, `POST` | | `additional_params` | - | map<string,string> | Набор параметров в зависимости от способа прохождения операции | | `extra_params` | - | map<string,*> | Набор параметров в зависимости от способа прохождения операции | >- Проверьте, есть ли какие-либо параметры в объектах `additional_params` и `extra_params`. >- Перенаправьте пользователя на адрес из `domain` при помощи метода, указанного в `http_method`, включив все необходимые параметры в URL или в тело запроса. ## `error_info` Описание ошибки. | Название | Обязательность | Тип | Описание | |---------------------|----------------|--------|-----------------| | `error_code` | - | string | Код ошибки | | `error_description` | - | string | Описание ошибки | ## `fps_info` Данные пользователя Системы быстрых платежей при выплатах и платежах. | Название | Обязательность | Тип | Описание | |-------------------|---------------------------|--------|----------------------------------------------| | `phone_number` | - (обязателен для выплат) | string | Телефон получателя выплаты | | `bank_identifier` | - (обязателен для выплат) | string | Идентификатор банка получателя выплаты в СБП | | `money_purpose` | - (обязателен для выплат) | string | Назначение выплаты или платежа | ## `fps_info_verification` Данные для проверки регистрации пользователя в Системе быстрых платежей. | Название | Обязательность | Тип | Описание | |-------------------|----------------|--------|-----------------------------------------------------------------------------------------------------------------------------------| | `phone_number` | + | string | Телефон получателя | | `bank_identifier` | + | string | Идентификатор банка получателя в СБП. Чтобы получить идентификатор, используйте метод [`sbp/banks`](/spec/methods#banks_fps) | ## `fps_widget` Данные для платежной страницы для денежных переводов. | Название | Обязательность | Тип | Описание | | ---------------------------- | -------------- | ------------------------------- | ------------------- | | `session_id` | + | string | Идентификатор платежной сессии | ## `hashed_card_details` Карта с шифрованными полями (токенизированная). Передается при проведении выплаты или оплаты через виджет. | Название | Обязательность | Тип | Описание | |------------------------|----------------|--------|---------------------------| | `hashed_card_number` | + | string | Хэш номера карты | | `hashed_card_exp_date` | - | string | Хэш срока действия | | `hashed_card_code` | - | string | Хэш секретного кода CVC | | `hashed_name_on_card` | - | string | Хэш имени владельца карты | ## `internet_banking` Информация об оплате через платежные системы. | Название | Обязательность | Тип | Описание | |------------|----------------|--------|------------------------------------------------------------------| | `type` | + | string | Платежная система. Возможные значения: `sber_pay` | | `sber_pay` | + | object | [Информация об оплате через SberPay](/spec/objects#sberpay) | ## `moneyback` Информация о возврате. | Название | Обязательность | Тип | Описание | |----------------------|----------------|--------|-------------------------------------------------------------------------------------| | `id` | + | string | Уникальный идентификатор возврата | | `transaction_status` | + | string | Статус возврата. Возможные значения: `in_progress`, `accepted`, `declined`, `error` | | `sum_info` | + | object | [Сумма возврата](/spec/objects#sum_info) | | `created_date` | + | string | Дата создания | | `completed_date` | - | string | Дата завершения | | `chargeback` | - | bool | Показывает, совершен ли возврат в рамках чарджбека | | `transaction_info` | - | object | [Данные о транзакции](/spec/objects#transaction_info) | #### Статусы возврата (`transaction_status`) - `in_progress` — в обработке; - `accepted` — возврат прошел успешно; - `declined` — Zetplat отклонил возврат; - `error` — возврат не прошел из-за ошибки. ## `participant_info` Данные об участниках выплаты. | Название | Обязательность | Тип | Описание | |--------------|----------------|--------|-----------------------------------------------------| | `payer_info` | - | object | [Данные отправителя](/spec/objects#payer_info) | | `payee_info` | - | object | [Данные получателя](/spec/objects#payee_info) | ## `payee_info` Данные получателя. Набор необходимых данных зависит от способа получения выплаты. | Название | Обязательность | Тип | Описание | |-----------------------|--------------------------------------------------------------------------------------------|--------|-------------------------------------------| | `full_name` | - (обязательно при выплатах на любые карты) | string | Полное имя | | `given_name` | - | string | Имя | | `family_name` | - | string | Фамилия | | `patronymic` | - | string | Отчество | | `legal_name` | - | string | Название компании | | `user_id` | - | string | Идентификатор получателя на вашей стороне | | `tax_id` | - | string | Идентификатор налогоплательщика | | `beneficiary_id` | - (обязательно при платежах и выплатах, у которых есть бенефициар или выгодоприобретатель) | string | ИНН бенефициара или выгодоприобретателя | | `country_code_alpha3` | - | string | Страна (ISO-3166-1 alpha-3) | ## `payer_info` Данные отправителя. Набор необходимых данных зависит от способа получения выплаты. | Название | Обязательность | Тип | Описание | |-----------------------|-----------------------------------------------------------------------------------------|--------|-------------------------------------------| | `full_name` | - | string | Полное имя | | `given_name` | - | string | Имя | | `family_name` | - | string | Фамилия | | `patronymic` | - | string | Отчество | | `legal_name` | - | string | Название компании | | `user_id` | - | string | Идентификатор получателя на вашей стороне | | `tax_id` | - | string | Идентификатор налогоплательщика | | `beneficiary_id` | - (обязателен для платежей и выплат, у которых есть бенефициар или выгодоприобретатель) | string | ИНН бенефициара или выгодоприобретателя | | `country_code_alpha3` | - | string | Страна (ISO-3166-1 alpha-3) | | `ipv4_address` | - | string | IPv4-адрес устройства отправителя | | `ipv6_address` | - | string | IPv6-адрес устройства отправителя | ## `payment_form_config` Настройки виджета платежной формы для проведения платежей банковской картой. | Название | Обязательность | Тип | Описание | |-----------------------|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Идентификатор платежной сессии, по которой будет производиться оплата | | `show_autopay_option` | - | bool | Нужно ли отображать в интерфейсе виджета чекбокс **Соглашаюсь на автоплатежи** | | `succeeded_url` | - | string | URL, на который нужно перенаправить пользователя после успешного платежа | | `failed_url` | - | string | URL, на который нужно перенаправить пользователя после ошибки при оплате | | `show_hold_message` | - | bool | Нужно ли показывать плательщику сообщение об успешном платеже на этапе холдирования. По умолчанию `false` и виджет показывает экран загрузки до завершения холда | | `redirect_option` | - | string | Правило, как будет открываться ссылка при редиректе после платежа:- `top` — поверх всех фреймов, - `self` — в том же фрейме, - `parent` — во фрейме выше уровнем, если фреймы вложены один в другой. Значение по умолчанию: `top` | ## `payment_info` Описание способа проведения платежа. | Название | Обязательность | Тип | Описание | |------------------------|---------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Тип способа оплаты. Возможные варианты: `card_info`, `recurring_token_info`, `fps_info`, `faster_payment_system_binding` | | `card_info` | - (обязателен для `type = card_info`) | object | [Данные банковской карты](/spec/objects#card) | | `recurring_token_info` | - (обязателен для `type = recurrent`) | object | [Данные для повтора платежа по токену](/spec/objects#recurrent) | | `fps_info` | - (обязателен для `type = fps_info`) | object | [Данные для платежа по СБП](/spec/objects#fps_info) | ## `payment_qr` Информация о способе платежа. | Название | Обязательность | Тип | Описание | | -------- | -------------- | --------------------------------------- | ----------------------------------- | | `qr_data` | - | object | [QR-код для оплаты по СБП](/spec/objects#qr_inform_interaction) | ## `payments` Все данные платежа. | Название | Обязательность | Тип | Описание | |------------------------|----------------|--------|----------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Уникальный идентификатор платежа | | `transaction_status` | + | string | Статус платежа. Возможные варианты: `successful`, `ongoing`, `pending`, `unsuccessful` | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `payment_info` | + | object | [Платежные данные](/spec/objects#payment_info) | | `sum_info` | + | object | [Сумма](/spec/objects#sum_info) | | `completed_date` | - | string | Дата завершения в формате ISO 8601 | | `user_info` | + | object | [Данные пользователя (отправителя платежа)](/spec/objects#user_info) | | `recurring_token_info` | - | object | [Токен для проведения рекуррентных платежей](/spec/objects#recurrent_token_info) | | `participant_info` | - | object | [Данные об участниках](/spec/objects#participant_info) | | `moneyback` | - | array | [Список возвратов](/spec/objects#moneyback) | | `user_action` | - | object | [Данные для взаимодействия с пользователем](/spec/objects#user_action) | | `transaction_info` | - | object | [Данные о транзакции](/spec/objects#transaction_info) | | `extra_info` | - | object | Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках | | `error_info` | - | object | [Описание ошибки](/spec/objects#error_info) |   #### Статусы платежа (`transaction_status`) - `ongoing` — в обработке; - `pending` — ожидает вашего подтверждения ([`transaction/approve`](/spec/methods#transactionapprove)) или отмены ([`transaction/cancel`](/spec/methods#transactioncancel)); - `successful` — оплата прошла успешно; - `unsuccessful` — оплата не прошла из-за ошибки. ## `payment_settings` Параметры для проведения платежа. | Название | Обязательность | Тип | Описание | |-------------------|----------------|--------|-----------------------------------------------------------------------------------------------------| | `back_url` | - | string | URL, на который нужно перенаправить пользователя после проведения платежа. URL должен быть валидным | | `allow_recurring` | - | bool | Нужно ли провести платеж с помощью сохраненного токена | ## `payout_info` Описание способа получения выплаты. | Название | Обязательность | Тип | Описание | |------------------------|--------------------------------------------|--------|----------------------------------------------------------------------------------------------------------| | `type` | + | string | Тип способа получения выплаты. Возможные варианты: `card_info`, `recurring_token_info`, `tokenized_card` | | `card_info` | - (обязателен для `type = card_info`) | object | [Банковская карта получателя](/spec/objects#card) | | `recurring_token_info` | - (обязателен для `type = recurrent`) | object | [Данные токена](/spec/objects#recurrent) | | `tokenized_card` | - (обязателен для `type = tokenized_card`) | object | [Токенизированный номер карты](/spec/objects#tokenized_card) | ## `payouts` Все данные выплаты. | Название | Обязательность | Тип | Описание | |----------------------|----------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Идентификатор выплаты | | `transaction_status` | + | string | Статус. Возможные варианты: `successful`, `ongoing`, `pending`, `unsuccessful` | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `payout_info` | + | object | [Способ получения выплаты](/spec/objects#payout_info) | | `sum_info` | + | object | [Сумма](/spec/objects#sum_info) | | `completed_date` | - | string | Дата завершения в формате ISO 8601 | | `user_info` | - | object | [Данные получателя в вашей системе](/spec/objects#user_info). Например, логин, по которому вы сможете идентифицировать получателя на своей стороне | | `participant_info` | - | object | [Данные об участниках выплаты](/spec/objects#participant_info). Например, имя и адрес отправителя и получателя | | `moneyback` | - | array | [Список возвратов](/spec/objects#moneyback) | | `transaction_info` | - | object | [Данные о транзакции](/spec/objects#transaction_info) | | `extra_info` | - | object | Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках | | `error_info` | - | object | [Описание ошибки](/spec/objects#error_info) |   #### Статусы выплаты (`transaction_status`) - `ongoing` — в обработке; - `pending` — ожидает вашего подтверждения ([`transaction/approve`](/spec/methods#transactionapprove)) или отмены ([`transaction/cancel`](/spec/methods#transactioncancel)); - `successful` — выплата прошла успешно; - `unsuccessful` — выплата не прошла из-за ошибки. ## `public_token` Публичный токен. | Название | Обязательность | Тип | Описание | | -------- | -------------- | ------ | -------- | | `token` | + | string | Токен | ## `qr_data` QR-код для оплаты по СБП. | Название | Обязательность | Тип | Описание | |--------------|----------------|--------|--------------------| | `qr_content` | + | string | Ссылка на QR-код | | `qr_image` | + | string | Содержимое QR-кода | ## `recurring_token` Токен для рекуррентных платежей и выплат. | Название | Обязательность | Тип | Описание | | -------- | -------------- | ------ | -------- | | `token` | + | string | Токен | ## `recurring_token_info` (токен для рекуррентных платежей и выплат) Токен для рекуррентных платежей и выплат. Входит в объекты: [`payout_info`](/spec/objects#payout_info), [`payment_info`](/spec/objects#payment_info). | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|--------------------------------------------------------------------------------------------------------------| | `token` | + | string | Токен | | `initiated_by` | - | string | Вид рекуррентного платежа. Возможные значения: `merchant` — платеж MIT (по умолчанию), `client` — платеж CIT | ## `recurring_token_info` (информация о токене для рекуррентных платежей и выплат) Информация о токене для рекуррентных платежей и выплат. Входит в объекты: [`payments`](/spec/objects#payments). | Название | Обязательность | Тип | Описание | |------------------|----------------|--------|--------------------------------------------------------------------------------------------------------------| | `token` | + | string | Токен | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `completed_date` | + | string | Дата завершения в формате ISO 8601 | | `token_active` | + | bool | Можно ли проводить операции по этому токену: `true` — можно,  `false` — нельзя | | `initiated_by` | - | string | Вид рекуррентного платежа. Возможные значения: `merchant` — платеж MIT (по умолчанию), `client` — платеж CIT | | `type` | + | string | Вид токена. Всегда: `recurring_token` | ## `sber_pay` Информация для оплаты через SberPay. | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|-----------------------------------------------------------------------------------| | `phone_number` | - | string | Номер телефона для отправки PUSH или СМС. Формат: `7**********` | | `channel` | + | enum | Канал приема оплаты через SberPay. Возможные значения: `app`, `web_mobile`, `web` | ## `sum_info` Сумма. | Название | Обязательность | Тип | Описание | |-----------------|----------------|--------|------------------------------------------------------------------------------------------------------------| | `sum` | + | int | Значение суммы в минорных единицах валюты (в копейках). Если сумма платежа 100 рублей, передавайте `10000` | | `currency_code` | + | string | Код валюты согласно ISO 4217. Регистр не важен. Варианты: `rub`, `eur` | ## `token_info` (токенизированная карта) Данные о токенизированной банковской карте. Возвращается в ответ на запрос [`public_token/state`](/spec/methods#public_tokenstate). | Название | Обязательность | Тип | Описание | |----------------------|----------------|--------|--------------------------------------| | `hashed_card_number` | + | string | Токен (токенизированный номер карты) | | `card_network` | + | string | Платежная система, например `visa` | | `card_last4` | + | string | Последние 4 цифры номера карты | | `type` | + | string | Вид токена. Всегда: `card_info` | ## `token_info` (публичный токен) Информация о публичном токене. Возвращается в ответ на запрос [`public_token/state`](/spec/methods#public_tokenstate). | Название | Обязательность | Тип | Описание | |------------------|----------------|--------|--------------------------------------------------------------------------------| | `token` | + | string | Токен | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `completed_date` | + | string | Дата завершения в формате ISO 8601 | | `token_active` | + | bool | Можно ли проводить операции по этому токену: `true` — можно,  `false` — нельзя | | `type` | + | string | Вид токена. Всегда: `public_token` | ## `token_info` (токен для рекуррентных платежей и выплат) Информация о токене для [рекуррентных платежей](/checkouts/payment-recurring) и выплат. Возвращается в ответ на запрос [`public_token/state`](/spec/methods#public_tokenstate). | Название | Обязательность | Тип | Описание | |------------------|----------------|--------|--------------------------------------------------------------------------------------------------------------| | `token` | + | string | Токен | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `completed_date` | + | string | Дата завершения в формате ISO 8601 | | `token_active` | + | bool | Можно ли проводить операции по этому токену: `true` — можно,  `false` — нельзя | | `initiated_by` | - | string | Вид рекуррентного платежа. Возможные значения: `merchant` — платеж MIT (по умолчанию), `client` — платеж CIT | | `type` | + | string | Вид токена. Всегда: `recurring_token` | ## `tokenized_card` Токенизированный номер карты. | Название | Обязательность | Тип | Описание | | -------- | -------------- | ------ | -------- | | `token` | + | string | Токен | ## `session_info` Данные обо всех операциях, которые проводились в рамках одной платежной сессии. Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей). | Название | Обязательность | Тип | Описание | |----------------------|----------------|--------|---------------------------------------------------------------------------------------------------------------| | `id` | + | string | Идентификатор сессии | | `transaction_status` | + | string | [Статус сессии](#session-status) | | `created_date` | + | string | Дата создания в формате ISO 8601 | | `updated_at` | + | string | Дата обновления в формате ISO 8601 | | `payouts` | - | array | [Список выплат в рамках сессии](/spec/objects#payouts) | | `payments` | - | array | [Список платежей в рамках сессии](/spec/objects#payments) | | `next_step` | - | string | [Ожидаемые действия](#expected_action) | | `error_info` | - | object | [Описание ошибки](/spec/objects#error_info) | #### Статусы платежной сессии (`transaction_status`) - `created` — сессия создана, ожидает старта или отмены; - `in_progress` — в обработке; - `accepted` — успешно завершена; - `cancelled` — отменена; - `error` — в процессе работы произошла непредвиденная ошибка. >Внимание! Данный статус не является финальным. Обратитесь в поддержку Zetplat и дождитесь финального статуса транзакции. #### Ожидаемые действия (`next_step`) Если это поле не пустое, значит, Zetplat ждет от вас определенных действий, чтобы продолжить операцию: - `confirm` — вам нужно подтвердить операцию ([`transaction/approve`](/spec/methods#transactionapprove)) или отменить ее ([`transaction/cancel`](/spec/methods#transactioncancel)); - `capture` — вам нужно провести списание ([`transaction/finalize`](/spec/methods#transactionfinalize)) или отменить его ([`transaction/cancel`](/spec/methods#transactioncancel)). ## `transaction_info` Информация о транзакции. | Название | Обязательность | Тип | Описание | |------------------------|----------------|--------|----------------------------------------------------------------------------| | `retrieval_ref_number` | - | string | Уникальный идентификатор транзакции (Retrieval Reference Number) | | `acquirer_ref_number` | - | string | Уникальный номер операции с кредитными картами (Acquirer Reference Number) | | `authorization_code` | - | string | Код авторизации | | `fps_transaction_id` | - | string | Уникальный идентификатор операции в СБП | ## `user_action` Описание взаимодействия с пользователем. | Название | Обязательность | Тип | Описание | |--------------------|----------------------------------------------|--------|---------------------------------------------------------------------------------------------| | `type` | + | string | Тип взаимодействия с пользователем. Возможные значения: `destination_info`, `payment_qr` | | `destination_info` | - (обязателен для `type = destination_info`) | object | [Данные для перенаправления пользователя](/spec/objects#customer_interaction_redirect) | | `payment_qr` | - (обязателен для `type = payment_qr`) | object | [Информация о способе платежа](/spec/objects#payment_qr) | ## `user_info` Данные о пользователе (получателе выплаты или отправителе платежа) в вашей системе. Например, логин, по которому вы сможете идентифицировать пользователя, и его контактная информация. | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|-----------------------------------------------------------------------------------------------------------| | `user_id` | + | string | Идентификатор пользователя (получателя выплаты или отправителя платежа) в вашей системе (до 128 символов) | | `contact_info` | - | array | [Список контактов пользователя](/spec/objects#customer_contact) | ## `wallet_balance_info` Данные о вашем балансе (счете обеспечения) для отправки выплат. | Название | Обязательность | Тип | Описание | |------------|----------------|--------|------------------------------------------------------------| | `id` | + | string | Идентификатор баланса | | `sum_info` | + | object | [Текущий баланс](/spec/reference-objects.mdx#sum_info) | --- ## Методы - [Методы](https://docs.zetplat.com/spec/methods): Полное описание всех эндпоинтов API. При обработке запросов проверяется корректность входных параметров, наличие [необходимых заголовков](/api-rules/signature), права на выполнение действий. ## Проведение операций ### `public_token` #### Генерация публичного токена для работы с виджетами Токен нужен для доступа к JavaScript-библиотеке Zetplat. Вы можете сгенерировать его этим запросом и использовать для работы с виджетами. Токен действителен 24 часа. Его можно использовать для одной операции. При отправке запроса следует передать параметры для работы с виджетами, которые вы собираетесь использовать с этим токеном. #### Адрес для отправки запроса `/api/v1/public_token` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-------------------------|----------------|--------|---------------------------------------------------------------------------------| | `card_tokenize` | - | object | [Данные для работы виджета токенизации](/spec/objects#tokenizewidget) | | `payment_form_config` | - | object | [Данные для работы виджета платежной формы](/spec/objects#acquiringwidget) | | `fps_widget` | - | object | [Данные для платежной страницы](/spec/objects#fps_widget) | Пример запроса Пример запроса на создание токена для проведения платежа с оплатой через платежную форму ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_form_config": { "session_id": "ps_3230" } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|-------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `public_token` | - | string | Публичный токен | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } ``` Пример неуспешного ответа ```json showLineNumbers { "status": "error", "error": { "error_description": "payment_form_config.session_id.not_unique", "error_code": "invalid_request" } } ``` ### `recurring_token/disable` #### Отключение токена С помощью этого запроса можно отключить токен. Отправьте в запросе токен, в ответ придет `token_active: false`. Это значит, что с этим токеном больше нельзя проводить рекуррентные платежи. > После отключения токена в параметре даты окончания действия токена `completed_date` может появиться дата, относящаяся к 2000 году — она ни на что не влияет, можно не обращать на неё внимание. #### Адрес для отправки запроса `/api/v1/recurring_token/disable` #### Параметры запроса | Название | Обязательность | Тип | Описание | | --------- | -------------- | ----------------------------------------------------------------- | ----------------------------------------- | | `recurring_token_info` | + | object | [Токен, который нужно отключить](/spec/objects#recurrent) | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/recurring_token/disable \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "recurring_token_info": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427" } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-------------|----------------|--------|------------------------------------------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `recurring_token_info` | + | object | [Информация о токене для рекуррентных платежей](/spec/objects#recurrent_token_info) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "recurring_token_info": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_date": "2020-07-14T13:17:11+03:00", "completed_date": "2020-07-31T16:05:42+03:00", "token_active": false, "type": "recurring_token" }, "status": "ok" } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/cancel` #### Отмена операции Этот запрос можно отправлять, когда Zetplat готов провести операцию — выплату или платеж. Например, вы получили вебхук `approve_pending` или `finalization_pending`. Если не хотите проводить эту операцию, можете ее отменить: отправьте запрос `transaction/cancel`. Если всё в порядке, отправьте запрос на подтверждение операции (`transaction/approve`) или на списание замороженной суммы (`transaction/finalize`). #### Адрес для отправки запроса `/api/v1/transaction/cancel` #### Параметры запроса | Название | Обязательность | Тип | Описание | | ---------- | -------------- | ------ | -------------------- | | `session_id` | + | string | Идентификатор сессии | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/cancel \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payouts": [{ "id": "po_1313", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/finalize` #### Списание захолдированной суммы Этот запрос можно использовать, если вы отправляете холдированные платежи. Такой платеж проходит в две стадии: сначала деньги замораживаются (например, на банковской карте пользователя), а потом списываются по вашей команде. Запрос можно отправлять, когда Zetplat готов списать деньги и прислал вам вебхук `finalization_pending`. Если вы хотите списать замороженную сумму, отправьте запрос `transaction/finalize`. Можно списать замороженную сумму полностью или частично. Чтобы отменить списание, отправьте `transaction/cancel`. #### Адрес для отправки запроса `/api/v1/transaction/finalize` #### Параметры запроса | Название | Обязательность | Тип | Описание | | -------------- | -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Идентификатор сессии Zetplat | | `sum_info` | - | object | [Сумма к списанию](/spec/objects#sum_info). Может быть меньше замороженной, но обязательно больше 0. Если параметр отсутствует, то замороженная сумма будет списана полностью | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/finalize \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_1313", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "sum_info": { "sum": 10000, "currency_code": "usd" }, "moneyback": [{ "id": "rf_23", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "sum_info": { "sum": 10000, "currency_code": "usd" } }] }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/approve` #### Подтверждение операции Этот запрос можно отправлять, когда Zetplat готов провести операцию — выплату или платеж. Например, вы получили вебхук `approve_pending`. Вам нужно проверить параметры операции и принять решение. Если всё в порядке, подтвердите операцию: отправьте Zetplat `transaction/approve`. Если что-то не так, отмените операцию: отправьте запрос [`transaction/cancel`](/spec/methods#transactioncancel). #### Адрес для отправки запроса `/api/v1/transaction/approve` #### Параметры запроса | Название | Обязательность | Тип | Описание | |------------|----------------|--------|----------------------| | `session_id` | + | string | Идентификатор сессии | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/approve \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payouts": [{ "id": "po_1313", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/initiate` #### Создание платежной сессии Этот запрос создает платежную сессию на стороне Zetplat. Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей). Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или оплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату. >Если вы готовы сразу передать параметры для платежа или выплаты, вы можете это сделать. >Для платежа передайте: `payment_info`, `sum_info`, `user_info`. >Для выплаты передайте: `payout_info`, `sum_info`. В ответе возвращаются параметры созданной сессии. #### Адрес для отправки запроса `/api/v1/transaction/initiate` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-----------------------|----------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | `payout_info` | - | object | [Платежные данные](/spec/objects#payout_info) (карта, банковский счет и др.) | | `payment_info` | - | object | [Платежные данные](/spec/objects#payment_info) | | `sum_info` | - | object | [Сумма](/spec/objects#sum_info). Передается в минорных единицах. Если отправляете 100 рублей, евро или долларов США, нужно передать `10000` | | `participant_info` | - | object | [Информация об участниках операции](/spec/objects#participant_info) | | `user_info` | - | object | [Данные получателя в вашей системе](/spec/objects#user_info) | | `extra_info` | - | * | Дополнительная информация. Любые данные, которые вам необходимы для проведения операции | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/initiate \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "order123" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "created", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "invalid_request", "error_description": "customer.reference.not_blank" }, "status": "error" } ``` ### `transaction/init/checkout` #### Создание сессии с одновременным стартом платежа Можно использовать, если вы сразу готовы передать все параметры, необходимые для оплаты. В ответе возвращаются параметры созданной сессии и объект с информацией о платеже ([`payments`](/spec/objects#payments)). #### Адрес для отправки запроса `/api/v1/transaction/init/checkout` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-----------------------|----------------|--------|----------------------------------------------------------------------------------------------------------------------------| | `payment_info` | + | object | [Платежные данные](/spec/objects#payment_info) | | `sum_info` | + | object | [Сумма](/spec/objects#sum_info). Передается в копейках. Если отправляете 100 рублей, нужно передать `10000` | | `participant_info` | - | object | [Информация об участниках операции](/spec/objects#participant_info) | | `user_info` | + | object | [Данные клиента в вашей системе](/spec/objects#user_info) | | `payment_settings` | - | object | [Дополнительные параметры платежа](/spec/objects#payment_settings) | | `extra_info` | - | * | Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: `"extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}` | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/init/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payment_info": { "type": "card_info", "card_info": { "type": "card_details", "card_details": { "card_number": "4242424242424242", "card_exp_month": "05", "card_exp_year": "22", "card_code": "123" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" }, "payment_settings": { "back_url": "https://zetplat.com" } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_1313", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "payment_settings": { "back_url": "https://zetplat.com" } }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "invalid_request", "error_description": "customer.reference.not_blank" }, "status": "error" } ``` ### `transaction/init/transfer` #### Создание сессии с одновременным стартом выплаты Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты на банковский счет или банковскую карту. Также можно стартовать выплату с использованием токена, который был получен при создании рекуррентного платежа. В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (`payouts`). #### Адрес для отправки запроса `/api/v1/transaction/init/transfer` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-----------------------|----------------|--------|------------------------------------------------------------------------------------------------------------------------| | `payout_info` | + | object | [Платежные данные](/spec/objects#payout_info) (карта, банковский счет и др.) | | `sum_info` | + | object | [Сумма](/spec/objects#sum_info). Передается в копейках. Если отправляете 100 рублей, нужно передать `10000` | | `participant_info` | - | object | [Информация об участниках операции](/spec/objects#participant_info) (отправителе и получателе) | | `user_info` | - | object | [Данные получателя в вашей системе](/spec/objects#user_info) | | `extra_info` | - | * | Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: `"extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}` | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/init/transfer \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payout_info": { "type": "card_info", "card_info": { "type": "card_details", "card_details": { "card_number": "4242424242424242" } } }, "sum_info": { "sum": 1000, "currency_code": "rub" }, "participant_info": { "payee_info": { "full_name": "Ivanov Ivan" } } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payouts": [{ "id": "po_1313", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/refund` #### Возврат С помощью этого запроса можно вернуть деньги пользователю после успешного платежа. После проведения возврата Zetplat отправит вам вебхук `checkout_refunded`. #### Адрес для отправки запроса `/api/v1/transaction/refund` #### Параметры запроса | Название | Обязательность | Тип | Описание | |------------------|----------------|--------|------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Идентификатор успешной платежной сессии, по которой необходимо провести возврат. | | `sum_info` | - | object | [Сумма возврата](/spec/objects#sum_info). Если не указывать, то возврат будет на полную сумму платежа | | `extra_info` | - | * | Дополнительная информация | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/refund \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id":"ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payments": [{ "id": "pm_1313", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "moneyback": [{ "id": "rf_23", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "sum_info": { "sum": 10000, "currency_code": "rub" } }] }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/start/checkout` #### Старт платежа Этот запрос можно использовать, чтобы начать платеж в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения оплаты или заменить уже переданные. #### Адрес для отправки запроса `/api/v1/transaction/start/checkout` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-----------------------|------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Идентификатор платежной сессии | | `payment_info` | - (обязательно, если не передано в `transaction/initiate`) | object | [Платежные данные](/spec/objects#payment_info) | | `sum_info` | - (обязательно, если не передано в `transaction/initiate`) | object | [Сумма](/spec/objects#sum_info) | | `participant_info` | - | object | [Информация об участниках операции](/spec/objects#participant_info) | | `user_info` | - (обязательно, если не передано в `transaction/initiate`) | object | [Данные отправителя в вашей системе](/spec/objects#user_info) | | `payment_settings` | - | object | [Дополнительные параметры платежа](/spec/objects#payment_settings) | | `extra_info` | - | * | Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: `"extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}` | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/checkout \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230", "payment_info": { "type": "card_info", "card_info": { "type": "card_details", "card_details": { "card_number": "4242424242424242", "card_exp_month": "01", "card_exp_year": "26", "card_code": "123" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "user_info": { "user_id": "lucky" }, "payment_settings": { "back_url": "https://zetplat.com" }, "extra_info": "good" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "payments": [{ "id": "pm_3232", "transaction_status": "ongoing", "created_date": "2024-08-21T06:21:56.846204Z", "user_info": { "user_id": "lucky" }, "payment_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa", "country_code_alpha3": "RUS" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "payment_settings": { "back_url": "https://zetplat.com" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "status": "error", "error": { "error_description": "internal error", "error_code": "repository_record_not_found" } } ``` ### `transaction/start/transfer` #### Старт выплаты Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные. Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать. #### Адрес для отправки запроса `/api/v1/transaction/start/transfer` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-----------------------|------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Идентификатор платежной сессии | | `payout_info` | - (обязательно, если не передано в `transaction/initiate`) | object | [Платежные данные](/spec/objects#payout_info) (карта, банковский счёт и др.) | | `sum_info` | - (обязательно, если не передано в `transaction/initiate`) | object | [Сумма](/spec/objects#sum_info) | | `participant_info - | object | [Информация об участниках выплаты](/spec/objects#participant_info) | | `user_info` | - | object | [Данные получателя в вашей системе](/spec/objects#user_info) | | `extra_info` | - | * | Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: `"extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}` | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/start/transfer \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payouts": [{ "id": "po_1313", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ## Информация ### `public_token/state` #### Получение информации по токену Операции с банковскими картами часто проводятся с токенизированными данными. При выплатах и платежах через виджеты создается публичный токен, при рекуррентных платежах — токен для рекуррентных платежей. По любому платежному токену можно получить информацию: - о банковской карте, для которой создан этот токен — это будет маскированный номер карты и платежная система; - о самом токене — тип токена, время создания, срок действия, активен ли этот токен на момент запроса. Этот метод можно использовать, чтобы, например, узнать маскированный номер карты и показать пользователю, с какой карты спишутся деньги по подписке. Или если понадобится проверить срок действия токена. #### Адрес для отправки запроса `/api/v1/public_token/state` #### Параметры запроса | Название | Обязательность | Тип | Описание | |-------------------|---------------------------------------------|--------|-------------------------------------------------------------------------------| | `type` | + | string | Тип запроса. Варианты: `card_info`, `public_token`, `recurring_token` | | `card_info` | - (обязателен для `type = card_info`) | object | [Данные токена банковской карты](/spec/objects#card) | | `public_token` | - (обязателен для `type = public_token`) | object | [Данные публичного токена](/spec/objects#publictoken) | | `recurring_token` | - (обязателен для `type = recurring_token`) | object | [Данные токена для рекуррентных платежей](/spec/objects#recurrent_token) | Примеры запросов Вы отправляете токенизированные данные банковской карты и получаете маску карты и платежную систему. ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token/state \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "type": "card_info", "card_info": { "type": "hashed_card_details", "hashed_card_details": { "hashed_card_number": "card_number_hash (token)" } } }' ``` Вы отправляете публичный токен и получаете информацию о нем. ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token/state \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "type": "public_token", "public_token": { "token": "your_token" } }' ``` Вы отправляете токен и получаете информацию о нем. ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/public_token/state \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "type": "recurring_token", "recurring_token": { "token": "your_token" } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |----------|----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `token_info` | - | object | В зависимости от типа запроса (`type`): - [информация о токенизированной банковской карте](/spec/objects#card_token_info)- [информация о публичном токене](/spec/objects#public_token_info)- [информация о токене для рекуррентных платежей](/spec/objects#info_recurrent) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Примеры успешных ответов ```json showLineNumbers { "status": "ok", "token_info": { "hashed_card_number": "card_number_hash", "card_network": "visa", "card_last4": "4242", "type": "card_info" } } ``` ```json showLineNumbers { "status": "ok", "token_info": { "token": "your_token", "created_date": "2024-03-17T14:10:56+03:00", "completed_date": "2024-03-18T14:10:56+03:00", "token_active": true, "type": "public_token" } } ``` ```json showLineNumbers { "status": "ok", "token_info": { "token": "your_token", "created_date": "2024-03-17T14:19:05+03:00", "completed_date": "2024-04-17T14:19:05+03:00", "token_active": true, "type": "recurring_token" } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `sbp/banks` С помощью этого запроса вы можете получить список наименований и идентификаторов банков-участников Системы быстрых платежей. >Метод используется только для выплат. #### Адрес для отправки запроса `/api/v1/sbp/banks` Пример запроса ```json showLineNumbers curl -X GET \ https://api-demo.zetplat.com/api/v1/sbp/banks \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{}' ``` Пример ответа ```json showLineNumbers { "banks": [{ "id": "100000000243", "eng_name": "National Standard Bank", "ru_name": "Национальный стандарт" }, { "id": "100000000056", "eng_name": "Khlynov", "ru_name": "Хлынов" },...] } ``` ### `sbp/identity_check` С помощью этого запроса можно проверить зарегистрирован ли получатель в Системе Быстрых Платежей. Если пользователь найден в СБП, то сессия примет успешный статус, иначе сессия отменится. Эта операция не тарифицируется и подтверждается автоматически (вебхук `approve_pending` не отправляется). #### Адрес для отправки запроса `/api/v1/sbp/identity_check` #### Параметры запроса | Название | Обязательность | Тип | Описание | |---------------------|----------------|--------|------------------------------------------------------------------------------------------| | `payout_info` | + | object | [Платежные данные](/spec/objects#payout_info) (карта, банковский счёт и др.) | | `participant_info` | + | object | [Информация об участниках выплаты](/spec/objects#participant_info) | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/sbp/identity_check \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "payout_info": { "type": "account_info", "account_info": { "payment_system": "fps_info_verification", "fps_info_verification": { "phone_number": "79261234567", "bank_identifier": "100000000069" } } }, "participant_info": { "payee_info": { "given_name": "Иван", "family_name": "Иванов", "patronymic": "Иванович" } } }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payouts": [{ "id": "po_31668", "transaction_status": "ongoing", "created_date": "2022-03-01T11:57:31.895773Z", "payout_info": { "type": "account_info", "account_info": { "payment_system": "fps_info_verification", "fps_info_verification": { "phone_number": "79261234567", "bank_identifier": "100000000069" } } }, "sum_info": { "sum": 100, "currency_code": "rub" }, "participant_info": { "payee_info": { "given_name": "Иван", "family_name": "Иванов", "patronymic": "Иванович" } } }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` ### `transaction/state` #### Получение информации по сессии Вы можете отправить этот запрос, если хотите получить полную информацию о платежной сессии. Например, проверить, прошла выплата или нет. Или узнать, можно ли списывать сумму, захолдированную при оплате картой. В ответ на запрос приходит платежная сессия с данными обо всех операциях, которые проводились в ее рамках. #### Адрес для отправки запроса `/api/v1/transaction/state` #### Параметры запроса | Название | Обязательность | Тип | Описание | | ---------- | -------------- | ------ | ------------------------------ | | `session_id` | + | string | Идентификатор платежной сессии | Пример запроса ```json showLineNumbers curl -X POST \ https://api-demo.zetplat.com/api/v1/transaction/state \ -H 'Content-Type: application/json' \ -H 'X-Project-Id: your_project_name' \ -H 'X-Signature: signature' \ -d '{ "session_id": "ps_3230" }' ``` #### Параметры ответа | Название | Обязательность | Тип | Описание | |-----------|----------------|--------|--------------------------------------------------------| | `status` | + | string | Статус. Возможные варианты: `error`, `ok` | | `session_info` | - | object | [Платежная сессия](/spec/objects#payment_session) | | `error_info` | - | object | [Ошибка](/spec/objects#error_info) | Пример успешного ответа ```json showLineNumbers { "status": "ok", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", "payouts": [{ "id": "po_1313", "transaction_status": "ongoing", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa", "card_bin":"444600" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" }, "extra_info": "good" }] } } ``` Пример неуспешного ответа ```json showLineNumbers { "error": { "error_code": "error code", "error_description": "error description" }, "status": "error" } ``` --- ## Вебхуки - [Вебхуки](https://docs.zetplat.com/spec/webhooks): Уведомления о событиях: статусы платежей, выплат, возвратов. Вебхуки — это уведомления о событиях, возникающих на стороне Zetplat. Они оповещают о результате выполнения операции, служат для запроса подтверждения или информируют о действиях, которые требуются от вас. Кроме того, с помощью вебхуков может передаваться информация о сумме комиссии за проведенную операцию. Для подключения этой функции обратитесь к вашему менеджеру Zetplat. :::info[] Если функция вебхуков отключена, вам придется самостоятельно отправлять запрос [`transaction/state`](/spec/methods#transactionstate) для каждой операции, чтобы отслеживать статус и узнавать следующий этап. ::: ## Настройка получения вебхуков 1. Создайте на своей стороне публичный URL-адрес для приема уведомлений. 2. Передайте его вашему менеджеру Zetplat. Чтобы **перестать** получать вебхуки, напишите вашему менеджеру в Zetplat. ## Требования к ответу На любой полученный вебхук ваш сервис должен возвращать HTTP-код 200. Если в ответе будет передан код из диапазонов 4\** или 5\**, Zetplat будет повторять отправку, пока не получит ответ. Отправка будет проходить с увеличивающимися интервалами по следующим правилам: - время между повторными попытками постепенно растет, но не превышает 15 минут; - если на протяжении 30 минут ни одна из попыток не завершилась успешно (HTTP-код 200), отправка вебхука окончательно прекращается. :::warning[ВАЖНО!] Набор полей в теле вебхука может со временем расширяться — это связано с добавлением новых способов оплаты. Реализуйте обработку уведомлений так, чтобы появление дополнительных полей не нарушало работу вашего сервиса. ::: ## Вебхуки Zetplat ### `action_pending` Zetplat отправляет этот вебхук, если для продолжения операции нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure. #### Параметры | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|---------------------------------------------------| | `type` | + | string | Тип вебхука: `action_pending` | | `session_info` | + | object | [Платежная сессия](/spec/objects#payment_session) | Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "action_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "pm_1313", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id":"user@test.ru" }, // highlight-next-line "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "8801", "card_bin":"444600" } }, "sum_info": { "sum": 15000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" }, "user_action": { "type": "destination_info", "destination_info": { "url_address": "https://zetplat.com?foo=bar", "domain": "https://zetplat.com", "http_method": "POST", "additional_params": { "foo": "bar" }, "extra_params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ### `checkout_results` Zetplat отправляет этот вебхук, когда завершает операцию. Результат приходит в поле `transaction_status` массива `payments`. Статус `successful` означает успешную операцию. #### Параметры | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|---------------------------------------------------| | `type` | + | string | Тип вебхука: `checkout_results` | | `session_info` | + | object | [Платежная сессия](/spec/objects#payment_session) | Примеры ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payouts": [{ "id": "po_1234", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, // highlight-next-line "payout_info": { "type": "account_info", "account_info": { "payment_system": "fps_info_verification", "fps_info_verification": { "phone_number": "79261234567", "bank_identifier": "100000000069" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "checkout_results", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1234", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, // highlight-next-line "payment_info": { "type": "account_info", "account_info": { "payment_system": "fps_info_verification", "fps_info_verification": { "phone_number": "79261234567", "bank_identifier": "100000000069" } } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" } }] } }' ``` ### `checkout_refunded` Zetplat отправляет этот вебхук после проведения возврата. В параметрах уведомления приходит информация о платежной сессии, включающей в себя информацию о возвратах. Вебхук отправляется в следующих случаях: - если вы сделали возврат с помощью метода [`transaction/refund`](/spec/methods#transactionrefund), - в рамках процедуры **chargeback**. > Если возврат сделан в рамках процедуры **chargeback**, в объекте `moneyback` вы увидите дополнительную строку: `"chargeback": true`. #### Параметры | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|---------------------------------------------------| | `type` | + | string | Тип вебхука: `checkout_refunded` | | `session_info` | + | object | [Платежная сессия](/spec/objects#payment_session) | Примеры ```json showLineNumbers curl - X POST \ https: //partner.ru \ -H 'Content-Type: application/json' \ - -H 'X-Signature: signature' \ - -d '{ "type": "checkout_refunded", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payouts": [{ "id": "pm_2705", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, // highlight-next-line "payout_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242", "card_bin":"444600" } }, "sum_info": { "sum": 1000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" }, "extra_info": "good", "moneyback": [{ "id": "rf_203", "transaction_status": "repaid", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "chargeback": true, "sum_info": { "sum": 1000, "currency_code": "rub" }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl - X POST \ https: //partner.ru \ -H 'Content-Type: application/json' \ - -H 'X-Signature: signature' \ - -d '{ "type": "checkout_refunded", "session_info": { "id": "ps_3230", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "pm_2705", "transaction_status": "successful", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "lucky" }, // highlight-next-line "payment_info": { "type": "card_info", "card_info": { "card_network": "visa", "card_last4": "4242", "card_bin":"444600" } }, "sum_info": { "sum": 1000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" }, "extra_info": "good", "moneyback": [{ "id": "rf_203", "transaction_status": "completed", "created_date": "2024-05-27T02:03:00.000000Z", "completed_date": "2024-05-27T02:03:00.000000Z", "chargeback": true, "sum_info": { "sum": 1000, "currency_code": "rub" }, "transaction_info": { "retrieval_ref_number": "425307614918", "authorization_code": "057441" } }] }] } }' ``` ### `finalization_pending` Zetplat отправляет этот вебхук при холдировании. Это значит, что деньги для оплаты заморожены на банковской карте пользователя. Их можно списать сразу или через некоторое время. - **Подтвердить** — с помощью запроса [`transaction/finalize`](/spec/methods#transactionfinalize). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). #### Параметры | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|---------------------------------------------------| | `type` | + | string | Тип вебхука: `finalization_pending` | | `session_info` | + | object | [Платежная сессия](/spec/objects#payment_session) | Пример ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "finalization_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "finalize", // highlight-next-line "payments": [{ "id": "pm_1313", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, // highlight-next-line "payment_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "extra_info": "good" }] } }' ``` ### `approve_pending` Zetplat отправляет этот вебхук, когда готов провести операцию — выплату или платеж. Проверьте данные операции, а затем подтвердите или отмените ее: - **Подтвердить** — с помощью запроса [`transaction/approve`](/spec/methods#transactionapprove). - **Отменить** — с помощью запроса [`transaction/cancel`](/spec/methods#transactioncancel). :::info[] Для вашего удобства можно настроить автоподтверждение платежной сессии и обойтись без получения вебхука `approve_pending` с последующим его подтверждением. Для настройки автоподтверждения обратитесь к вашему менеджеру в Zetplat. ::: #### Параметры | Название | Обязательность | Тип | Описание | |----------------|----------------|--------|---------------------------------------------------| | `type` | + | string | Тип вебхука: `approve_pending` | | `session_info` | + | object | [Платежная сессия](/spec/objects#payment_session) | Примеры ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", // highlight-next-line "payouts": [{ "id": "po_1234", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, // highlight-next-line "payout_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "extra_info": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-Signature: signature' \ -d '{ "type": "approve_pending", "session_info": { "id": "ps_3230", "transaction_status": "active", "created_date": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_step": "approve", // highlight-next-line "payments": [{ "id": "pm_1313", "transaction_status": "pending", "created_date": "2024-05-27T02:03:00.000000Z", "user_info": { "user_id": "user123", "contact_info": [{ "email_address": "user@gmail.com" }] }, // highlight-next-line "payment_info": { "type": "card_info", "card_info": { "card_last4": "4242", "card_network": "visa" } }, "sum_info": { "sum": 10000, "currency_code": "rub" }, "fee_info": { "fee": { "merchant_fee": { "sum": 10, "currency_code": "RUB" } } }, "extra_info": "good" }] } }' ``` --- ## Ошибки - [Ошибки](https://docs.zetplat.com/spec/errors): Коды и описания ошибок API. :::info[] - Коды ошибок могут обновляться без отдельного уведомления. - Ошибки не разделяются по платежам и выплатам. - В таблице даны только общие описания кодов ошибок в столбце (`error_code`). Одному коду могут соответствовать несколько вариантов описания в поле `error_description`. ::: | `error_code` | Описание ошибки | |----------------------------------------|------------------------------------------------------------------------------------------| | `3DS_error` | Проблемы с прохождением 3DS | | `activity_count_exceeded` | Достигнут лимит по сумме или количеству операций для карты/кошелька | | `authentication_error` | Не пройдена аутентификация | | `authorization_error` | Не пройдена авторизация | | `bank_card_expired` | Карта просрочена | | `cancelled_by_customer` | Пользователь отменил транзакцию | | `capture_timeout` | Транзакция отменена, так как подтверждение не пришло вовремя | | `card_number_does_not_exist` | Номер карты указан неверно | | `confirm_timeout` | Транзакция отменена, так как истекло время подтверждения | | `declined_by_issuer_bank` | Банк, выпустивший карту, отклонил операцию | | `idempotency_key_already_exists` | Запрос с таким ключом уже в обработке. Дождитесь его завершения | | `idempotency_key_not_supported` | Этот метод не поддерживает ключи идемпотентности | | `idempotency_key_params_mismatch` | Ключ уже привязан к другой сессии | | `identification_error` | Не удалось идентифицировать партнера | | `incomplete_data` | Переданы не все обязательные поля — проверьте запрос | | `incorrect_card_data` | Ошибочные реквизиты карты | | `insufficient_funds` | Недостаточно средств на карте | | `insufficient_wallet_balance` | Недостаточно средств на балансе. Ошибка будет повторяться, пока баланс не будет пополнен | | `internal_error` | Внутренняя ошибка системы | | `invalid_details` | Некорректный формат переданных данных | | `invalid_recipient_details` | Неверно указаны данные получателя | | `invalid_request` | Ошибка в структуре запроса | | `invalid_sender_details` | Неверно указаны данные отправителя | | `invalid_transaction` | Транзакция некорректна | | `issuer_bank_fault` | Сбой на стороне банка, выпустившего карту | | `not_permitted_by_issuer_bank` | Операция запрещена банком, выпустившим карту | | `not_permitted_to_card` | Операция недоступна для этой карты | | `operation_rejected` | Отказ по правилам безопасности | | `provider_exceeds_amount_limit` | Превышен лимит на сумму перевода (разовый или максимальный) | | `provider_foreign_transfer_prohibited` | Перевод на иностранную или корпоративную карту через этого провайдера недоступен | | `provider_internal_error` | Сбой на стороне провайдера | | `provider_issuer_unavailable` | Банк, выпустивший карту, не отвечает | | `provider_timeout` | Таймаут ожидания ответа от провайдера | | `refund_amount_too_large` | Сумма возврата выше допустимой | | `routing_internal_error` | Не удалось определить условия проведения платежа | | `session_cancelled_by_partner` | Партнер отменил сессию | | `session_cancelled` | Сессия отменена | | `session_wrong_state` | Текущий статус сессии не позволяет выполнить операцию | | `suspected_fraud` | Операция заблокирована как подозрительная | | `wallet_internal_error` | Сбой при обработке баланса |