Create Order Widget

Overview

This create order widget is the simplest way to initialise the customer checkout flow from your checkout site and will take all order information on the frontend javascript to begin the customer checkout flow. If you wish to initiate an order from your backend system then the API Driven Create Order Widget widget may be more suited to your use case.

Overview of Widget Setup and Integration

<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>

<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 - Payload Field

Call the widget with required payload structure. For more details about the fields please view Direct API Orders as this is where the fields are passed to after the widget is called. The two fields on the payload field that are handled different are the dynamicCallbackUrl and paymentStatusFetchEnabled which are outlined below.

Parameters

When using the optty-create-order-widget, note the following about dynamicCallbackUrl:

For In-Context implementation: dynamicCallbackUrl is required
For standard implementation: dynamicCallbackUrl is optional

When provided, dynamicCallbackUrl should be a valid HTTPS URL that can receive requests for webhook notifications about order status changes.

The paymentStatusFetchEnabled 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 3.2 - Callback Functions

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

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-create-order-widget', {
        payload: {
          "locale": "en_US",
          "customerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkZW50aWZpZXIiOiJmM2I1OGEzMzE4ZmI3OTk2NmQ4Yzc3Njc5OTg0MzBhNjFmODNhYzY2ODU0NGFlODMwZTkwNDE4YjkwNzQ4YWYyNWQ2Mjg1YTIxMzIzZDJkNmNkNTcyNGQwM2RkMTk2OWU3NjZlODU4ZGIwZjNjYjM1NjJlNTk1N2FhMGRhZTZjMiIsIm1lcmNoYW50SWQiOiI0NGFkMzIxMS0yYTgzLTRiNWUtYTJlNy03ZmZlNjhlZTkyMWMiLCJpYXQiOjE2NDc4NzAwNjQsImV4cCI6MTY0ODQ3NDg2NH0.oQmfzTDvaEywgtaV5dhSeY_6pZ95og9rswE5LuktEnc",
          "orderReference": {{YOUR_UNIQUE_REFERENCE}},
          "bnplProvider": {{SELECTED_BNPL_PROVIDER}},
          "orderAmount": 50,
          "taxAmount": 0,
          "shippingAmount": 0,
          "discountAmount": 0,
          "orderItems": [
            {
              "name": "Striped Silk Tie",
              "quantity": 1,
              "sku": "793775370033M",
              "unitPrice": 50,
              "totalAmount": 50
            }
          ],
          "purchaseCountry": "AU",
          "purchaseCurrency": "AUD",
          "customer": {
            "firstName": "Ben",
            "lastName": "Tester",
            "email": "[email protected]",
            "phoneNumber": "+6591234567"
          },
          "autoCapture": true,
          "billingAddress": {
            "firstName": "RTS",
            "lastName": "VDP",
            "email": "[email protected]",
            "phoneNumber": "+6591234567",
            "streetAddress": "201 S. Division St.",
            "streetAddress2": "Ann Arbor",
            "city": "PUNE",
            "country": "US",
            "state": "New york",
            "region": "skdsk",
            "postalCode": "48104-2201"
          },
          "shippingMethod": "digital",
          "shippingAddress": {
            "firstName": "Kaufen",
            "lastName": "Darf",
            "email": "[email protected]",
            "phoneNumber": "+6591234567",
            "streetAddress": "Herrengraben 31",
            "streetAddress2": "",
            "city": "Herrengraben",
            "country": "US",
            "state": "New york",
            "region": "Herrengraben",
            "postalCode": "48104-2201"
          },
          "dynamicRedirectUrl": "https://webhook.site/f133ab94-8687-4b94-a570-e008d999f362",
          "dynamicCallbackUrl": "https://webhook.site/f133ab94-8687-4b94-a570-e008d999f362",
          "cancellationTimeout": 8660,
          "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.

PreviousEasy Checkout Widget NextAPI Driven Create Order Widget