.. meta:: :description: /api/v4/payout-by-ref API endpoint SBC: отправляет выплату на сохранённый референс карты получателя без повторного сбора данных карты. .. _/api/v4/payout-by-ref/: /api/v4/payout-by-ref/ ################################## .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^^^ Payout By Reference инициируется запросом :code:`HTTPS POST` с использованием указанных ниже :ref:`URL-адресов` и :ref:`параметров`. Для аутентификации используйте :ref:`RSA-SHA256`. .. _payout-by-ref_api: API URL ^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.sbctech.ru/paynet/api/v4/payout-by-ref/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/payout-by-ref/ENDPOINTID` * - :ex:`https://sandbox.sbctech.ru/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID` - :ex:`https://gate.sbctech.ru/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID` .. _payout-by-ref_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. .. note:: | Ask Support Менеджер if Conditional fields are Обязательный for integration. .. list-table:: :widths: 25, 45, 25 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`client_orderid` - Идентификатор заказа, присвоенный Присоединяющейся Стороной. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`amount` - Сумма к оплате. Сумма должна быть указана в максимальных единицах с "." разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`currency` - Валюта, в которой проводится операция (трёхбуквенные алфавитные коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 3 * - :code:`destination-card-ref-id` - Идентификатор ссылки на карту назначения, полученный на этапе регистрации карты. В сценарии оплаты на карту внутри системы эта карта считается картой назначения, и к ней применяются все лимиты обработки, списки и скоринг мошенничества. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 20 * - :code:`order_desc` - Описание заказа. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 64 * - :code:`ipaddress` - IP-адрес получателя (IPv4 или IPv6) - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 7-45 * - :code:`purpose` - Назначение Payout. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`server_callback_url` - | URL-адрес :ex:`server_callback_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`notify_url`. При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`notify_url` - | URL-адрес :ex:`notify_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`server_callback_url`. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`redirect_url` - | URL, where the Receiver is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is :ex:`approved`, :ex:`declined` in any other final :ref:`status`. | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`https://doc.sbctech.ru` if you have no need to return Receiver anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`redirect_success_url` - | URL, на который Получатель перенаправляется, когда статус транзакции — :ex:`approved` (см. :ref:`список статусов`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Otherwise put :ex:`https://doc.sbctech.ru` if there is no need to redirect Receiver anywhere. Use either combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url` or :ex:`redirect_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_fail_url` - | URL, на который Получатель перенаправляется, когда статус транзакции не :ex:`approved` (см. :ref:`список статусов`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`https://doc.sbctech.ru` if there is no need to redirect Receiver anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`account_number` - Номер банковского счета - | ``Необходимость``: Условно | ``Тип``: String | ``Length``: 24 * - :code:`account_name` - Банковский счет - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`ewallet_type` - Тип e-wallet. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 64 * - :code:`ewallet_wallet` - Идентификатор e-wallet. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`crypto_wallet_address` - Адрес криптокошелька. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 64 * - :code:`bank_name` - Имя банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_branch` - Имя банковского отделения. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_code` - Код банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :code:`bank_city` - Город банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`bank_address1` - Адрес банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_zip_code` - Почтовый индекс банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_province` - Штат банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_area` - Область банка - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`routing_number` - Номер маршрута, используется для определения отдела банка в Китае. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 16 * - :code:`legal_person_name` - Имя на юридическом документе. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`legal_person_document_number` - Номер юридического документа - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_first_name` - Имя Получателя, так же можно отправить как :code:`first_name`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_last_name` - Фамилия Получателя, так же можно отправить как :code:`last_name`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_birthday` - Дата рождения получателя, так-же можно отправить как :code:`birthday`. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 30 * - :code:`receiver_country_code` - Код страны Получателя, также можно отправить как :code:`country`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 3 * - :code:`receiver_state` - Штат Получателя, обязательный параметр для стран, которые делятся на штаты (США, Канада, Австралия), также можно отправить как :code:`state`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 4 * - :code:`receiver_city` - Город Получателя, также можно отправить как :code:`city`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_zip_code` - Почтовый индекс Получателя, также можно отправить как :code:`zip_code`. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 32 * - :code:`receiver_address1` - Адрес Получателя, также можно отправить как :code:`address1`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 256 * - :code:`receiver_phone` - Номер телефона Получателя, также можно отправить как :code:`phone`. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 128 * - :code:`receiver_email` - Адрес электронной почты Получателя, также можно отправить как :code:`email`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_identity_document_id` - Идентификатор удостоверения личности получателя, так-же можно отправитькак :code:`identity_document_id`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_identity_document_number` - Номер удостоверения личности получателя, так-же можно отправитькак :code:`identity_document_number`. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`order_desc` - Любая дополнительная информация о транзакции, которая может быть полезна во внешних системах Присоединяющейся стороны, например :ex:`VIP клиент`, :ex:`лид промокампании на ТВ`. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 64k * - :code:`bank_bic` - BIC-код банка получателя - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`receiver_inn` - Уникальный идентификатор для налогообложения получателя - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`customer_level` - Уровень клиента в системе CMS. - | ``Необходимость``: Опционально | ``Тип``: Varchar | ``Длина``: 32 * - :code:`customer_id` - Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом. - | ``Необходимость``: Опционально | ``Тип``: Int | ``Длина``: 10 * - :code:`merchant_customer_identifier` - Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM. - | ``Необходимость``: Опционально | ``Тип``: Varchar | ``Длина``: 64 * - :code:`card-ref-id` - Ссылочный Идентификатор Платежа для последующих списаний. Может быть создан с помощью запроса :ref:`токенизации v4` или запроса :ref:`токенизации v2`. - | ``Необходимость``: Условно | ``Тип``: Long Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра. .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Payout Параметры запроса - Описание * - :code:`type` - Тип ответа. Может принимать такие значения как: :ex:`async-response`, :ex:`validation-error`, :ex:`error` и т.д. Если тип ответа :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` будут содержать детали ошибки. * - :code:`paynet-order-id` - Идентификатор заказа, присвоенный SBC. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны. * - :code:`error-message` - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`error`. Пример запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http POST /paynet/api/v4/payout-by-ref/121799 HTTP/1.1 Host: sandbox.sbctech.ru User-Agent: curl/8.4.0 Accept: */* Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="8qsDrhiDelGHlxY01aDjCh44u7isXJjL", oauth_signature="WpbNcRxNSDW%2BdJgftRc%2BAN0oe8KAP4CNpUkxjxStFYZEU9Vo%2F7uk9dSKEG%2B76C%2FdlzemILaRmikQqZg93ZK1cibT8zy97uYVDdWVmY2obDSOVb8UipGjt2KFUyKr4awHW9xH%2BTzbR%2FMXwm3y%2Fx2RotElZWxumsL37P5Q%2BCquoAGcO6jjkvkkSH9P4lBYKSmwhfqD4O%2Br8FB3exzNzl2FFBTwLp4ch2G9Cis5a0CkVrpjDB%2FbbbrOutbNPZYhtH45rNz91QAbpvNJ91XjVwxiCm4lCldIO66gF73GQNSFKVG1mstc%2B941Dj1bVhXWQQW%2F9TyPiXfWGP8szg18rwsTHbj1zKCRIaw%2FqVbrOBPhbo%2BJjGMZp2hB1ei0%2FUPIkjeIZkWD2NgJRQEniJfjU7AlILs91augm50fPwWR5JiOuE5uSvwM6VWgXMpYe4USb819ZAK%2BFYTRI%2BenrycFZHmY%2BafOlaOHFtpnbn8FsrzzNbOvGXmXCt2xXAQTaORqMeLRRtkD3DY4rJa8qeO0zYnmT4ZhKsFZjImDdonA3WTG8G7awP9W0RKhHlUGwGaugRWbdPjSbGMhAzs58Y9ptvExr6GwAHhJU1RbzfWL4wCzVbH8%2BAC6I0OrkB13tw2eXP4yIPtEC7iGu%2FkElGz4OrwFEU6cUcEDpeEOmA2%2Fe%2BZFK0w%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721975900", oauth_version="1.0" Content-Length: 74 Content-Type: application/x-www-form-urlencoded Connection: keep-alive amount=10.42 &client_orderid=1 ¤cy=USD &destination-card-ref-id=1461897 Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 200 Server: server Date: Fri, 26 Jul 2024 06:39:23 GMT Content-Type: text/html;charset=utf-8 Connection: keep-alive Keep-Alive: timeout=60 Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 138 type=async-response &serial-number=00000000-0000-0000-0000-000002f36e41 &merchant-order-id=1 &paynet-order-id=7363634 &end-point-id=121799 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 200 Server: server Date: Fri, 26 Jul 2024 06:42:43 GMT Content-Type: text/html;charset=utf-8 Connection: keep-alive Keep-Alive: timeout=60 Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 170 type=validation-error &serial-number=00000000-0000-0000-0000-000002f36e42 &error-message=Project+with+currency+USD+does+not+apply+request+with+currency+AZN &error-code=16 Коллекция Postman ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_payout.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Вставьте приватный ключ PKCS#1 PEM для среды sandbox в поле ниже. Конструктор запросов поддерживает длину ключа до 4096. .. raw:: html :file: ../_static/examples/V4Payout-by-ref_Debug.html