Автоматические уведомления

Автоматические уведомления (Webhooks) - способ вызова скрипта на вашем веб-сервере всякий раз, когда происходит обработка транзакции или подписки.

Настройка автоматических уведомлений

Для того, чтобы получать автоматические уведомления от системы Overpay, передайте параметр notification_url в запросе на проведение транзакции.

{
    ....

    "notification_url":"https://your-domain.com/notification",

    ....
}

Запрос на автоматические уведомления имеет авторизацию типа Basic с ID и Secret key магазина как имя пользователя и пароль соответственно.

Проверка уведомлений

Уведомление от системы Overpay содержит такие же параметры, как и запрос на проведение транзакции или на оплату подписки.

В заголовке Content-Signature находится RSA цифровая подпись запроса, сформированная с помощью закрытого RSA ключа магазина, известного только Overpay.

Если вам необходимо проверять подлинность и целостность уведомлений, проверяйте цифровую подпись запроса на своей стороне с помощью вашего RSA публичного ключа и сравнивайте с той, что приходит в запросе. Совпадение подтверждает, что уведомление было отправлено от системы Overpay и пришло к вам в оригинальном виде.

Info

При реализации проверки подписи, обратите внимания на следующие моменты:

Хэш вычисляется функцией SHA256;
В качестве ключа используется публичный ключ, который можно получить в личном кабинете;
Вычисленное значение передается в кодировке base64.

Info

При интеграции виджета с использованием публичного ключа, при проверке полученного автоматического уведомления, обратите внимание на следующие параметры:

amount (сумма),
currency (валюта платежа),
test (не является ли транзакция тестовой),
tracking_id (идентификатор транзакции, присвоенный торговцем).

Warning

При проверке подписи необходимо использовать тело полученного автоматического уведомления в том виде, в котором оно получено, без его сериализации/десериализации в/из JSON.

Примеры PHP кода проверки цифровой подписи

# shop_public_key - публичный ключ вашего магазина
# signature - значение параметра Content-Signature
# rawBody - тело запроса уведомления

$rawBody = file_get_contents('php://input');

$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 = request.body.bytes.to_a.pack('c*') # Тело запроса уведомления в байтовом формате

public_key = OpenSSL::PKey::RSA.new(Base64.decode64(shop_public_key))

public_key.verify(OpenSSL::Digest::SHA256.new, Base64.decode64(signature), request_raw_body)

Обработка уведомлений

Ваш веб-сервер должен вернуть HTTP статус 200, если уведомление было обработано успешно. Иначе, через некоторое время, Overpay повторно вышлет уведомление.

Расписание повторных автоматических уведомлений

Интервалы между повторными попытками увеличиваются экспоненциально, при этом в расчёте каждого интервала используется случайная составляющая.

В результате, фактический интервал между попытками попадает в определённый диапазон, который зависит от номера попытки. Примерные значения интервалов приведены в таблице ниже.

Retries

Сервис	Количество повторных попыток	Формула расчета интервала - count – порядковый номер повторной попытки; - rand(30) – случайное число от 0 до 29; - .to_i — преобразование в целое число.	Интервалы между соседними попытками	Абсолютные интервалы
Checkout	2	`count⁴ + 15 + (rand(30) * (count + 1))`	1я повторная попытка: 15 секунд, 2 повторная попытка: 0.5–2 минуты.	1я повторная попытка: 15 секунд, 2 повторная попытка: 46 секунд – 2.5 минуты.
Сервис обработки карточных транзакций	15	`((2.12 * count).to_i)³ + (rand(30) * (count +1))`	1я повторная попытка: 8–66 секунд; 2: 1–3 минуты; 3: 3–6 минут; 4: 8–11 минут; 5: 16–20 минут; 6: 28–33 минуты; 7: 45–50 минут; 8: 68–73 минуты; 9: 114–120 минут; 10: ≈ 2.5 часа; 11: ≈ 3.5 часа; 12: ≈ 4.5 часа; 13: ≈ 5.5 часов; 14: ≈ 7 часов; 15: ≈ 8.5 часов.	1я повторная попытка: 8–66 секунд; 2: 1–4 минуты; 3: 4–10 минут; 4: 13–21 минута; 5: 30–40 минут; 6: 58–72 минуты; 7: 1–2 часа; 8: 2–3.5 часа; 9: 4–5.5 часов; 10: ≈ 7 часов; 11: ≈ 10–11.5 часов; 12: ≈ 15–16 часов; 13: ≈ 20–21.5 часа; 14: ≈ 27–28.5 часов; 15: ≈ 35.5–37 часов.
Сервис обработки транзакций с помощью альтернативных платежных методов	15	`((2.12 * count).to_i)³ + (rand(30) * (count +1))`
Сервис подписок	25	`сount⁴ + 15 + (rand(30) * (count + 1))`	1я повторная попытка: 15 секунд; 2: 0.5–2 минуты; 3: 1–4 минуты; 4: 4–7 минут; 5: 10–14 минут; 6: 21–26 минут; 7: 40–45 минут; 8: 68–73 минуты; 9: 109–115 минут; 10: ≈ 3 часа; 11: ≈ 4 часа; 12: ≈ 6 часов; 13: ≈ 8 часов; 14: ≈ 11 часов; 15: ≈ 14 часов; 16: ≈ 18 часов; 17: ≈ 24 часа; 18–25: 36–109 часов.	1я повторная попытка: 15 секунд; 2: 0.5–2 минуты; 3: 2–6 минут; 4: 6–13 минут; 5: 17–27 минут; 6: 39–52 минуты; 7: 1–2 часа; 8: 2–3 часа; 9: 4–5 часов; 10: 7–8 часов; 11: 11–12 часов; 12: 16–18 часов; 13: 24–26 часов; 14: 35–37 часов; 15: 49–51 час; 16: 67–69 часов; 17: 91–93 часа; 18–25: 5–25 дней.

Пример уведомления при оплате

{
  "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": 2027,
      "token_provider": null,
      "token": null
    },
    "receipt_url": "https://backoffice.overpay.io/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.overpay.io/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": "john@example.com",
      "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": 2027,
    "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://api.overpay.io/plans/pln_7f2e3edfbca72afc/pay",
    "payment_url": "https://api.overpay.io/plans/pln_7f2e3edfbca72afc/pay",
    "confirm_url": "https://checkout.overpay.io/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": 2027
  },
  "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": 2027
  },
  "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":"jake@example.com"
  },
  "finished":false,
  "expired":true,
  "shop":{
    "name":"Shop",
    "url":"http://127.0.0.1:3009",
    "contact_email":"qwfpg@gmail.com",
    "contact_phone":"123456789",
    "brands":[
      "visa",
      "master",
      "maestro",          
      "erip"
    ]
  },
  "test":false,
  "status":"error",
  "message":"Token is expired.",
  "payment_method":{
    "id":9,
    "checkout_data_id":9,
    "types":[
      "erip"
    ],
    "data":{ 
      "erip":{
        "order_id":"order_id",
        "account_number":"123",
        "service_no":"99999999"
      }
    },
    "created_at":"2017-06-01T13:00:14.506Z",
    "updated_at":"2017-06-01T13:00:14.506Z"
  }
}