# 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

{% stepper %}
{% step %}
[Log in to the Universal Payment Platform](https://upp.qa.optty.com/)

<figure><img src="https://3947039319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCUCEi1845pQGMcbjae6%2Fuploads%2FcpC6cZpO60hDy8opGQ9D%2Fimage.png?alt=media&#x26;token=7423721a-e54d-4dd0-9524-d0dd6cec2f57" alt=""><figcaption><p>Universal Payment Platform</p></figcaption></figure>
{% endstep %}

{% step %}
[Go to the admin settings](https://upp.optty.com/admin-setting)

<figure><img src="https://3947039319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCUCEi1845pQGMcbjae6%2Fuploads%2F3erAbaiIMN6TciKXvHQG%2Fimage.png?alt=media&#x26;token=407ccfe7-4140-48d1-9b1c-65864772b03e" alt=""><figcaption><p>Admin Settings</p></figcaption></figure>
{% endstep %}

{% step %}
Click on Webhook/Callback Settings&#x20;

Enter the URL where you want to receive notifications.&#x20;

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.

<figure><img src="https://3947039319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCUCEi1845pQGMcbjae6%2Fuploads%2Fpzty552dOkLd6yiINUyj%2Fimage.png?alt=media&#x26;token=cb70ad92-cf6a-4a2e-a1ad-69a75a94dd56" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
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.&#x20;
{% endstep %}
{% endstepper %}

{% hint style="info" %}
You can also set a notification URL for each order when [creating an order](https://docs.optty.com/universal-integration-features/broken-reference)  by passing in the "dynamicCallbackURL" field in the request body, it will only be sent notifications for ORDER\_ASYNC\_CALLBACK events

<pre class="language-json"><code class="lang-json"><strong>"dynamicCallbackUrl": "https://example.com/dynamicCallbackUrl" 
</strong></code></pre>

{% endhint %}

## 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'  [Broken link](https://docs.optty.com/universal-integration-features/broken-reference "mention")

Endpoints must be configured in the [merchant dashboard](https://upp.qa.optty.com/admin-setting), separately for Sandbox and Production environments. If a notification is not received successfully, we will retry to send the event.&#x20;

### Type of Events

<details>

<summary>ORDER_ASYNC_CALLBACK</summary>

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`&#x20;

{% hint style="info" %}
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
{% endhint %}

</details>

<details>

<summary>ORDER_CAPTURE_ASYNC_CALLBACK</summary>

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

Status: `SUCCESSFUL` `ERROR`&#x20;

{% hint style="info" %}
&#x20;This event will be sent to the URL which was configured in Universal Payment Platform
{% endhint %}

</details>

<details>

<summary>REFUND_CALLBACK</summary>

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

Status: `SUCCESSFUL` `ERROR` `DECLINED` `PENDING`

{% hint style="info" %}
&#x20;This event will be sent to the URL which was configured in Universal Payment Platform
{% endhint %}

</details>

<details>

<summary>ORDER_VOID_ASYNC_CALLBACK</summary>

This event will be sent to you whenever an authorized order is voided.

voidStatus: `SUCCESSFUL` `ERROR`&#x20;

{% hint style="info" %}
&#x20;This event will be sent to the URL which was configured in Universal Payment Platform
{% endhint %}

</details>

### Notification Object

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

{% tabs %}
{% tab title="ORDER\_ASYNC\_CALLBACK" %}

<pre class="language-json"><code class="lang-json">{
  "event": "ORDER_ASYNC_CALLBACK",
  "data": {
    "transactionId": "3d59905e-1e26-4647-a67b-6dc900bc5730",
    "reference": "Test-52",
<strong>    "status": "SUCCESSFUL",
</strong>    "hash": "8c3bc3a7628eccd78ee3b37a389e0fb650fa64ebf9f5f3d6733eec4d57ce5e2dad22f225bc716b0a63433e27826ccbf211541cf6f9356a7e6d4713e4de5efbd5",
    "currency": "AUD",
    "amount": 146.24,
    "transactionReference": "c38f5823fd",
    "provider": "FAT_ZEBRA_AU",
    "initiator": "regular",
    "metadata": null,
    "token": "nx5so6w6gprawk7ur",
    "rawBNPLResponse": null
  }
}
</code></pre>

{% endtab %}

{% tab title="REFUND\_CALLBACK" %}

```json
{
  "event": "REFUND_CALLBACK",
  "data": {
    "orderReference": "54534_F-533",
    "status": "SUCCESSFUL",
    "hash": "9b300cd24c3a96cd436c0ca847852dd2d4a1136cf928a400ade4552b40b960838c04b",
    "currency": "AUD",
    "amount": 60,
    "refundReference": "Test-342",
    "refundDescription": "60 Refunded"
  }
}
```

{% endtab %}

{% tab title="ORDER\_CAPTURE\_ASYNC\_CALLBACK" %}

```json
{
  "event": "ORDER_CAPTURE_ASYNC_CALLBACK",
  "data": {
    "reference": "FZ-LC-UT-333-Test",
    "orderReference": "FZ-LC-UT-333-Test",
    "captureReference": "test-order-12",
    "status": "SUCCESSFUL",
    "token": "nx5so6w6gpytk7ur",
    "currency": "AUD",
    "amount": "12",
    "transactionId": "b497023b-4f6d-4c42-be56-e8795177e340",
    "transactionReference": "5246c2b954",
    "provider": "NUVEI_CARDS_AU",
    "hash":"5d1e82dd0a0e9cba32ede281a223829ca7f5983fd0",
    "captureStatus": "CAPTURED",
    "rejectReason": null
  }
}
```

{% endtab %}

{% tab title="ORDER\_VOID\_ASYNC\_CALLBACK" %}

```json
{
  "event": "ORDER_VOID_ASYNC_CALLBACK",
  "data": {
    "reference": "CARDS_AU_F-40",
    "voidReference": "9724",
    "errorMessage": null,
    "status": "CANCELED",
    "transactionId": "c723354f-cee4-4671-9afc-ab76379dd9a8",
    "transactionReference": "cf099bc431",
    "token": null,
    "currency": "AUD",
    "amount": 60,
    "hash": "4667be1b3925ce3690f4f50901951bbc762962476e26ed600bcd62c6440c5ccd267bc311a28efd69d35b0a290d3065717b75539e116efc63c0fc095e3d111779",
    "provider": "NUVEI_CARDS_AU",
    "voidStatus": "SUCCESSFUL",
    "rejectReason": "Transaction Cancelled"
  }
}
```

{% endtab %}
{% endtabs %}

&#x20;Below is a table describing the key fields included in the notification object:

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

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