Callbacks¶
Callbacks позволяют получать уведомления, когда изменяется статус операции.
Чтобы настроить Callbacks для операций, необходимо задать адрес в callback_url
в настройках интеграции или отправлять этот параметр в запросе.
Note
Callback — асинхронная функция, поэтому не рекомендуется для задач с жестким ограничением по времени. Существует вероятность, что ваше приложение получит сообщения не в порядке отправки или они продублируются. Поэтому в дополнение к Callbacks мы рекомендуем использовать реконсиляцию (сверку) по API для обновления данных в системе.
Настройка¶
Для настройки Callbacks вам нужно перейти к настройкам аккаунта и добавить значение «Callback URL».
Формат сообщения¶
HTTP запрос, который мы отправим на ваш callback_url
, будет обладать следующими характеристиками:
- это будет POST запрос;
- тело запроса будет передано в JSON API формате;
- объекты
type
иid
обязательно будут в теле запроса (а не в URL-параметре).
{
"data": {
"type": "payment-invoices",
"id": "cpi_yv1RgJ2l8ty2AxIs",
"attributes": {
"serial_number": "yv1RgJ2l8ty2AxIs",
"status": "processed",
"resolution": "ok",
"moderation_required": false,
"amount": 22,
"payment_amount": 22,
"currency": "USD",
"service_currency": "USD",
"reference_id": "da1b0b9d-c249-4f6e-9949-2a2f2d4b1758",
"test_mode": true,
"fee": 0,
"deposit": 22,
"processed": 1592232071,
"processed_amount": 22,
"refunded_amount": null,
"processed_fee": 0,
"processed_deposit": 22,
"metadata": {
"merchant_url": "https://yu.test.this"
},
"flow_data": {
"action": "https://example.domain/hpp/cgi_Q0fYDFaHlqb5MCdl",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_Q0fYDFaHlqb5MCdl",
"token": "eyJ0eXAiOiJKV1QiLRiGCg2O...nGE7E"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1592232050,
"updated": 1592232071,
"payload": {
"token": null,
"client_ip": "54.36.117.30",
"payment_card": {
"last": "0000",
"mask": "512381******0000",
"brand": "mastercard",
"first": "512381",
"holder": null,
"expiry_year": "33",
"issuer_name": "FIRST DATA CORPORATION",
"expiry_month": "11",
"issuer_country": "US"
}
},
"description": null,
"descriptor": null,
"callback_url": "https://test.doc.home",
"return_url": "https://example.com",
"return_urls": {
"fail": "https://example.com/sorry-page",
"pending": "https://example.com/wait-for-it-page",
"success": "https://example.com/thank-you-page"
},
"original_data": null,
"rrn": null,
"approval_code": null,
"reserved_amount": null,
"reserve_expires": null,
"unreserved": null,
"source": null,
"callback_logs": []
},
"relationships": {
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
},
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"customer": {
"data": null
}
},
"links": {
"self": "/api/payment-invoices/cpi_yv1RgJ2l8ty2AxIs"
}
}
}
{
"data": {
"type": "payout-invoices",
"id": "cpoi_sIzOuMKJg98J22NC",
"attributes": {
"serial_number": "sIzOuMKJg98J22NC",
"status": "processed",
"resolution": "ok",
"amount": 100,
"payout_amount": 100,
"currency": "USD",
"service_currency": "USD",
"service_amount": 100,
"service_payout_amount": 100,
"reference_id": "45284707-d243-439e-8b41-d657322e693b",
"test_mode": true,
"description": null,
"fee": 0,
"writeoff": 100,
"exchange_rate": 1,
"processed": 1621335982,
"processed_amount": 100,
"processed_fee": 0,
"processed_writeoff": 100,
"metadata": [],
"created": 1621335974,
"updated": 1621335982,
"fields": {
"card_number": "512381******0000"
},
"callback_url": "https://test.doc.home",
"source": "merchant_dashboard",
"callback_logs": [],
"payouts": [
{
"id":"po_4a3Bgz6YR3cRjW6k",
"rrn":null,
"amount":72.5,
"currency":"USD",
"status":"processed"
},
{
"id":"po_3cR4z6kgYR6aj3BW",
"rrn":null,
"amount":27.5,
"currency":"USD",
"status":"processed"
}
]
},
"relationships": {
"payout-service": {
"data": {
"type": "payout-services",
"id": "payment_card_usd"
}
},
"payout-method": {
"data": {
"type": "payout-methods",
"id": "payment_card"
}
},
"customer": {
"data": null
}
},
"links": {
"self": "/api/payout-invoices/cpoi_sIzOuMKJg98J22NC"
}
}
}
Тело запроса Callback содержит тело соответствующей операции инвойса.
Статусы инвойсов описаны в руководствах:
Проверка подлинности¶
PaymentsTrust подписывает данные, используя ключи в хедере запроса X-Signature
.
Алгоритм генерации:
$signature = base64_encode(sha1($secret . $callbackData . $secret, true));
- где
$secret
— боевой ("Live key") или тестовый ("Test key") секретный (приватный) ключ, который находится в настройках аккаунта; -
$callbackData
— неформатированный JSON код.
Чтобы убедиться в достоверности источника, сгенерируйте подпись, используя соответствующий ключ, и сравните с данными в Callback.
Превышение времени ожидания (тайм-аут)¶
PaymentsTrust выделяет три типа тайм-аутов для Callbacks:
- Тайм-аут соединения (Connection Timeout): граничное время для установления начального соединения с HTTP-сервером URL Callbacks.
- Тайм-аут чтения (Read Timeout): граничное время сообщения о получении данных HTTP сервером после установки соединения.
- Общий тайм-аут отправки Callbacks (Execution Timeout): в дополнение к предыдущим PaymentsTrust также проверяет общее время выполнения Callbacks.
Значения тайм-аутов:
Тип | Для тестового соединения | Для боевого соединения |
---|---|---|
Connection Timeout | 10,000 мс | 20,000 мс |
Read Timeout | 10,000 мс | 20,000 мс |
Execution Timeout | 20,000 мс | 60,000 мс |
Доставка Calbacks и автоповтор отправки¶
Дальнейшие действия определяются по HTTP-коду, полученному в ответе на отправку Callbacks:
Код | Значение | Дальнейшие действия системы |
---|---|---|
200 | Callback успешно доставлен | Повторная отправка не требуется, следующие запланированные попытки доставки аннулируются |
429 | Слишком много запросов, Callback не принят | Повторная отправка принудительно остановлена, следующие запланированные попытки доставки аннулируются |
Любой другой HTTP-код в ответе означает, что запрос не доставлен. По умолчанию запрос повторно отправляется с промежутком ожидания между попытками:
- 1-й повтор запроса будет отправлен спустя 1 минуту после начальной попытки;
- 2-й повтор — спустя 2 минуты после 1-го повтора;
- 3-й — спустя 3 минуты после 2-го;
- 4-й — спустя 4 минуты после 3-го;
- 5-й — спустя 5 минут после 4-го;
- и 6-й — спустя 6 минут после 5го.
- и т.д. до 100 попыток или до получения
200
или429
HTTP-кода.
Существует возможность настройки интервала отправки и количества попыток
Отправьте запрос нашей службе поддержки , чтобы мы вместе подобрали наиболее подходящий вариант.
Note
Вы можете переотправить запрос c панели управления, если хотите синхронизировать данные немедленно. Для этого нужно перейти к обзору транзакции, выбрать вкладку Callbacks и кнопку Отправить заново.
Дублирование¶
Из-за повторной отправки Callbacks есть вероятность, что приложение получит одни и те же данные несколько раз. Вы можете убедиться в идемпотентности операции (свойстве объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом), обнаружив такие дубликаты в данных приложения.
Это не является проблемой, если приложение определяет идемпотентность. Для контроля используйте параметр id
в данных запроса Callbacks, т.к. его значение является уникальным для операции.
Пакетная обработка¶
Мы связываем Callbacks для близких статусов. Так, если платеж сразу же перешел из статуса created
(создан) в статус pending
(в обработке) и в статус processed
(обработан), вы получите только один Callback с последним по времени статусом (т.е. processed
).
Преимущество такого подхода: возможность избежать перегрузки ваших серверов HTTP запросами и избавить ваше приложение от необходимости усложнять логику взаимодействия с последовательными изменениями статуса. Ваше приложение должен заботить только последний статус объекта.
Доставка не по порядку¶
Callbacks могут приходить не по порядку из-за неполадок сети или сбоев отправки. Вы все равно можете установить правильную последовательность событий, ориентируясь на атрибут updated
в Callbacks — временную отметку в Timestamp формате.
IP-адреса¶
Для повышения безопасности взаимодействия между платформой PaymentsTrust и вашим сервером, необходимо использовать белый список IP-адресов.