3.60. Обратный вызов Присоединяющейся Стороны

Вводная информация

Если Присоединяющаяся Сторона указывает URL обратного вызова, Платёжный Шлюз отправляет HTTP GET запрос на этот URL, когда транзакция получает финальный статус вне зависимости от того, получен ли статус approved, declined или другой из финальных статусов. Это позволяет Присоединяющейся Стороне лучше контролировать процесс прохождения транзакции, например, осуществляя соответствующие пометки во внутренней системе учёта.

Предупреждение

Сервер Присоединяющейся Стороны должен отвечать на этот GET запрос статусом 200 OK согласно RFC, в противном случае Платёжный Шлюз продолжит попытки отправить обратный вызов в течение 30 раз за 14 дней с увеличивающимся интервалом между запросами.

Обратные вызовы являются гарантированным способом информирования Присоединяющейся Стороны о статусе транзакции. Присоединяющаяся Сторона должна принять меры, защищающие от получения одинакового обратного вызова дважды, что может произойти из-за сетевых или иных технических неполадок. Рекомендуется проверять status, type, orderid и client_orderid для защиты от дублирования транзакций в контуре Присоединяющейся Стороны.

URL обратного вызова могут быть указаны Присоединяющейся Стороной следующими способами:

  • Путём отправки server_callback_url или notify_url в инициирующем запросе на проведение транзакции. Если отправлен server_callback_url, Присоединяющаяся Сторона получит обратный вызов только по изначальной транзакции (например sale approved). Если вместо этого отправлен notify_url, Присоединяющаяся Сторона получит обратный вызов по изначальной транзакции, а также по всем последующим транзакциям, связанным с изначальной (например reversal, chargeback).

  • Путём указания URL обратного вызова на уровне терминала. Каждый тип транзакции может иметь свой URL обратного вызова.

Для URL обратного вызова разрешены только следующие порты:

  • для HTTP 80, 8080

  • для HTTPS 443, 8443

Настраиваемый URL обратного вызова

Обычный URL обратного вызова содержит все параметры, указанные в Параметрах обратного вызова.
Настраиваемый URL обратного вызова - это полностью определённый URL со всеми параметрами, необходимыми на конечной странице или скрипте обработки результата Присоединяющейся Стороной. Настраиваемый URL позволяет Присоединяющейся Стороне самостоятельно определить названия параметров, значения для которых определяются макросами в формате ${parameter_name}. Таким образом, gate.sbctech.ru заменяет соответствующие значения параметров в настраиваемом URL перед отправкой на запроса него. Доступные макросы перечислены в разделе Макросы обратного вызова.

Настраиваемый URL обратного вызова

https://connectingparty.com/sale_completed.php

Настраиваемый URL обратного вызова

https://connectingparty.com/sale_completed.php?cardholder_name=${name}&tx_status=${status}&order_id=${merchant_order}

Параметры обратного вызова

Примечание

Система автоматически добавляет нижеуказанные параметры к URL обратного вызова.
* - эти параметры не возвращаются в ответе по умолчанию. Для их получения необходимо связаться со службой поддержки.

Параметр

Описание

status

Подробности см. в Список статусов.

merchant_order

Идентификатор заказа в системе Присоединяющейся Стороны, аналогичен параметру client_orderid.

client_orderid

Идентификационный номер транзакции, присовенный Присоединяющейся Стороной.

orderid

Идентификатор заказа в системе gate.sbctech.ru.

type

Тип транзакции, например sale, reversal, chargeback.

amount

Фактическая сумма транзакции. Данное значение может быть изменено в ходе транзакции.

currency

Валюта транзакции.

descriptor

Дескриптор платежа, указанный на шлюзе, через который прошла транзакция.

error_code

Код ошибки. Данное поле не будет включено в обратный вызов, если статус транзакции status=approved.

error_message

Сообщение ошибки. Данное поле не будет включено в обратный вызов, если статус транзакции status=approved.

name

Имя держателя карты.

email

Адрес электронной почты плательщика.

Параметр country *

