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

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

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

Warning

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

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 status, type, orderid and client_orderid to prevent duplication of transactions on Connecting Party side.

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 обратного вызова

Simple callback URL contains all parameters listed in Параметры обратного вызова. Customizable callback URL is a fully defined URL with all the parameters Connecting Party target page or script would require. Customizable URL allows Connecting Party to define own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}. Thus gate.connpay.com substitutes respective parameter values into final customized URL before calling it. Available macros are listed in Callback Macros.

Настраиваемый 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.connpay.com.
type	Тип транзакции, например sale, reversal, chargeback.
amount	Фактическая сумма транзакции. Может быть изменена в процессе прохождения транзакции.
currency	Валюта транзакции.
descriptor	Дескриптор платежа, указанный на шлюзе, через который прошла транзакция.
error_code	Код ошибки.
error_message	Сообщение ошибки.
name	Имя держателя карты.
email	Адрес электронной почты плательщика.
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	Контрольная сумма, подтверждающая, что gate.connpay.com (а не мошенник) инициирует запрос. Представляет собой хеш SHA-1 от конкатенации параметров status + orderid + merchant_order + merchant-control. Проверка контрольной суммы Присоединяющейся Стороной обязательна для подтверждения отправителя обратного вызова.
merchantdata	Значение, переданное в соответствующем параметре инициирующего запроса Присоединяющейся Стороной.
serial-number	Серийный номер запроса.
processor-tx-id	Идентификатор транзакции, присвоенный процессором.
processor-auth-credit-code	Зарезервировано.
card-hash-id	Уникальный хеш карты, всегда одинаковый для этой карты.
verified-3d-status	Для транзакции, прошедшей проверку 3DS, вернётся значение AUTHENTICATED.
processor-credit-rrn	Уникальный идентификатор, который назначается банком Эквайером.
processor-credit-arn	Acquirer card reference number for credit card.
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	Сумма транзакции из инициирующего запроса, без комиссий. Не может быть изменена в процессе прохождения транзакции.
seller-commission	Итоговая комиссия проведённой транзакции.
acquirer-commission	Комиссия Экваёера для проведённой транзакции.
exchange-rate	Базовый курс обмена валюты.
effective-exchange-rate	Фактический курс обмена валюты.
orig-amount	Изначальная сумма транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму.
orig-currency	Изначальная валюта транзакции, если была применена конвертация валюты на подчинённом терминале в интеграции через Параллельную форму.

Callback Macros

Название макроса gate.connpay.com	Описание
${status}	Статус транзакции, например approved, declined, processing и т.д.
${merchant_order}	Идентификатор заказа в системе Присоединяющейся Стороны, аналогичен параметру client_orderid.
${orderid}	Идентификатор заказа в системе gate.connpay.com.
${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}	Bank approval code.
${comment}	Комментарий, в случае возврата.
${rapida-balance}	Текущий баланс Присоединяющейся Стороны в системе Рапида (при наличии активной проверки баланса).
${control}	Контрольная сумма, подтверждающая, что gate.connpay.com (а не мошенник) инициирует запрос. Представляет собой хеш SHA-1 от конкатенации параметров status + orderid + merchant_order + merchant-control. Проверка контрольной суммы Присоединяющейся Стороной обязательна для подтверждения отправителя обратного вызова.
${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();
    }

}