Перейти к содержанию

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": "UAH",
        "service_currency": "UAH",
        "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_UAH_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": "UAH",
    "service_currency": "UAH",
    "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":"UAH",
                "status":"processed"
            },
            {
                "id":"po_3cR4z6kgYR6aj3BW",
                "rrn":null,
                "amount":27.5,
                "currency":"UAH",
                "status":"processed"
            }
        ]
    },
    "relationships": {
    "payout-service": {
        "data": {
        "type": "payout-services",
        "id": "payment_card_UAH"
        }
    },
    "payout-method": {
        "data": {
        "type": "payout-methods",
        "id": "payment_card"
        }
    },
    "customer": {
        "data": null
    }
    },
    "links": {
    "self": "/api/payout-invoices/cpoi_sIzOuMKJg98J22NC"
    }
  }
}

Тіло запиту Callback містить тіло відповідної операції інвойсу.

Статуси інвойсів описані в посібниках:

Перевірка автентичності

CASCAD підписує дані, використовуючи ключі у хедері запиту X-Signature.

Алгоритм генерації:

Алгоритм генерування підпису (PHP)

<?php
$secret="yourPrivateKey";    
$callbackData='{"data":{"type":"payment-invoices","id":"cpi_exampleID","attributes":{"serial_number":"exampleID","status":"processed","resolution":"ok","moderation_required":false,"amount":1000,"payment_amount":1000,"currency":"UAH","service_currency":"UAH","reference_id":"yourReferenceId","test_mode":true,"fee":38,"deposit":962,"processed":1647077297,"processed_amount":1000,"refunded_amount":null,"processed_fee":38,"processed_deposit":962,"metadata":[],"flow_data":{"action":"https:\/\/pay.example.com\/hpp\/cgi_exampleId","method":"GET","params":[],"metadata":{"sid":"cgi_exampleId","token":"bearerToken-for-H2H-api-auth"}},"flow":"hpp","payment_flow":"charge","created":1647077285,"updated":1647077297,"payload":{"token":"token-if-tokenize-true","auth_type":"card","client_ip":"192.168.0.1","payment_card":{"last":"0000","mask":"512381******0000","brand":null,"first":"512381","holder":"Test Customer","network":"mastercard","expiry_year":"99","issuer_name":"FIRST DATA CORPORATION","expiry_month":"09","issuer_country":"US"}},"description":null,"descriptor":null,"callback_url":"https:\/\/your.callback.url","return_url":null,"return_urls":{"fail":"https:\/\/your.fail-return.url","pending":"https:\/\/your.default-return.url","success":"https:\/\/your.success-return.url"},"original_data":null,"rrn":null,"approval_code":null,"reserved_amount":null,"reserve_expires":null,"unreserved":null,"source":"merchant_api","callback_logs":[],"charged_back_amount":null,"resolution_message":null,"hpp_url":"https:\/\/api.example.com\/hpp?cpi=cpi_exampleID"},"relationships":{"payment-service":{"data":{"type":"payment-services","id":"payment_card_UAH_hpp"}},"payment-method":{"data":{"type":"payment-methods","id":"payment_card"}},"customer":{"data":{"type":"customers","id":"cus_exampleID"}},"active-payment":{"data":{"type":"payments","id":"pay_exampleID"}}},"links":{"self":"\/api\/payment-invoices\/cpi_exampleID"}},"included":[{"type":"customers","id":"cus_exampleID","attributes":{"reference_id":"example-customer-id","email":null,"name":null,"phone":null,"description":null,"created":1646833439,"metadata":[],"avatar":"https:\/\/www.gravatar.com\/avatar\/exampleAvatarID?s=20&d=mm&r=g","archived":false,"processing_options":{"payment_enabled":true,"payout_enabled":true},"address":{"street":null,"country":null,"region":null,"city":null,"full_address":null,"post_code":null}},"relationships":{"commerce-account":{"data":{"type":"commerce-accounts","id":"coma_exampleID"}}}}]}';
$signature = base64_encode(sha1($secret . $callbackData . $secret, true));

echo $signature;
де $secret — бойовий ("Live key") або тестовий ("Test key") секретний (приватний) ключ, який знаходиться в налаштуваннях акаунту;

$callbackData — неформатований JSON код.

Щоб переконатися в достовірності джерела, згенеруйте підпис, використовуючи відповідний ключ і raw JSON тіло Callback.

В результаті ви отримаєте стрічку base64 вигляду:

B86Af35b/IfM0z0rGROHw5gVw14=

яка повинна бути аналогічною значенню підпису в хедері Callback.

Перевищення часу очікування (тайм-аут)

CASCAD виділяє три типи тайм-аутів для Callbacks:

  1. Тайм-аут з'єднання (Connection Timeout): граничний час для встановлення початкового з'єднання з HTTP-сервером URL Callbacks.
  2. Тайм-аут читання (Read Timeout): граничний час повідомлення про отримання даних HTTP сервером після встановлення з'єднання.
  3. Загальний тайм-аут надсилання Callbacks (Execution Timeout): на додаток до попередніх CASCAD також перевіряє загальний час виконання 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

Якщо потрібно синхронізувати дані негайно, можна перенаправити запит з панелі управління. Для цього потрібно перейти до огляду транзакції, вибрати вкладку Callbacks і кнопку Відправити заново.

Resend Callback

Дублювання

Через повторне відправлення Callbacks є ймовірність, що додаток отримає ті самі дані кілька разів. Ви можете переконатися в ідемпотентності операції (властивості об'єкта або операції при повторному застосуванні операції до об'єкта давати той самий результат, що і при першому), виявивши такі дублікати даних програми.

Те, що програма визначає ідемпотентність, не є проблемою. Для контролю використовуйте параметр id даних запиту Callbacks, т.к. його значення є унікальним для операції.

Пакетна обробка

Ми пов'язуємо Callbacks для найближчих статусів. Так, якщо платіж відразу ж перейшов із статусу created (створено) в статус pending (в обробці) і в статус processed (оброблено), ви отримаєте лише один Callback з останнім за часом статусом (тобто processed).

Перевага такого підходу полягає в тому, що він дає можливість уникнути перевантаження ваших серверів HTTP запитами та позбавити вашу програму необхідності ускладнювати логіку взаємодії з послідовними змінами статусу. Ваш додаток повинен піклуватися лише про останній статус об'єкта.

Доставка не по порядку

Callbacks можуть приходити не по порядку через неполадки мережі або збої відправки. Ви все одно можете встановити правильну послідовність подій, орієнтуючись на атрибут updated в Callbacks — часову позначку у Timestamp форматі.

IP-адреси

Для підвищення безпеки взаємодії між платформою CASCAD і вашим сервером, необхідно використовувати білий список IP-адрес.

Детальніше про домени та IP адреси →