Страна плательщика (двухбуквенный код страны). Список допустимых кодов стран см. в Коды стран и штатов.

Параметр state *

Штат плательщика. Список допустимых кодов штатов см. в:ref:country-state-codes. Обязательно для США, Канады и Австралии.

Параметр city *

Город Плательщика.

Параметр zip_code *

Почтовый индекс Плательщика.

Параметр address1 *

Адрес Плательщика, строка 1.

approval-code

Код авторизации успешной транзакции, если присутствует.

last-four-digits

Последние четыре цифры номера карты плательщика.

bin

БИН карты плательщика.

card-type

Тип карты плательщика (VISA, MASTERCARD и т.д.).

phone

Номер телефона плательщика.

bank-name

Название банка плательщика.

card-exp-month

Месяц срока действия карты.

card-exp-year

Год срока действия карты.

gate-partial-reversal

Возможность проведения частичного возврата (enabled - возможно, disabled - невозможно).

gate-partial-capture

Возможность проведения частичного списания захолдированной суммы (enabled - возможно, disabled - невозможно).

reason-code

Причина возвратного платежа (chargeback) или метки о мошеннической операции.

processor-rrn

Уникальный идентификатор банковской транзакции, который назначается банком Эквайером.

comment

Комментарий, в случае возврата.

rapida-balance

Текущий баланс Присоединяющейся Стороны в системе Рапида (при наличии активной проверки баланса).

control

Контрольная сумма используется, чтобы убедиться, что callback Присоединяющейся стороне инициирует gate.sbctech.ru, а не мошенник. Это контрольная сумма SHA-1 от конкатенации status + orderid + merchant_order + merchant_control. Скрипт callback ОБЯЗАН проверить этот параметр, сравнив его с контрольной суммой SHA-1 указанной выше конкатенации.

merchantdata

Значение, переданное в соответствующем параметре инициирующего запроса Присоединяющейся Стороной.

serial-number

Серийный номер запроса.

processor-tx-id

Идентификатор транзакции, присвоенный процессором.

processor-auth-credit-code

Зарезервировано.

card-hash-id

Уникальный хеш карты, всегда одинаковый для этой карты.

verified-3d-status

Для транзакции, прошедшей проверку 3DS, вернётся значение AUTHENTICATED.

processor-credit-rrn

Уникальный идентификатор, который назначается банком Эквайером.

processor-credit-arn

Номер ссылки на карту эквайера для кредитной карты.

processor-debit-arn

Уникальный ссылочный идентификатор транзакции.

eci

Индикатор электронной коммерции (Visa).

ips-src-payment-product-code

Код карты, установленный международным платёжным сервисом (Visa/Mastercard).

ips-src-payment-product-name

Расшифрованный код карты, установленный международным платёжным сервисом (Visa/Mastercard).

ips-src-payment-type-code

Тип кода карты, установленный международным платёжным сервисом (Visa/Mastercard).

ips-src-payment-type-name

Расшифрованный тип кода карты, установленный международным платёжным сервисом (Visa/Mastercard).

card-country-alpha-three-code

Трёхбуквенный код страны Эмитента карты отправителя. См Коды стран.

destination-card-country-alpha-three-code

Трёхбуквенный код страны Эмитента карты получателя. См Коды стран.

initial-amount

Сумма, установленная при инициировании транзакции, без каких-либо сборов или комиссий. Это значение не может измениться в ходе транзакции.

Описание: customer-ip *

IP-адрес клиента

Параметр seller-commission *

Итоговая комиссия проведённой транзакции.

Параметр acquirer-commission *

Комиссия Эквайера для проведённой транзакции.

Описание: exchange-rate *

Базовый курс обмена валюты.

Параметр effective-exchange-rate *

Фактический курс обмена валюты.

Параметр motivational-message *

Опциональный параметр, содержаний сообщение с расширенной информацией по причине отклонения транзакции.

orig-amount

Изначальная сумма транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму.

orig-currency

Изначальная валюта транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму.

transaction-date

Callback receiving date and time.

Callback Macros

Название макроса gate.sbctech.ru

