🔔Notifications

Receive notifications for changes in Order status.

When integrating Optty, you will want your applications to receive events on Orders as their status is updated, so that you can update your backend systems accordingly.

Receiving webhook events helps you respond to asynchronous events, such as when a payment/refund/capture reaches a final state or changes state.

How to enable Notifications

Using the steps below, you can enable notifications on your account

1

Log in to the Universal Payment Platform

Universal Payment Platform

2

Go to the admin settings

Admin Settings

3

Click on Webhook/Callback Settings

Enter the URL where you want to receive notifications.

The "Raw Payment Method Response", when enabled, will forward both the standardised notification from Optty and will include a nested field with the notification we received from the provider that we standardised. This feature it only recommended in some rare edge cases when you wish to get payment method specific information.

4

Click on Save Changes

You have successfully configured your webhook notifications. For every status change or update, you will receive a notification on the URL you have set in the Universal Payment Platform.

You can also set a notification URL for each order when creating an order by passing in the "dynamicCallbackURL" field in the request body, it will only be sent notifications for ORDER_ASYNC_CALLBACK events

"dynamicCallbackUrl": "https://example.com/dynamicCallbackUrl" 

How it works?

Optty Payment Platform allow you to receive updates on specific events as part of the Optty Payment process.

It will also include the token on a final status update, such as SUCCESSFUL or DECLINED , if you have set "getToken" to true. This token can be used for merchant-initiated payments using the field 'token' Token Create Order - Merchant Initiated

Endpoints must be configured in the merchant dashboard, separately for Sandbox and Production environments. If a notification is not received successfully, we will retry to send the event.

Type of Events

ORDER_ASYNC_CALLBACK

This event will sent to you whenever a pending order get into final state (asynchronously), it will be having the order details and updated status of Order.

Status SUCCESSFUL DECLINED CANCELED PENDING ERROR

If dynamicCallbackUrl is passed while creating order this event notification will be sent to dynamicCallbackUrl else the on the url which was configured from Universal Payment Platform

ORDER_STATUS_UPDATE

This event will sent to you whenever a order, refund or capture is completed using continues polling of orders

Status: SUCCESSFUL DECLINED CANCELED PENDING ERROR

This event will be sent to the URL which was configured in Universal Payment Platform

ORDER_CAPTURE_ASYNC_CALLBACK

This event will be sent to you whenever a order which required manual capture and that has been done

Status: SUCCESSFUL ERROR

This event will be sent to the URL which was configured in Universal Payment Platform

REFUND_CALLBACK

This event will be sent to you whenever a refund order status is update asynchronously

Status: SUCCESSFUL ERROR

This event will be sent to the URL which was configured in Universal Payment Platform

Notification Object

Below is the notification example body for each type of notification.

ORDER_ASYNC_CALLBACK

{
  "event": "ORDER_ASYNC_CALLBACK",
  "data": {
    "transactionId": "3d59905e-1e26-4647-a67b-6dc900bc5730",
    "reference": "Test-52",
    "status": "SUCCESSFUL",
    "hash": "8c3bc3a7628eccd78ee3b37a389e0fb650fa64ebf9f5f3d6733eec4d57ce5e2dad22f225bc716b0a63433e27826ccbf211541cf6f9356a7e6d4713e4de5efbd5",
    "currency": "AUD",
    "amount": 146.24,
    "transactionReference": "c38f5823fd",
    "provider": "FAT_ZEBRA_AU",
    "initiator": "regular",
    "metadata": null,
    "token": "nx5so6w6gprawk7ur",
    "rawBNPLResponse": null
  }
}

ORDER_STATUS_UPDATE

