Notification Handling
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. You should always handle the PENDING status on initial response, redirect and webhooks and handle a state where the status is not final until a proceeding webhook.
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
Log in to the Universal Payment Platform
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.
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'
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_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 DECLINED PENDING
This event will be sent to the URL which was configured in Universal Payment Platform
ORDER_VOID_ASYNC_CALLBACK
This event will be sent to you whenever an authorized order is voided.
voidStatus: 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.
Below is a table describing the key fields included in the notification object:
event
string
Type of notification, e.g., ORDER_ASYNC_CALLBACK
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.
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
voidReference
string
Reference for Void order
voidStatus
string
In case of void order you will recive this field
e.g. SUCCESSFUL or ERROR
reference
string
Unique identifier for the 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
refundDescription
string
Description for refund order
This JSON structure should be parsed and validated to ensure accurate order and transaction processing.
Last updated