Описание

${status}

Статус транзакции, например approved, declined, processing и т.д.

${merchant_order}

Идентификатор заказа в системе Присоединяющейся Стороны, аналогичен параметру client_orderid.

${orderid}

Идентификатор заказа в системе gate.sbctech.ru.

${type}

Тип транзакции, например sale, return, chargeback и т.д.

${amount}

Сумма транзакции.

${descriptor}

Дескриптор платежа, указанный на шлюзе, через который прошла транзакция.

${error_message}

Сообщение ошибки, если ${status} = declined.

${name}

Имя держателя карты.

${email}

Адрес электронной почты плательщика.

${last-four-digits}

Последние четыре цифры номера карты плательщика.

${bin}

БИН карты плательщика.

${card-type}

Тип карты плательщика (VISA, MASTERCARD и т.д.).

${card-exp-month}

Месяц срока действия карты.

${card-exp-year}

Год срока действия карты.

${gate-partial-reversal}

Возможность проведения частичного возврата (enabled - возможно, disabled - невозможно).

${gate-partial-capture}

Возможность проведения частичного списания захолдированной суммы (enabled - возможно, disabled - невозможно).

${reason-code}

Причина возвратного платежа (chargeback) или метки о мошеннической операции.

${processor-rrn}

Уникальный идентификатор банковской транзакции, который назначается банком Эквайером.

${approval-code}

Код одобрения банка.

${comment}

Комментарий, в случае возврата.

${rapida-balance}

Текущий баланс Присоединяющейся Стороны в системе Рапида (при наличии активной проверки баланса).

${control}

Контрольная сумма используется, чтобы убедиться, что callback Присоединяющейся стороне инициирует gate.sbctech.ru, а не мошенник. Это контрольная сумма SHA-1 от конкатенации status + orderid + merchant_order + merchant_control. Скрипт callback ОБЯЗАН проверить этот параметр, сравнив его с контрольной суммой SHA-1 указанной выше конкатенации.

${merchantdata}

Значение, переданное в соответствующем параметре инициирующего запроса Присоединяющейся Стороной.

Пример обратного вызова

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
&currency=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

Сопоставление параметров обратного вызова и ответа на запрос статуса

Название параметра в обратного вызова

Название параметра в ответе на запрос статуса

amount

amount

approval-code

approval-code

bin

bin

card-type

card-type

last-four-digits

last-four-digits

bank-name

bank-name

name

name

first-name

first-name

last-name

last-name

country

country

state

state

city

city

zip_code

zip_code

address1

address1

card-exp-month

card-exp-month

card-exp-year

card-exp-year

client_orderid

merchant-order-id

comment

comment

descriptor

descriptor

dest-bin

dest-bin

dest-card-type

dest-card-type

dest-last-four-digits

dest-last-four-digits

dest-bank-name

dest-bank-name

email

email

purpose

purpose

error_code

error-code

error_message

error-message

gate-partial-capture

gate-partial-capture

gate-partial-reversal

gate-partial-reversal

loyalty-balance

loyalty-balance

loyalty-bonus

loyalty-bonus

loyalty-message

loyalty-message

loyalty-program

loyalty-program

merchant_order

merchant-order-id

merchantdata

merchantdata

orderid

paynet-order-id

original-gate-descriptor

original-gate-descriptor

phone

phone

processor-rrn

processor-rrn

processor-tx-id

processor-tx-id

rapida-balance

rapida-balance

reason-code

reason-code

serial-number

serial-number

status

status

type

transaction-type

initial-amount

initial-amount

seller-commission

seller-commission

acquirer-commission

acquirer-commission

exchange-rate

exchange-rate

effective-exchange-rate

effective-exchange-rate

card-country-alpha-three-code

card-country-alpha-three-code

destination-card-country-alpha-three-code

destination-card-country-alpha-three-code

Пример проверки контрольной суммы в Java

Ниже предоставлен пример проверки контрольной суммы в обратном вызове для языка программирования 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 <code>byte[]</code>.
    *
    * @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();
    }

}