📡 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.50,
  "Refund": {
    "RefundId": 1234,
    "Status": "Processed",
    "Amount": null,
    "Revisions": [],
    "RejectReason": null,
    "RefundDate": 638123241242235199,
    "RefundDateIso": "2023-12-22T06:42:04.223587Z",
    "Refundable": true,
    "RequestedAmount": null
  },
  "Source": "Card",
  "Splits": [
    {
      "Iban": "GE65BG0000000000000000",
      "PayIn": 0.0,
      "Amount": 35.0,
      "Status": "Draft",
      "Description": "Split Funds (ID:99D4DDCC4TEST12BB260418C42A6912A); ",
      "CashOutOrder": []
    }
  ],
  "Sandbox": false,
  "CardMask": "415479xxxxxx4768",
  "Currency": "GEL",
  "Metadata": {
    "Order": {
      "OrderId": 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": 638381923066765059,
  "CardBrand": "Visa",
  "PaymentId": "2TEST21AF2DTESTDA14L2E05A",
  "CardHolder": null,
  "Commission": null,
  "CreateDate": 638381922898406910,
  "CaptureDate": null,
  "CardCountry": null,
  "FinalAmount": 51.50,
  "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