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 |
Имя держателя карты. |
Адрес электронной почты плательщика. |
|
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
¤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
Сопоставление параметров обратного вызова и ответа на запрос статуса
Название параметра в обратного вызова |
Название параметра в ответе на запрос статуса |
---|---|
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 |
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();
}
}