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

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

Если Присоединяющаяся Сторона указывает 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.payneteasy.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.payneteasy.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.payneteasy.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.payneteasy.com

Описание

${status}

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

${merchant_order}

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

${orderid}

Идентификатор заказа в системе gate.payneteasy.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.payneteasy.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();
    }

}