Payment Status Data Model

Data Model

Overview

The "Payment Status Changed" webhook is triggered whenever there is an update to the status of a payment transaction. This webhook ensures that your system is notified of any changes in the transaction status, allowing for real-time updates and appropriate actions.

Your webhook endpoint will receive a POST request containing an event with a Code of 1 and Name of PAYMENT_STATUS_CHANGED. This event is particularly useful for keeping track of failed, authorized, released, or successful payment transactions, enabling your system to handle displaying the payment attempt result on your page and update your system with the transaction status.

Request Model

The webhook payload consists of multiple nested objects containing essential transaction details.

Event Object

Input Parameter	Type	Description
Event.Code	number	1 - PAYMENT_STATUS_CHANGED
Event.Name	string	PAYMENT_STATUS_CHANGED
Event.CountryIsoCode	string	The country of your account with nstFi.
Event.CreationDate	datetime	The timestamp when the event was created in ISO 8601 format.
Event.Reference	string	Unique reference ID for the webhook event.

Data Object

Invoice Object

Input Parameter	Type	Description
Invoice.Id	string	Unique identifier for the invoice.
Invoice.Status	string	The current status of the invoice (PAID - PENDING).
Invoice.Reference	string	A unique reference number assigned to the invoice.
Invoice.CreationDate	datetime	The date and time when the invoice was created, formatted in ISO 8601.
Invoice.ExpirationDate	datetime	The expiration date of the invoice, formatted in ISO 8601.
Invoice.UserDefinedField	string	Any custom user-defined field associated with the invoice.
Invoice.ExternalIdentifier	string	The value sent in the CustomerIdentifier field in the request.
Invoice.MetaData	Object	Includes the metadata sent in the request up to 5 UDFs.

Transaction Object

Input Parameter	Type	Description
Transaction.Id	string	Unique identifier for the transaction.
Transaction.Status	string	The status of the transaction (SUCCESS - FAILED - AUTHORIZE - CANCELED).
Transaction.PaymentMethod	string	The payment method used (e.g., VISA/MASTER (USD)).
Transaction.PaymentId	string	The unique payment ID associated with the transaction.
Transaction.ReferenceId	string	A unique identifier assigned to the transaction.
Transaction.TrackId	string	The tracking ID for the transaction.
Transaction.AuthorizationId	string	A unique ID associated with the authorization of the payment transaction.
Transaction.TransactionDate	datetime	The date and time when the transaction was processed.
Transaction.ECI	string	The Electronic Commerce Indicator (ECI) code.
Transaction.IP.Address	string	The IP address from which the transaction was initiated.
Transaction.IP.Country	string	The country associated with the IP address.
Transaction.Error.Code	string	Error code returned by the payment gateway.
Transaction.Error.Message	string	Detailed error message.
Transaction.Card.NameOnCard	string	The name of the cardholder entered by the payer.
Transaction.Card.Number	string	The masked credit/debit card number used.
Transaction.Card.Token	string	The token of the card if tokenized
Transaction.Card.PanHash	string	A unique identifier for the PAN.
Transaction.Card.ExpiryMonth	string	Expiry month entered by the customer.
Transaction.Card.ExpiryYear	string	Expiry year entered by the customer.
Transaction.Card.Brand	string	The brand of the payment card.
Transaction.Card.Issuer	string	The issuing bank or financial institution of the card.
Transaction.Card.IssuerCountry	string	The issuer country of the card
Transaction.Card.FundingMethod	string	The funding method of the card (e.g.: debit, credit, prepaid)

Customer Object

Input Parameter	Type	Description
Customer.Name	string	Customer's name.
Customer.Mobile	string	The Customer Mobile provided in the request.
Customer.Email	string	Customer's email address (masked).

Amount Object

