Recurring Data Model

Data Model

Overview

The "Recurring Updates" webhook is triggered whenever there is an update to a recurring payment. This webhook ensures that your system is notified of recurring payment status changes, allowing for real-time updates and appropriate actions.

Your webhook endpoint will receive a POST request containing an event with a Code of 5 and Name of RECURRING_UPDATES. This event is particularly useful for tracking active, canceled, or updated recurring payments and their associated transactions.

Request Model

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

Event Object

Input Parameter	Type	Description
Event.Code	number	5 - RECURRING_UPDATES
Event.Name	string	RECURRING_UPDATES
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

The Data Object contains multiple nested objects as below.

Recurring Object

Input Parameter	Type	Description
Recurring.Id	string	Unique identifier for the recurring payment.
Recurring.NextPayDate	datetime	The scheduled date and time for the next recurring payment, formatted in ISO 8601 and always in UTC.
Recurring.Status	string	ACTIVE - The recurring payment is being processed normally, but its iterations have not been completed yet.\ UNCOMPLETED - nstFi attempted to withdraw the recurring value, but the payment failed, and all retry attempts were unsuccessful.\ COMPLETED - The recurring payment has been executed successfully with all iterations completed; it will not be executed again.
Recurring.InitialInvoiceId	string	The invoice ID associated with the creation of the recurring payment.

Payment Object

The Payment Object contains details about the latest processed recurring payment.

Invoice Object

Input Parameter	Type	Description
Invoice.Id	string	Unique identifier for the invoice.
Invoice.Status	string	The current status of the invoice (e.g., PAID).
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.

Transaction Object

Input Parameter	Type	Description
Transaction.Id	string	Unique identifier for the transaction.
Transaction.Status	string	The status of the transaction (e.g., SUCCESS).
Transaction.PaymentMethod	string	The payment method used (e.g., VISA/MASTER).
Transaction.PaymentId	string	The unique payment ID associated with the transaction.
Transaction.ReferenceId	string	A unique identifier assigned to the transaction for tracking purposes.
Transaction.TrackId	string	The tracking ID for the payment transaction.
Transaction.AuthorizationId	string	A unique ID associated with the authorization of the payment.
Transaction.TransactionDate	datetime	The date and time when the transaction was processed.
Transaction.ECI	string	The Electronic Commerce Indicator (ECI) code, representing security level.
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, if applicable.
Transaction.Error.Message	string	Detailed error message, if applicable.
Transaction.Card.Number	string	The masked credit/debit card number used for the transaction.
Transaction.Card.Brand	string	The brand of the payment card, such as Visa or MasterCard.
Transaction.Card.Issuer	string	The issuing bank or financial institution of the card, if available.

Amount Object

Input Parameter	Type	Description
Amount.BaseCurrency	string	The base currency of your nstFi account (e.g., KWD).
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 to 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 (e.g., USD).
Amount.ValueInPayCurrency	string	The transaction value in payment currency.

Sample Event

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

{
  "Event": {
    "Code": 5,
    "Name": "RECURRING_UPDATES",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-02-09T01:16:11.9770000",
    "Reference": "WH-19916"
  },
  "Data": {
    "Recurring": {
      "Id": "RECUR1218312623",
      "NextPayDate": "2025-02-09T21:00:00Z",
      "Status": "ACTIVE",
      "InitialInvoiceId": "5047674"
    },
    "Payment": {
      "Invoice": {
        "Id": "5105602",
        "Status": "PAID",
        "Reference": "2025015455",
        "CreationDate": "2025-02-09T01:16:10.6259466Z",
        "ExpirationDate": "2025-02-10T01:16:10.6259466Z",
        "UserDefinedField": ""
      },
      "Transaction": {
        "Id": "121797",
        "Status": "SUCCESS",
        "PaymentMethod": "VISA/MASTER",
        "PaymentId": "07075105602247796773",
        "ReferenceId": "504001121797",
        "TrackId": "09-02-2025_2477967",
        "AuthorizationId": "262890",
        "TransactionDate": "2025-02-09T01:16:11.8837517Z"
      }
    }
  }
}

Webhook Signature

You will use the parameters mentioned below to generate the webhook signature for the RECURRING_UPDATES event.

Recurring.Id=RECUR1037225,Recurring.Status=UNCOMPLETED,Recurring.InitialInvoiceId=322242

This webhook allows real-time tracking of recurring payments, ensuring accurate financial management and automated processing in your system.