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:

1 2 3 { "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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 }