Callback

Callback - це повідомлення клієнта про те, що сталась якась подія за допомогою HTTP запиту. Система UAPAY робить HTTP запит з методом POST на вказаний клієнтом URL. Формат переданих даних - JSON. Запит підписується за допомогою JWT-токена, докладніше про це тут.

Обов'язково! Для отримання callback з продуктового середовища, необхідно передати вашому персональному менеджеру UAPAY, URL, на який ви хочете їх отримувати, і після підтверждення, ваш URL буде внесено в список дозволених для отримання callback.
При зміні IP-адреси вашого сервісу - попереджати персонального менеджера UAPAY, щоб вашу нову IP-адресу внесли до списку дозволених для отримання callback.

Приклад підписаного тіла запиту callback у вигляді JWT-токена:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50SWQiOiI2MWI5YTVkNS1kNDI5LTQ4ZmEtYjAxYy0yZjhkYzc1ZjIwMjMiLCJpbnZvaWNlSWQiOiIxY2ZkZWE0My0xMGYwLTQwYzgtOWZlOC01NWQzOGY0OGI5YmMiLCJleHRlcm5hbElkIjoiMGY5MWJiOTAtODhlZS00ZjJhLThiNzUtOTNiZGNiNjE0NGVjIiwicGF5bWVudE51bWJlciI6MjQ5NTAzLCJjYXJkRnJvbU1hc2tlZCI6IjQxMTExMTExMTEiLCJjYXJkVG9NYXNrZWQiOm51bGwsImFtb3VudCI6MTAwMDAwLCJzdGF0dXMiOiJGSU5JU0hFRCIsInR5cGUiOiJQQVkiLCJzeXN0ZW1UeXBlIjoiRUNPTSIsInBheW1lbnRTdGF0dXMiOiJGSU5JU0hFRCIsInJlY2VpcHRQYXRoIjoiaHR0cHM6Ly9hcGkuc3RhZ2UudWFwYXkudWEvYXBpL2FjcXVpcmluZy9yZWNlaXB0cy92Mi82MWI5YTVkNS1kNDI5LTQ4ZmEtYjAxYy0yZjhkYzc1ZjIwMjMucGRmIiwiZXh0cmFJbmZvIjoie1wiZG9jSWRcIjpcIjA5OTQ3ODA0MDJcIixcInNwcm90b2NvbFwiOlwi0KLQldCh0KJcIixcIm5wcm90b2NvbFwiOlwiMjQyMzg1MlwiLFwibGljZW5zZVBsYXRlXCI6XCJmaW5lU2VyaWVzXCJ9IiwiY3JlYXRlRGF0ZSI6IjIwMjEtMDQtMTJUMTA6MDM6MTAuMDAwWiIsInBheURhdGUiOiIyMDIxLTA0LTEyVDEwOjAzOjMxLjg3NFoiLCJpYXQiOjE2MTgyMjE4MTF9.qfbEOHLPka3YW6z0J0FygRx4Sw5R5g6jyjFF6bFhU2g"
}

Також є гарантований механізм доставки callback - крім першої спроби доставки, є ще 5 спроб протягом наступної доби з інтервалами між запитами - 5 с, 5 хв, 1 год, 2 год, 24 год.

Callback вважається доставленим, якщо у відповідь на запит прийшов HTTP status code 200.

Метод перезапиту постбеків

Метод перезапиту постбеків які не були доставлені використовується у випадках, коли по будь-якій з причин один та більше постбеків не були доставлені на вказаний клієнтом URL.

URI

POST /api/callbacks/resend

Запит:

Ключ	Опис	Тип	Чи обов'язковий параметр?	Приклад

Ключ	Опис	Тип	Чи обов'язковий параметр?	Приклад
params
sessionId	id сесії клієнта	string, uuid	так	"52be10d0-d094-4ede-b201-904783df5f8d"

{  
   "params":{  
      "sessionId":"9499b6f1-907c-4907-93bf-5d89bda6c40a"
   }
}

Успішна відповідь:

Ключ	Опис	Тип	Приклад

Ключ

Опис

Тип

Приклад

status

Статус.

0 - помилка, 1 - успіх

integer

1

data

object

success

результат запиту. Можливі варіанти: true,

boolean

true

{
    "status": 1,
    "data": {
        "success": true
    }
}

Неуспішна відповідь:

Ключ	Опис	Тип	Приклад

Ключ	Опис	Тип	Приклад
status	Статус. 0 - помилка, 1 - успіх	integer	1
error	результат запиту. Можливі варіанти: true	boolean	true
error.code	код помилки	string	“TOO_MANY_REQUESTS“
error.message	текст помилки	string	"You already resended postbacks"

{
    "status": 0,
    "error": {
				"code": "TOO_MANY_REQUESTS",
				"message": "You already resended postbacks"
    }
}

Callback зміни статусу платежу інвойсу

Для отримання callback з інформацією про зміни статусу платежу інвойсу потрібно передати URL в поле callbackUrl на створення інвойсу.

Поля тіла callback:

Ключ	Тип	Опис

Ключ	Тип	Опис
callbackType	string	Тип колбеку
paymentId	uuid	ID платежу
invoiceId	uuid	ID інвойсу
externalId	string	зовнішній ID інвойсу
paymentNumber	integer	номер платежу
cardFromMasked	string	маскований номер картки списання
cardToMasked	string	маскований номер картки зарахування
cardFromHolderName	string	ім'я та прізвище тримача карти
amount	integer	сума платежу
reversalAmount	integer	сума повернення платежу
status	string	статус платежу
type	string	тип інвойсу
systemType	string	тип платіжного сервісу
paymentStatus	string	детальний статус платежу в платіжному сервісі
receiptPath	string	посилання на квитанцію
extraInfo	string	додаткова інформація інвойсу
createDate	string	дата створення платежу
payDate	string	дата успішного завершення платежу
holdDate	string	дата холда платежу
rrn	string	RRN платежу
approvalCode	string	Код авторизації
cardSchema	string	Тип картки
merchantId	string	ID мерчанта
terminalId	string	ID терміналу

