Callback (en)

A callback is a client message on an event that has occurred using an HTTP request. The UAPAY system makes an HTTP request with the POST method to the URL specified by the client. The format of the transmitted data is JSON. The request is signed using a JWT token, more about this here.

Important! To receive a callback from the product environment, you must provide your personal UAPAY manager with the URL to which you want to receive them, and after confirmation, your URL will be included in the list of allowed URLs to receive a callback.
When changing the IP-address of your service, you have to notify personal UAPAY manager, so your new IP-address has been added to the list of allowed IP-addresses to receive a callback.

There is also a guaranteed callback delivery mechanism - in addition to the first delivery attempt, there are 5 more attempts during the next day with intervals between requests - 5 s, 5 min, 1 h, 2 h, 24 h.

The callback is considered delivered if an HTTP status code 200 is received in response to the request.

Example of a signed callback request body in the form of a JWT token:

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

Callback changes the status of the invoice payment

To receive a callback with information about changes in the status of the invoice payment, you need to pass the URL in the callbackUrl field to create an invoice.

Callback body fields:

Key	Type	Description

Key	Type	Description
paymentId	uuid	Payment ID
invoiceId	uuid	Invoice ID
externalId	string	external invoice ID
paymentNumber	integer	payment number
cardFromMasked	string	masked write-off card number
cardToMasked	string	masked enrollment card number
cardFromHolderName	string	name and surname of the card holder
amount	integer	payment amount
reversalAmount	integer	refund amount
status	string	payment status
type	string	invoice type
systemType	string	type of payment service
paymentStatus	string	detailed payment status in the payment service
receiptPath	string	receipt link
extraInfo	string	additional invoice information
createDate	string	date of payment creation
payDate	string	date of successful completion of payment
holdDate	string	payment holding date

Example:

{
  "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
}

Callback with changes in P2P payment status

To receive a callback with information about changes in the status of P2P payment, you need to pass the URL to the callbackUrl field to create a P2P payment.

Callback body fields:

Key	Type	Description

Key	Type	Description
paymentSystem	string	type of payment service
paymentId	uuid	Payment ID
operationId	uuid	Transaction ID
operationType	string	operation type
operationStatus	string	operation status
paymentType	string	payment type
paymentNumber	string	payment number
paymentAmount	integer	payment amount
paymentCommission	integer	commission amount
paymentStatus	string	payment status
postbackTime	string	request generation time
cardFromMasked	string	masked write-off card number
cardFromId	uuid	write-off card ID
cardToMasked	string	masked enrollment card number
cardToId	uuid	enrollment card ID
operationExternalId	string	external payment ID
reason	object	object with error details
confirmation	object	object with confirmation details
key	string	the key required to confirm the payment

Example:

{
  "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
}