Input Parameter	Type	Description
Amount.BaseCurrency	string	The base currency of the transaction.
Amount.ValueInBaseCurrency	string	The amount in the base currency.
Amount.ServiceCharge	string	The service charge applied in base currency.
Amount.ServiceChargeVAT	string	The VAT applied on the service charge.
Amount.ReceivableAmount	string	The amount the vendor receives in base currency.
Amount.DisplayCurrency	string	The currency used for display.
Amount.ValueInDisplayCurrency	string	The amount in display currency.
Amount.PayCurrency	string	The currency used for payment.
Amount.ValueInPayCurrency	string	The transaction value in payment currency.

Suppliers Object (If applicable)

Input Parameter	Type	Description
Suppliers[ ].Code	number	Unique identifier for the supplier.
Suppliers[ ].Name	string	The name of the supplier.
Suppliers[ ].InvoiceShare	string	The share of the supplier in the given invoice.
Suppliers[ ].ProposedShare	string	The ProposedShare for the supplier in the invoice.
Suppliers[ ].DepositShare	string	The amount the supplier receives from this invoice.

Sample Event

The below sample JSON message is sent by nstFi to your endpoint.

{
  "Event": {
    "Code": 1,
    "Name": "PAYMENT_STATUS_CHANGED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2026-01-04T08:15:00.9500000Z",
    "Reference": "WH-626519"
  },
  "Data": {
    "Invoice": {
      "Id": "6409988",
      "Status": "PAID",
      "Reference": "2026000073",
      "CreationDate": "2026-01-04T08:14:49.897Z",
      "ExpirationDate": "2026-01-04T10:08:36Z",
      "UserDefinedField": "",
      "ExternalIdentifier": "asdqwd-f13sdf-fasjkz",
      "MetaData": {
        "UDF1": "dsa",
        "UDF2": "145",
        "UDF3": "8586",
        "UDF4": "12039",
        "UDF5": "748gsvf"
      }
    },
    "Transaction": {
      "Id": "86781",
      "Status": "SUCCESS",
      "PaymentMethod": "VISA/MASTER",
      "PaymentId": "07076409988323998875",
      "ReferenceId": "600408086781",
      "TrackId": "04-01-2026_3239988",
      "AuthorizationId": "086781",
      "TransactionDate": "2026-01-04T08:15:00.8834074Z",
      "ECI": "02",
      "IP": {
        "Address": "41.40.252.158",
        "Country": "Egypt"
      },
      "Error": {
        "Code": "",
        "Message": ""
      },
      "Card": {
        "NameOnCard": "",
        "Number": "512345xxxxxx0008",
        "Token": "TKN-ecbc9523-8f87-4b72-8009-9859d89d6b45",
        "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
        "ExpiryMonth": "12",
        "ExpiryYear": "36",
        "Brand": "Mastercard",
        "Issuer": "Test Bank",
        "IssuerCountry": "KWT",
        "FundingMethod": "credit"
      }
    },
    "Customer": {
      "Name": "Anonymous",
      "Mobile": "+965",
      "Email": ""
    },
    "Amount": {
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "1",
      "ServiceCharge": "0.02",
      "ServiceChargeVAT": "0.003",
      "ReceivableAmount": "0.51",
      "DisplayCurrency": "KWD",
      "ValueInDisplayCurrency": "1",
      "PayCurrency": "KWD",
      "ValueInPayCurrency": "1"
    },
    "Suppliers": [
      {
        "Code": 212,
        "Name": "Jed Auer",
        "InvoiceShare": "1",
        "ProposedShare": "",
        "DepositShare": "0.467"
      }
    ]
  }
}

Webhook Signature

You will use the parameters mentioned below to generate the webhook signature for the PAYMENT_STATUS_CHANGED event. If a parameter has no value, set its value to an empty string.

Invoice.Id=6409988,Invoice.Status=PAID,Transaction.Status=SUCCESS,Transaction.PaymentId=07076409988323998875,Invoice.ExternalIdentifier=asdqwd-f13sdf-fasjkz