Приклад:

{
  "callbackType": "PAYMENT_STATUS_CHANGED",
  "paymentId": "61b9a5d5-d429-48fa-b01c-2f8dc75f2023",
  "invoiceId": "1cfdea43-10f0-40c8-9fe8-55d38f48b9bc",
  "externalId": "0f91bb90-88ee-4f2a-8b75-93bdcb6144ec",
  "paymentNumber": 249503,
  "cardFromMasked": "4111111111",
  "cardToMasked": null,
  "cardFromHolderName": "CARDHOLDER NAME",
  "amount": 100000,
  "reversalAmount": 0,
  "status": "FINISHED",
  "type": "PAY",
  "systemType": "ECOM",
  "paymentStatus": "FINISHED",
  "receiptPath": "https://api.stage.uapay.ua/api/acquiring/receipts/v2/61b9a5d5-d429-48fa-b01c-2f8dc75f2023.pdf",
  "extraInfo": "{\"docId\":\"0994780402\",\"sprotocol\":\"ТЕСТ\",\"nprotocol\":\"2423852\",\"licensePlate\":\"fineSeries\"}",
  "createDate": "2021-04-12T10:03:10.000Z",
  "payDate": "2021-04-12T10:03:31.874Z",
  "iat": 1618221811,
  "rrn": "001014048213",
  "approvalCode": "984019",
  "cardSchema": "mastercard",
  "merchantId": "01002003DS00001",
  "terminalId": "232535b6-2095-413e-ba57-12516d4df89a"
}

Callback зміни статусу P2P платежу

Для отримання callback з інформацією про зміни статусу P2P платежу потрібно передати URL в поле callbackUrl на створення P2P платежу.

Поля тіла callback:

Ключ	Тип	Опис

Ключ	Тип	Опис
paymentSystem	string	тип платіжного сервісу
paymentId	uuid	ID платежу
operationId	uuid	ID операції
operationType	string	тип операції
operationStatus	string	статус операції
paymentType	string	тип платежу
paymentNumber	string	номер платежу
paymentAmount	integer	сума платежу
paymentCommission	integer	сума комісії
paymentStatus	string	статус платежу
postbackTime	string	час формування запиту
cardFromMasked	string	маскований номер картки списання
cardFromId	uuid	ID картки списання
cardToMasked	string	маскований номер картки зарахування
cardToId	uuid	ID картки зарахування
operationExternalId	string	зовнішній ID платежу
reason	object	об'єкт з деталями помилки
confirmation	object	об'єкт з деталями підтвердження
key	string	ключ, який потрібен для підтвердження платежу

Приклад:

{
  "paymentSystem": "p2p",
  "paymentId": "e6edab68-da39-4a99-8fcb-e6974f6d3078",
  "operationId": "47106586-63ef-45ef-8560-038f646fc709",
  "operationType": "SEND",
  "operationStatus": "FINISHED",
  "paymentType": "BUCKET",
  "paymentNumber": "17639513",
  "paymentAmount": 1000,
  "paymentPendingAmount": 1000,
  "paymentCommission": 200,
  "paymentStatus": "PAYED",
  "postbackTime": 1618311873588,
  "cardFromMasked": "4111111111",
  "cardFromId": "f68484b7-9f85-4c94-8b91-c364cd5b6d0b",
  "cardToMasked": null,
  "cardToId": null,
  "operationExternalId": "985293a9-4b8b-411d-9e61-d82e8e8bb239",
  "iat": 1614370565
}

Callback помилки при неуспішному поверненні по платежу чи complete/cancel по інвойсу

Цей постбек надсилається у випадку, якщо виникла помилка під час таких операцій:

Скасування платежу з типом HOLD
Завершення платежу з типом HOLD
Повернення платежу (refund)

Постбек містить детальну інформацію про помилку (код, повідомлення, технічні деталі), що дозволяє дізнатися, якщо операція не була виконана.

Постбек активується через увімкнення відповідної опції (для увімкнення потрібно звернутися до вашого менеджера).

Поля тіла callback:

Ключ	Тип	Опис

Ключ	Тип	Опис
callbackType	string	Тип колбеку
paymentId	UUID	ID платежу
invoiceId	UUID	ID інвойсу
externalId	string	Зовнішній ID інвойсу
paymentNumber	integer	Номер платежу
status	string	Статус платежу
type	string	Тип інвойсу
systemType	string	Тип платіжного сервісу
paymentStatus	string	Детальний статус платежу в платіжному сервісі
method	string	Назва методу, який викликав подію. Можливі значення: 'reversePayment', 'cancelPayment', 'completePayment'
error
error.code	string	Код помилки
error.message	string	Опис помилки
error.responseCode	number	Цифровий код помилки

Приклад:

{
  "callbackType": "PAYMENT_TRANSITION_FAILED",
  "paymentId": "d3df6e08-44da-4bba-84d0-3463ab31274a",
  "invoiceId": "cec5de23-741c-433e-b727-98b0204f87ef",
  "externalId": "e1150fa3-61eb-4a5a-81cd-a3fe53cb03d1",
  "paymentNumber": 400793,
  "status": "FINISHED",
  "type": "PAY",
  "systemType": "ECOM",
  "paymentStatus": "FINISHED",
  "error": {
    "code": "TECHNICAL_ERROR",
    "message": "System error",
    "responseCode": 3
  },
  "method": "reversePayment"
}