API Driven Create Order Widget

Overview

This widget allows the creation of an order to be completed by your backend services and then initiate the customer flow from your checkout page by passing through references to the order. The flow of the checkout experienced by the customer will be the same using either widget.

Step 1 - Widget Setup & Initialisation

Overview of Widget Setup and Integration

1.1 Initiate Widget

<script>
  (function (w, d, s, o, f, js, fjs) {
    w['JS-Widget'] = o;
    w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script', 'mw', 'https://widgets.qa.optty.com/widget-loader.js'));
</script>

1.2 Load configuration

<script>
    // … widget initiation script …
    mw('init', {
        token: {{CUSTOMER_WIDGET_TOKEN}},
        currency: "string",
        initialAmount: number
        mode: “live”
    });
</script>

1.3 Setup Optty Easy Checkout Widget

<script>
    mw('optty-easy-checkout-widget', {
        initialAmount: number,
    })
</script>

Step 2 - Payment Provider Selection

There must be an implementation in your checkout to handle a customer selecting a payment method option. The easiest way to implement this is to use the Easy Checkout Widget, otherwise if you wish to have complete control of the display of the payment method selection the Options end point may be more preferable.

Step 3 - Create an Order

As mentioned above, this widget is used to display an order that has been previously created via API here Direct API Orders.

Step 4 - Setup Optty Handle Order Payment Widget

Step 4.1 - Payload Fields

The payload field takes in the parameters of the response from the order you have created, this helps us speed up the processing time to display the checkout to the customer instead of just passing a reference.

Is also takes in the paymentStatusFetchEnabled field which determines whether to retrieve the payment status after the payment is completed. If set to true, a payment object is included in the onFinalized callback response.

Step 4.2 - Callback Functions

onFinalize: This callback function is called when the consumer finishes the checkout flow with the payment method.

onFinalize Data Response Example

{
	"order": {
		"merchantReference": "WG-1750135641723",
		"provider": "PAYPAL",
		"transactionReference": "849e4b926c",
		"status": "PENDING"
	},
	"payment": {
		"merchantReference": "WG-1750135641723",
		"transactionReference": "849e4b926c",
		"amount": "850",
		"currency": "AUD",
		"status": "SUCCESSFUL",
		"provider": "PAYPAL",
		"preferredDisplayMode": "REDIRECT",
		"incontextDisplayMode": null,
		"paymentStatusFetchEnabled": true,
		"bnplOrderId": "WG-1750135641723",
		"failureReason": null,
		"rejectReason": null,
		"surcharge": "8.89",
		"updatedAt": "2025-06-17T04:47:48.224Z"
	}
}

onError: This callback function is called when their was an error faced creating an order with the selected payment provider (bnplProvider), the best practise for handling this would be to remove that option from the checkout and get the customer to checkout with another provider. We also request any errors faced here to be sent to [email protected] as we will follow up to get the technical issue with the provider directly on your behalf.

onCancel: This callback is only used when the in-context flow is used, and is when the customer cancels the checkout flow through either closing the popup table, or clicking the Optty cancel button on the IFrame, this IS NOT the only flow where a cancel occurs, if the customer cancels with the providers cancel functionality this will be passed as a CANCELED status in the onFinalize callback, but both should be handled the same way.

<script>
    mw('optty-handle-order-payment-widget', {
        payload: {
          "redirectUrl": {{RETURNED AS RESPONSE FROM /orders endpoint}},
          "orderReference": {{RETURNED AS RESPONSE FROM /orders endpoint}},
          "transactionReference": {{RETURNED AS RESPONSE FROM /orders endpoint}},
          "paymentStatusFetchEnabled": true
        },
      onError: function(err) {
         // Handle error 
        console.error({ err });
      },
      onCancel: function(cancel) {
        // Handle cancel
        console.log({ cancel });
      },
      onFinalize: function(data) {
         // Handle completion
        console.log('Payment completed:', data);
      }
    });
</script>

React Code Example

To test this we recommend forking this example and entering your widget token from the UPP found under 'view profile' when hovering your user on the top right. Along with a currency which has a payment method enabled on the UPP.