📡 What are the webhooks?

Webhooks are a powerful way to receive real-time notifications from our API about specific events. When certain events occur, such as a payment transaction, our system will send an HTTP POST request to a URL you've provided, allowing you to react to the event in your application. Let's dive into the webhook payload structure:

Request Headers

When setting up your webhook endpoint, make sure to handle incoming HTTP POSTrequests and consider including the following headers to handle the payload correctly:

Content-Type: application/json - Indicates that the request payload is in JSON format.

Request Body Example

{
    "RRN": "3524703829728",
    "Type": "JustPay",
    "Payer": {
        "Phone": null,
        "FullName": null
    },
    "Token": "B91LLM0TEST64349UP1B0A670",
    "Amount": 51.5,
    "Refund": {
        "RefundId": 1234,
        "Status": "Processed",
        "Amount": null,
        "Revisions": [],
        "RejectReason": null,
        "RefundDate": 638123241242235100,
        "RefundDateIso": "2023-12-22T06:42:04.223587Z",
        "Refundable": true,
        "RequestedAmount": null
    },
    "Source": "Card",
    "Splits": [
        {
            "Iban": "GE65BG0000000000000000",
            "PayIn": 0,
            "Amount": 35,
            "Status": "Draft",
            "Description": "Split Funds (ID:99D4DDCC4TEST12BB260418C42A6912A); ",
            "CashOutOrder": []
        }
    ],
    "Sandbox": false,
    "CardMask": "415479xxxxxx4768",
    "Currency": "GEL",
    "Metadata": {
        "Order": {
            "OrderId": null,
            "AdvanceContactId": null,
            "OrderItems": null,
            "BillingAddress": {
                "City": null,
                "Line1": null,
                "Line2": null,
                "State": null,
                "Country": null,
                "LastName": null,
                "FirstName": null,
                "PostalCode": null,
                "PhoneNumber": null
            },
            "ShippingAddress": {
                "City": null,
                "Line1": null,
                "Line2": null,
                "State": null,
                "Country": null,
                "LastName": null,
                "FirstName": null,
                "PostalCode": null,
                "PhoneNumber": null
            },
            "UzRegulatoryOrderDetails": {
                "TaxiTin": null,
                "Latitude": null,
                "Longitude": null,
                "TaxiPinfl": null,
                "TaxiVehicleNumber": null
            }
        },
        "Channel": null,
        "ExtraAttributes": [
            {
                "Key": "API_VERSION",
                "Value": "V1",
                "Description": ""
            }
        ]
    },
    "BlockDate": 638381923066765000,
    "CardBrand": "Visa",
    "PaymentId": "2TEST21AF2DTESTDA14L2E05A",
    "CardHolder": null,
    "Commission": null,
    "CreateDate": 638381922898406900,
    "CaptureDate": null,
    "CardCountry": null,
    "FinalAmount": 51.5,
    "CanBeCaptured": true,
    "PaymentStatus": "Blocked",
    "Preauthorized": true,
    "ExpirationDate": "2706",
    "IdempotencyKey": null,
    "CardOrigination": "Off-Us",
    "RejectionReason": null,
    "CardOwnerEntityType": null
}

Parsing Payment Statuses

You can parse the PaymentStatus field to determine the status of the payment transaction. Here are the possible payment statuses:

Transaction Status	Description
`Draft`	When the transaction is created and waiting for card details for the next action.
`Blocked`	The funds have been successfully blocked on the card. Usually, this means you have used preauthorize: True Transactions with `Blocked` statuses need to be committed within 30 days, otherwise, they will be refunded automatically.
`Captured`	The funds have been captured successfully from the cardholder.
`Refunded`	The transaction has been refunded fully.
`PartiallyRefunded`	The transaction amount has been refunded partially.
`Rejected`	The transaction was rejected, because of different reasons.

Example: Parsing Payment Statuses in Python

import json

# Sample JSON response
response_json = '{"data": {"PaymentStatus": "Draft", ...}, "status": {"message": null, "errors": null, "type": null}}'

response_dict = json.loads(response_json)
payment_status = response_dict['data']['PaymentStatus']

if payment_status == 'Draft':
    print("Transaction is in draft status, awaiting card details.")
elif payment_status == 'Blocked':
    print("Funds have been blocked on the card, ready for capture.")
# ... similar checks for other payment statuses