Автоматические уведомления
Автоматические уведомления (Webhooks) - способ вызова скрипта на вашем веб-сервере всякий раз, когда происходит обработка транзакции или подписки.
Настройка автоматических уведомлений
Для того, чтобы получать автоматические уведомления от системы PayCross, передайте параметр notification_url в запросе на проведение транзакции.
{
....
"notification_url":"https://your-domain.com/notification",
....
}
Запрос на автоматические уведомления имеет авторизацию типа Basic с ID и Secret key магазина как имя пользователя и пароль соответственно.
Проверка уведомлений
Уведомление от системы PayCross содержит такие же параметры, как и запрос на проведение транзакции или на оплату подписки.
В заголовке Content-Signature находится RSA цифровая подпись запроса, сформированная с помощью закрытого RSA ключа магазина, известного только PayCross.
Если вам необходимо проверять подлинность и целостность уведомлений, проверяйте цифровую подпись запроса на своей стороне с помощью вашего RSA публичного ключа и сравнивайте с той, что приходит в запросе. Совпадение подтверждает, что уведомление было отправлено от системы PayCross и пришло к вам в оригинальном виде.
Info
При реализации проверки подписи, обратите внимания на следующие моменты:
- Хэш вычисляется функцией SHA256;
- В качестве ключа используется публичный ключ, который можно получить в личном кабинете;
- Вычисленное значение передается в кодировке base64.
Info
При интеграции виджета с использованием публичного ключа, при проверке полученного автоматического уведомления, обратите внимание на следующие параметры:
amount(сумма),currency(валюта платежа),test(не является ли транзакция тестовой),tracking_id(идентификатор транзакции, присвоенный торговцем).
Примеры PHP кода проверки цифровой подписи
# shop_public_key - публичный ключ вашего магазина
# signature - значение параметра Content-Signature
# rawBody - тело запроса уведомления
$public_key = str_replace(array("\r\n", "\n"), '', $shop_public_key);
$public_key = chunk_split($public_key, 64);
$public_key = "-----BEGIN PUBLIC KEY-----\n$public_key-----END PUBLIC KEY-----";
$signature = base64_decode($signature);
$key = openssl_pkey_get_public($public_key);
$a = openssl_verify($rawBody, $signature, $key, OPENSSL_ALGO_SHA256);
var_dump($a);
Примеры Ruby кода проверки цифровой подписи
require 'openssl'
require 'base64'
shop_public_key = "" # Публичный ключ вашего магазина
signature = "" # Значение параметра Content-Signature
request_raw_body = "" # Тело запроса уведомления
public_key = OpenSSL::PKey::RSA.new(Base64.decode64(shop_public_key))
if public_key.verify(OpenSSL::Digest::SHA256.new, Base64.decode64(signature), request_raw_body)
true
else
false
end
Обработка уведомлений
Ваш веб-сервер должен вернуть HTTP статус 200, если уведомление было обработано успешно. Иначе, через некоторое время, PayCross повторно вышлет уведомление.
Пример уведомления при оплате
{
"transaction": {
"uid": "dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"status": "successful",
"amount": 100,
"currency": "EUR",
"description": "Test transaction ütf",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "tracking_id_000",
"message": "Successfully processed",
"test": true,
"created_at": "2023-04-14T13:07:01.836Z",
"updated_at": "2023-04-14T13:07:05.530Z",
"paid_at": "2023-04-14T13:07:05.495Z",
"expired_at": null,
"recurring_type": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"credit_card": {
"holder": "John Doe",
"stamp": "d9a78f040a8427c65da2c5569e6411c3641a5537fcfd2d2bf9f866abf3611c7d",
"brand": "visa",
"last_4": "1006",
"first_1": "4",
"bin": "401200",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": null
},
"receipt_url": "https://admin.pay-cross.com/customer/transactions/dd6ee60c-d30a-4348-b84c-86a4ef1a137d/42fe9b2e3ed56e98b426e946882cd10d71cd8ee0593373b00196413e28338dd7?language=en",
"status_code": null,
"gateway": {
"iframe": true
},
"id": "dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"additional_data": {
"browser": {
"screen_width": 1920,
"screen_height": 1080,
"screen_color_depth": 24,
"language": "en",
"java_enabled": false,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
"time_zone": -180,
"time_zone_name": "Europe",
"accept_header": "json",
"window_height": 667,
"window_width": 600
}
},
"redirect_url": "https://gateway.pay-cross.com/process/dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "EUR",
"billing_descriptor": "test descriptor",
"gateway_id": 645,
"status": "successful"
},
"customer": {
"ip": "127.0.0.1",
"email": "[email protected]",
"device_id": "12312312321fff67",
"birth_date": "1980-01-31"
},
"billing_address": {
"first_name": "John 1",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": "4567898765467"
}
}
}
Пример уведомлений о пробной подписке
{
"id": "sbs_962f994ca74420d3",
"state": "trial",
"tracking_id": null,
"device_id": null,
"created_at": "2023-04-13T06:39:36.593Z",
"renew_at": "2023-05-13T06:41:26.581Z",
"active_to": "2023-05-13T06:41:26.581Z",
"card": {
"holder": "JOHN DOE",
"stamp": null,
"brand": "visa",
"last_4": "1006",
"first_1": "4",
"bin": null,
"issuer_country": null,
"issuer_name": null,
"product": null,
"token": "606760b7-74da-44fb-a730-13a9ee28d620",
"token_provider": null,
"exp_month": 12,
"exp_year": 2026,
"sub_brand": null
},
"customer": {
"id": "cst_4a708bf13a483278"
},
"paid_billing_cycles": 1,
"number_failed_payment_attempts": 0,
"additional_data": {},
"plan": {
"id": "pln_7f2e3edfbca72afc",
"title": "Test plan",
"name": "Test plan",
"description": "Subscription. Main period: €9.99 each 1 month. Trial: €4.99 each 1 month.",
"amount": 499,
"currency": "EUR",
"language": "en",
"infinite": true,
"billing_cycles": null,
"created_at": "2023-04-13T06:38:58.604Z",
"updated_at": "2023-04-13T06:38:58.604Z",
"trial": {
"amount": 499,
"interval": 1,
"interval_unit": "month"
},
"plan": {
"amount": 999,
"interval": 1,
"interval_unit": "month",
"visible_fields": [
"last_name",
"first_name",
"email"
]
},
"number_payment_attempts": 3,
"prevent_payments_at_night": true,
"test": true,
"pay_url": "https://data.pay-cross.com/plans/pln_7f2e3edfbca72afc/pay",
"payment_url": "https://data.pay-cross.com/plans/pln_7f2e3edfbca72afc/pay",
"confirm_url": "https://panel.pay-cross.com/v2/confirm_order/pln_7f2e3edfbca72afc/160"
},
"last_transaction": {
"uid": "971c8eb0-f4db-4a04-ba64-840e3427656e",
"status": "successful",
"message": "Successfully processed",
"created_at": "2023-04-13T06:41:22.913Z"
},
"event": "created.subscription"
}
Пример уведомления об продлении подписки
{
"card": {
"token": "2ed0b389f63c9198160bd7b8e98f6b42eb4c56e3b659a8070248b28cd3376d9d",
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"created_at": "2015-06-18T12:02:42.521Z",
"customer": {
"id": "cst_ae00d2582d001228"
},
"device_id": "any device_id",
"id": "sbs_f140af88af4aaf88",
"last_transaction": {
"created_at": "2015-01-12T09:04:59.000Z",
"message": "Successfully processed",
"status": "successful",
"uid": "4107-310b0da80b"
},
"plan": {
"currency": "USD",
"id": "pln_05e0756ed24eec5c",
"plan": {
"amount": 20,
"interval": 7,
"interval_unit": "day"
},
"title": "Title 1",
"trial": {
"amount": 10,
"interval": 40,
"interval_unit": "hour"
}
},
"renew_at": "2015-06-24T12:02:42.499Z",
"state": "active",
"tracking_id": "any tracking_id"
}
Пример уведомления об отмене подписки
{
"card": {
"token": "9990edb8e6f2af5d93a6259b690c50a7410bf9f97235f2e051345e01b580f699",
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"created_at": "2015-06-18T12:02:42.731Z",
"customer": {
"id": "cst_2a46e8b7ff87df2d"
},
"device_id": "any device_id",
"id": "sbs_1cc338f74bc9bfb7",
"last_transaction": null,
"plan": {
"currency": "USD",
"id": "pln_0b4ba2f1ab0c1988",
"plan": {
"amount": 20,
"interval": 7,
"interval_unit": "day"
},
"title": "Title 1",
"trial": {
"amount": 10,
"interval": 40,
"interval_unit": "hour"
}
},
"renew_at": null,
"state": "canceled",
"tracking_id": "any tracking_id"
}
Пример уведомления об истекшем сроке оплаты токена платежа
В случае неоплаты токена уведомление отправляется в сроки: дата истечения срока оплаты (expired_at) или через 24 часа после создания токена, если дата срока оплаты (expired_at) не задана.
{
"token":"311300d08dc7f22ae37272fac6513921d4c99ca24dcaccf4392a2606fe8f1877",
"shop_id":1,
"transaction_type":"payment",
"gateway_response":null,
"order":{
"currency":"USD",
"amount":4299,
"description":"Order description",
"tracking_id":null,
"additional_data":{
},
"expired_at":"2017-06-01T13:01:06.123Z"
},
"settings":{
"success_url":"http://127.0.0.1:4567/success",
"fail_url":"http://127.0.0.1:4567/fail",
"decline_url":"http://127.0.0.1:4567/decline",
"notification_url":"http://your_shop.com/notification",
"cancel_url":"http://127.0.0.1:4567/cancel",
"language":"en",
"customer_fields":{
"hidden":[
"phone",
"address"
],
"read_only":[
"email"
]
}
},
"customer":{
"first_name":null,
"last_name":null,
"address":null,
"city":null,
"country":null,
"state":null,
"phone":null,
"zip":null,
"email":"[email protected]"
},
"finished":false,
"expired":true,
"shop":{
"name":"Shop",
"url":"http://127.0.0.1:3009",
"contact_email":"[email protected]",
"contact_phone":"123456789",
"brands":[
"visa",
"master",
"maestro"
]
},
"test":false,
"status":"error",
"message":"Token is expired.",
"payment_method":{
"id":9,
"checkout_data_id":9,
"types":[],
"data":{ },
"created_at":"2017-06-01T13:00:14.506Z",
"updated_at":"2017-06-01T13:00:14.506Z"
}
}