.. meta:: :description: Серверные обратные вызовы Payneteasy для торговца: параметры, проверка подписи и обработка асинхронных уведомлений о статусе транзакции. .. _merchant_callbacks: Обратный вызов Присоединяющейся Стороны #################################################### .. role:: ex .. role:: code Вводная информация ====================================================== Если Присоединяющаяся Сторона указывает URL обратного вызова, Платёжный Шлюз отправляет :ex:`HTTP GET` запрос на этот URL, когда транзакция получает финальный статус вне зависимости от того, получен ли статус :ex:`approved`, :ex:`declined` или другой из :ref:`финальных статусов`. Это позволяет Присоединяющейся Стороне лучше контролировать процесс прохождения транзакции, например, осуществляя соответствующие пометки во внутренней системе учёта. .. warning:: Сервер Присоединяющейся Стороны должен отвечать на этот :ex:`GET` запрос статусом :code:`200 OK` согласно `RFC `_, в противном случае Платёжный Шлюз продолжит попытки отправить обратный вызов в течение 30 раз за 14 дней с увеличивающимся интервалом между запросами. .. |rfc_link| raw:: html RFC Please remember, callbacks are guaranteed to report Connecting Party about transaction status. Connecting Party on their side must provide a means of preventing receiving the same callback twice - in case of network or other technical problems. It is recommended to check :code:`status`, :code:`type`, :code:`orderid` and :code:`client_orderid` to prevent duplication of transactions on Connecting Party side. URL обратного вызова могут быть указаны Присоединяющейся Стороной следующими способами: * Путём отправки :code:`server_callback_url` или :code:`notify_url` в инициирующем запросе на проведение транзакции. Если отправлен :code:`server_callback_url`, Присоединяющаяся Сторона получит обратный вызов только по изначальной транзакции (например sale approved). Если вместо этого отправлен :code:`notify_url`, Присоединяющаяся Сторона получит обратный вызов по изначальной транзакции, а также по всем последующим транзакциям, связанным с изначальной (например reversal, chargeback). * Путём указания URL обратного вызова на уровне терминала. Каждый тип транзакции может иметь свой URL обратного вызова. Для URL обратного вызова разрешены только следующие порты: * для :ex:`HTTP` 80, 8080 * для :ex:`HTTPS` 443, 8443 Настраиваемый URL обратного вызова ======================================================== | Обычный URL обратного вызова содержит все параметры, указанные в :ref:`Параметрах обратного вызова`. | Настраиваемый URL обратного вызова - это полностью определённый URL со всеми параметрами, необходимыми на конечной странице или скрипте обработки результата Присоединяющейся Стороной. Настраиваемый URL позволяет Присоединяющейся Стороне самостоятельно определить названия параметров, значения для которых определяются макросами в формате :code:`${parameter_name}`. Таким образом, gate.payneteasy.ru заменяет соответствующие значения параметров в настраиваемом URL перед отправкой на запроса него. Доступные макросы перечислены в разделе :ref:`Макросы обратного вызова`. Настраиваемый URL обратного вызова :code:`https://connectingparty.com/sale_completed.php` Настраиваемый URL обратного вызова :code:`https://connectingparty.com/sale_completed.php?cardholder_name=${name}&tx_status=${status}&order_id=${merchant_order}` .. _merchant_callback_parameters: Параметры обратного вызова ================================================== .. note:: | Система автоматически добавляет нижеуказанные параметры к URL обратного вызова. | * - эти параметры не возвращаются в ответе по умолчанию. Для их получения необходимо связаться со службой поддержки. .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Параметр - Описание * - :code:`status` - Подробности см. в :ref:`status_list`. * - :code:`merchant_order` - Идентификатор заказа в системе Присоединяющейся Стороны, аналогичен параметру :ex:`client_orderid`. * - :code:`client_orderid` - Идентификационный номер транзакции, присовенный Присоединяющейся Стороной. * - :code:`orderid` - Идентификатор заказа в системе gate.payneteasy.ru. * - :code:`type` - Тип транзакции, например :ex:`sale`, :ex:`reversal`, :ex:`chargeback`. * - :code:`amount` - Фактическая сумма транзакции. Данное значение может быть изменено в ходе транзакции. * - :code:`currency` - Валюта транзакции. * - :code:`descriptor` - Дескриптор платежа, указанный на шлюзе, через который прошла транзакция. * - :code:`error_code` - Код ошибки. Данное поле не будет включено в обратный вызов, если статус транзакции :code:`status=approved`. * - :code:`error_message` - Сообщение ошибки. Данное поле не будет включено в обратный вызов, если статус транзакции :code:`status=approved`. * - :code:`name` - Имя держателя карты. * - :code:`email` - Адрес электронной почты плательщика. * - Параметр :code:`country` * - Страна плательщика (двухбуквенный код страны). Список допустимых кодов стран см. в :ref:`country-state-codes`. * - Параметр :code:`state` * - Штат плательщика. Список допустимых кодов штатов см. в:ref:`country-state-codes`. Обязательно для США, Канады и Австралии. * - Параметр :code:`city` * - Город Плательщика. * - Параметр :code:`zip_code` * - Почтовый индекс Плательщика. * - Параметр :code:`address1` * - Адрес Плательщика, строка 1. * - :code:`approval-code` - Код авторизации успешной транзакции, если присутствует. * - :code:`last-four-digits` - Последние четыре цифры номера карты плательщика. * - :code:`bin` - БИН карты плательщика. * - :code:`card-type` - Тип карты плательщика (:ex:`VISA`, :ex:`MASTERCARD` и т.д.). * - :code:`phone` - Номер телефона плательщика. * - :code:`bank-name` - Название банка плательщика. * - :code:`card-exp-month` - Месяц срока действия карты. * - :code:`card-exp-year` - Год срока действия карты. * - :code:`gate-partial-reversal` - Возможность проведения частичного возврата (enabled - возможно, disabled - невозможно). * - :code:`gate-partial-capture` - Возможность проведения частичного списания захолдированной суммы (enabled - возможно, disabled - невозможно). * - :code:`reason-code` - Причина возвратного платежа (chargeback) или метки о мошеннической операции. * - :code:`processor-rrn` - Уникальный идентификатор банковской транзакции, который назначается банком Эквайером. * - :code:`comment` - Комментарий, в случае возврата. * - :code:`rapida-balance` - Текущий баланс Присоединяющейся Стороны в системе Рапида (при наличии активной проверки баланса). * - :code:`control` - Контрольная сумма используется, чтобы убедиться, что callback Присоединяющейся стороне инициирует gate.payneteasy.ru, а не мошенник. Это контрольная сумма :ex:`SHA-1` от конкатенации :ex:`status` + :ex:`orderid` + :ex:`merchant_order` + :ex:`merchant_control`. Скрипт callback ОБЯЗАН проверить этот параметр, сравнив его с контрольной суммой :ex:`SHA-1` указанной выше конкатенации. * - :code:`merchantdata` - Значение, переданное в соответствующем параметре инициирующего запроса Присоединяющейся Стороной. * - :code:`serial-number` - Серийный номер запроса. * - :code:`processor-tx-id` - Идентификатор транзакции, присвоенный процессором. * - :code:`processor-auth-credit-code` - Зарезервировано. * - :code:`card-hash-id` - Уникальный хеш карты, всегда одинаковый для этой карты. * - :code:`verified-3d-status` - Для транзакции, прошедшей проверку 3DS, вернётся значение :ex:`AUTHENTICATED`. * - :code:`processor-credit-rrn` - Уникальный идентификатор, который назначается банком Эквайером. * - :code:`processor-credit-arn` - Номер ссылки на карту эквайера для кредитной карты. * - :code:`processor-debit-arn` - Уникальный ссылочный идентификатор транзакции. * - :code:`eci` - Индикатор электронной коммерции (Visa). * - :code:`ips-src-payment-product-code` - Код карты, установленный международным платёжным сервисом (Visa/Mastercard). * - :code:`ips-src-payment-product-name` - Расшифрованный код карты, установленный международным платёжным сервисом (Visa/Mastercard). * - :code:`ips-src-payment-type-code` - Тип кода карты, установленный международным платёжным сервисом (Visa/Mastercard). * - :code:`ips-src-payment-type-name` - Расшифрованный тип кода карты, установленный международным платёжным сервисом (Visa/Mastercard). * - :code:`card-country-alpha-three-code` - Трёхбуквенный код страны Эмитента карты отправителя. См :ref:`Коды стран`. * - :code:`destination-card-country-alpha-three-code` - Трёхбуквенный код страны Эмитента карты получателя. См :ref:`Коды стран`. * - :code:`initial-amount` - Сумма, установленная при инициировании транзакции, без каких-либо сборов или комиссий. Это значение не может измениться в ходе транзакции. * - Описание: :code:`customer-ip` * - IP-адрес клиента * - Параметр :code:`seller-commission` * - Итоговая комиссия проведённой транзакции. * - Параметр :code:`acquirer-commission` * - Комиссия Эквайера для проведённой транзакции. * - Описание: :code:`exchange-rate` * - Базовый курс обмена валюты. * - Параметр :code:`effective-exchange-rate` * - Фактический курс обмена валюты. * - Параметр :code:`motivational-message` * - Опциональный параметр, содержаний сообщение с расширенной информацией по причине отклонения транзакции. * - :code:`orig-amount` - Изначальная сумма транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму. * - :code:`orig-currency` - Изначальная валюта транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму. * - :code:`transaction-date` - Callback receiving date and time. .. _callback_macros: Callback Macros ============================================== .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Название макроса gate.payneteasy.ru - Описание * - :code:`${status}` - Статус транзакции, например :ex:`approved`, :ex:`declined`, :ex:`processing` и т.д. * - :code:`${merchant_order}` - Идентификатор заказа в системе Присоединяющейся Стороны, аналогичен параметру :ex:`client_orderid`. * - :code:`${orderid}` - Идентификатор заказа в системе gate.payneteasy.ru. * - :code:`${type}` - Тип транзакции, например :ex:`sale`, :ex:`return`, :ex:`chargeback` и т.д. * - :code:`${amount}` - Сумма транзакции. * - :code:`${descriptor}` - Дескриптор платежа, указанный на шлюзе, через который прошла транзакция. * - :code:`${error_message}` - Сообщение ошибки, если :code:`${status}` = declined. * - :code:`${name}` - Имя держателя карты. * - :code:`${email}` - Адрес электронной почты плательщика. * - :code:`${last-four-digits}` - Последние четыре цифры номера карты плательщика. * - :code:`${bin}` - БИН карты плательщика. * - :code:`${card-type}` - Тип карты плательщика (:ex:`VISA`, :ex:`MASTERCARD` и т.д.). * - :code:`${card-exp-month}` - Месяц срока действия карты. * - :code:`${card-exp-year}` - Год срока действия карты. * - :code:`${gate-partial-reversal}` - Возможность проведения частичного возврата (enabled - возможно, disabled - невозможно). * - :code:`${gate-partial-capture}` - Возможность проведения частичного списания захолдированной суммы (enabled - возможно, disabled - невозможно). * - :code:`${reason-code}` - Причина возвратного платежа (chargeback) или метки о мошеннической операции. * - :code:`${processor-rrn}` - Уникальный идентификатор банковской транзакции, который назначается банком Эквайером. * - :code:`${approval-code}` - Код одобрения банка. * - :code:`${comment}` - Комментарий, в случае возврата. * - :code:`${rapida-balance}` - Текущий баланс Присоединяющейся Стороны в системе Рапида (при наличии активной проверки баланса). * - :code:`${control}` - Контрольная сумма используется, чтобы убедиться, что callback Присоединяющейся стороне инициирует gate.payneteasy.ru, а не мошенник. Это контрольная сумма :ex:`SHA-1` от конкатенации :ex:`status` + :ex:`orderid` + :ex:`merchant_order` + :ex:`merchant_control`. Скрипт callback ОБЯЗАН проверить этот параметр, сравнив его с контрольной суммой :ex:`SHA-1` указанной выше конкатенации. * - :code:`${merchantdata}` - Значение, переданное в соответствующем параметре инициирующего запроса Присоединяющейся Стороной. Пример обратного вызова ======================================================= .. code-block:: bash https://connectingparty.com/api/integration/check/pay/server?token=some_token &serial-number=b8e5b762-c116-407e-a591-82a458e1 &merchant_order=preauth_1171 &client_orderid=preauth_1171 &processor-tx-id=e0a0572f-2154-737c-8ea7-92410 &orderid=57792 &status=approved &amount=1.50 ¤cy=EUR &descriptor=%D0%90+%D0%94%D0%B5%D0%BD%%D0%B3%D0%B8+-+card+registration &original-gate-descriptor=%D0%90+%D0%940%BD%D1%8C%D0%B3%D0%B8+-+card+registration&gate-partial-capture=enabled &type=preauth &name=CARDHOLDER+NAME &card-exp-month=6 &card-exp-year=2024 &email=22701231%40example.com &processor-rrn=21660934567 &approval-code=265470 &control=bbd11a020f6bsdkfgjh23e24def54991bfb63c5&last-four-digits=0214 &bin=220220&card-type=VISA &phone=%2B71914454778 &bank-name=Rabobank &card-hash-id=235479750 &card-country-alpha-three-code=RUS &ips-src-payment-product-code=VISA &ips-src-payment-product-name=VISA &ips-src-payment-type-code=Unknown &ips-src-payment-type-name=VISA+Unknown &initial-amount=1.50 &transaction-date=2022-06-15+12%3A37%3A02+CEST Сопоставление параметров обратного вызова и ответа на запрос статуса ================================================================================ .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Название параметра в обратного вызова - Название параметра в ответе на запрос статуса * - :code:`amount` - :code:`amount` * - :code:`approval-code` - :code:`approval-code` * - :code:`bin` - :code:`bin` * - :code:`card-type` - :code:`card-type` * - :code:`last-four-digits` - :code:`last-four-digits` * - :code:`bank-name` - :code:`bank-name` * - :code:`name` - :code:`name` * - :code:`first-name` - :code:`first-name` * - :code:`last-name` - :code:`last-name` * - :code:`country` - :code:`country` * - :code:`state` - :code:`state` * - :code:`city` - :code:`city` * - :code:`zip_code` - :code:`zip_code` * - :code:`address1` - :code:`address1` * - :code:`card-exp-month` - :code:`card-exp-month` * - :code:`card-exp-year` - :code:`card-exp-year` * - :code:`client_orderid` - :code:`merchant-order-id` * - :code:`comment` - :code:`comment` * - :code:`descriptor` - :code:`descriptor` * - :code:`dest-bin` - :code:`dest-bin` * - :code:`dest-card-type` - :code:`dest-card-type` * - :code:`dest-last-four-digits` - :code:`dest-last-four-digits` * - :code:`dest-bank-name` - :code:`dest-bank-name` * - :code:`email` - :code:`email` * - :code:`purpose` - :code:`purpose` * - :code:`error_code` - :code:`error-code` * - :code:`error_message` - :code:`error-message` * - :code:`gate-partial-capture` - :code:`gate-partial-capture` * - :code:`gate-partial-reversal` - :code:`gate-partial-reversal` * - :code:`loyalty-balance` - :code:`loyalty-balance` * - :code:`loyalty-bonus` - :code:`loyalty-bonus` * - :code:`loyalty-message` - :code:`loyalty-message` * - :code:`loyalty-program` - :code:`loyalty-program` * - :code:`merchant_order` - :code:`merchant-order-id` * - :code:`merchantdata` - :code:`merchantdata` * - :code:`orderid` - :code:`paynet-order-id` * - :code:`original-gate-descriptor` - :code:`original-gate-descriptor` * - :code:`phone` - :code:`phone` * - :code:`processor-rrn` - :code:`processor-rrn` * - :code:`processor-tx-id` - :code:`processor-tx-id` * - :code:`rapida-balance` - :code:`rapida-balance` * - :code:`reason-code` - :code:`reason-code` * - :code:`serial-number` - :code:`serial-number` * - :code:`status` - :code:`status` * - :code:`type` - :code:`transaction-type` * - :code:`initial-amount` - :code:`initial-amount` * - :code:`seller-commission` - :code:`seller-commission` * - :code:`acquirer-commission` - :code:`acquirer-commission` * - :code:`exchange-rate` - :code:`exchange-rate` * - :code:`effective-exchange-rate` - :code:`effective-exchange-rate` * - :code:`card-country-alpha-three-code` - :code:`card-country-alpha-three-code` * - :code:`destination-card-country-alpha-three-code` - :code:`destination-card-country-alpha-three-code` Пример проверки контрольной суммы в Java ============================================================================== Ниже предоставлен пример проверки контрольной суммы в обратном вызове для языка программирования Java: .. highlight:: java :: import org.junit.Test; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import static org.junit.Assert.assertEquals; public class TestCallbackSignatureExampleTest { @Test public void test() { String digest3 = calculateCallbackSignature("approved", 123, "invoice-1", "AF4B5DE6-3468-424C-A922-C1DAD7CB4509"); assertEquals("5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1", digest3); } public String calculateCallbackSignature(String aTransactionStatus, long aOrderId, String aMerchantOrderId, String aMerchantControlKey) { String text = aTransactionStatus + aOrderId + aMerchantOrderId + aMerchantControlKey; byte[] buffer = text.getBytes(StandardCharsets.UTF_8); byte[] shaSum = sha(buffer); return toHexString(shaSum); } /** * Calculates the SHA-1 digest and returns the value as a byte[]. * * @param data * Data to digest * @return SHA-1 digest */ private static byte[] sha(byte[] data) { try { MessageDigest digest = MessageDigest.getInstance("SHA"); return digest.digest(data); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException("Couldn't calculate SHA-1 digest", e); } } /** * Converts bytes to hex string */ private static String toHexString(byte[] data) { StringBuilder sb = new StringBuilder(); for (byte b : data) { String hex = Integer.toHexString(0xff & b); if (hex.length() == 1) { sb.append('0'); } sb.append(hex); } return sb.toString(); } }