{
  "event": "ORDER_STATUS_UPDATE",
  "data": {
    "status": "CANCELED",
    "orderId": "Test-582",
    "orderToken": "Test-582",
    "redirectUrl": "https://paynow.pmnts-sandbox.io/tokenize_only=false",
    "bnplProvider": "FAT_ZEBRA_AU",
    "orderReference": "Test-582",
    "orderAmount": 146.24,
    "orderPaymentOption": "Credit/Debit",
    "orderDate": "2025-05-30T05:45:25.861Z",
    "paymentStatus": "pending",
    "transactionReference": "b9233437a9",
    "preferredDisplayMode": "REDIRECT",
    "incontextDisplayMode": null,
    "currency": "AUD",
    "hash": "25e2a7eeccf9542d51d20a9474e6eb73e52a49c37",
    "rawBNPLResponse": null,
    "cancelledBy": "SYSTEM",
    "reference": "Test-582"
  }
}

ORDER_STATUS_UPDATE

This same event ORDER_STATUS_UPDATE will send you notification for Refund status as well

{
  "event": "ORDER_STATUS_UPDATE",
  "data": {
    "status": "SUCCESSFUL",
    "bnplProvider": "STRIPE_CARDS",
    "refundReference": "355-dafadfsd-43qwaf",
    "refundAmount": {
      "amount": 66,
      "currency": "EUR"
    },
    "hash": "0326b621ea1fe602cdac20535aca8104ce07bb3f893393674039ac3da2e9b3b",
    "rawBNPLResponse": null
  }
}

REFUND_CALLBACK

{
  "event": "REFUND_CALLBACK",
  "data": {
    "orderReference": "54534_F-533",
    "status": "SUCCESSFUL",
    "hash": "9b300cd24c3a96cd436c0ca847852dd2d4a1136cf928a400ade4552b40b960838c04b",
    "refundReference": "Test-342"
  }
}

ORDER_CAPTURE_ASYNC_CALLBACK

{
  "event": "ORDER_CAPTURE_ASYNC_CALLBACK",
  "data": {
    "orderReference": "FZ-LC-UT-333-Test",
    "captureReference": "test-order-12",
    "status": "SUCCESSFUL",
    "token": "nx5so6w6gpytk7ur",
    "currency": "AUD",
    "amount": "12",
    "hash":"5d1e82dd0a0e9cba32ede281a223829ca7f5983fd0",
    "rejectReason": null
  }
}

Description

Below is a table describing the key fields included in the notification object:

Field	Type	Description
event	string	Type of notification, e.g., ORDER_ASYNC_CALLBACKORDER_STATUS_UPDATE
status	string	Current status of the order, such as SUCCESSFUL DECLINED
transactionId	string	Unique identifier for the transaction.
orderId	string	Provider Order Id
orderToken/reference	string	Order Reference for merchants at Optty's end
hash	string	Secure hash key for verification purposes.
currency	string	Currency code, e.g., AUD.
amount	number	Transaction amount.
transactionReference	string	Reference number for tracking the transaction at Optty
paymentStatus	string	Status of Order when the order was placed
provider	string	Service provider handling the transaction, e.g., FAT_ZEBRA_AU
token	string/null	Secure card token for repat payments
redirectUrl	string	Payment Page Url
orderReference	string	Unique identifier for the order.
orderDate	string	Timestamp of when the order was placed.
rawBnplResponse	object/null	Response from Provider, can turned on/Off from merchant dashboard
metaData	object/null	The meta data which was added during order creation
cancelledBy	string	You will receive this field only in CANCELEDstatus "SYSTEM": The order timeout has met so system so has canceled this order "USER": User the canceled the order
preferredDisplayMode	string	The display mode of payment page. IN_CONTEXT or REDIRECT
incontextDisplayMode	string/null	The mode in which IN_CONTEXT has been displayed IFRAME or POPUP
captureStatus	string	In case of capture order you will recive this field e.g. "AUTHORIZED" or "CAPTURED"
captureReference	string	Reference for Capture order
rejectReason	string/null	InCase of payment failure or declined it will give the reason of failure, can be null
refundReference	string	Refund Reference for refund Order

This JSON structure should be parsed and validated to ensure accurate order and transaction processing.