Payment widget

Table of Contents

Using EPC Payment widget integrated with S360 backend APIs

This page explains how to process payments in S360 via APIs, without redirecting to the Ticketshop pages. Through the S360 APIs, a payment instance will be created in the E‑Payment Center (EPC) and then, the EPC payment widget can be used to be displayed in any webpage by providing some parameters.

Summary

  1. Initialize payment using createPaymentAndCloseOrder API method
  2. Display the payment widget
  3. On successful payment:
    1. Call API notifyOrder to finalize the order
  4. On payment failure:
    1. Call API notifyOrder to abandon the order.
  5. Use the reopenOrder API to reopen the order and authorize a new payment attempt.

Activation of the payment widget

Activate the widget for the point of sale

  • Go to Organization context > Initialization > Sales Channel > [Choose the sales channel] > Point of sale > [Choose the point of sale] > Characteristics > Payment modes > Choose "Yes" for "Use payment widget if supported":

Info

If this option is not available, either the feature is not activated for the institution (elcadmin), either the sales channel is not of type Internet

Make sure that the version of EPC interface to use on the sales channel is V10 :

If this is not the case, you can update the version by :

  • Click on 'EDIT PARAM'
  • For Alias service, URL Service, Shop service and Alias service URL: update the end of the URL only by replacing V... by V10 : (First image: before change / Second image: after the change)

Before the change to V10 After the change to V10

C) Check EPC shop id

If the sales channel is not already processing payment, make sure that the EPC Shop ID is correctly configured in the Point of Sale Internet Parameters:

Closing and paying an order

Calling createPaymentAndCloseOrder

After creating the order using Secutix APIs, you have to call the API service createPaymentAndCloseOrder (https://secutix.pos.secutix.com/tnseb/apidocs/ExternalOrderFacade_latest.html#createPaymentsAndCloseOrder) and provide those two parameters in "paymentParams.paymentParametersMap" object :

  • “ORDER_IDENTIFIER” : the value should be a unique identifier that will be used when displaying the payment widget (called sessionId during initialization of the widget - see more details below) *this is generated outside of secutix- good example is a UID
  • “RETURN_URL”: the URL to be used by the EPC to redirect the user after the payment has been successfully done

More details here: https://secutix.pos.secutix.com/tnseb/apidocs/ExternalOrderFacade_latest.html#PaymentParameters

In the response, use the transactionID inside the EPC Transaction Data for the next step (to use for payment ID field).

Keep track of the paymentId in case of payment cancellation.

{
    "orderId": "2621264",
    "isConvertedReservation": false,
    "createToken": true,
    "payments": [
        {
            "amount": 24000,
            "paymentMethodId": 16362
        }
        ],
    "paymentParams": {
        "contactNumber": "752565",
        "totalAmount": 24000,
        "paymentParametersMap": {
            "ORDER_IDENTIFIER": "your-unique-session-id-12345",
            "RETURN_URL": "<https://yourdomain.com/payment-success>"
            }
        },
    "orderType": "SALE",
    "maxWaitingTime": 0,
    "purchasersInfo": [
        {
            "contactReference": "752565"
        }
    ]
}

This methid will return a paymentId and an identification. Store them to be able to cancel the payments if needed.

Show the widget

To show the widget, you just need to include JS file and call a JavaScript function.

JS File for preproduction and testing : https://pp-payment.secutix.com/widget/integrate_widget.js

JS File for production : https://payment.secutix.com/widget/integrate_widget.js

Code snippet to use in the page

<div id="paymentWidget"></div>

<!-- Do not change the ID of this script element, 
     it is required to load the payment widget correctly -->

<script type="text/javascript" id="paymentWidgetJs" src="https://pp-payment-qf.secutix.com/widget/integrate_widget.js"></script>

<script>
createPaymentWidget(
  "widget", // use "alias" to show the widget to create an alias
  "paymentWidget", // id of the div
  {
    "paymentId": "1638671948",
    "sessionId": "30ab1465-b39a-4212-a5f1-ea8ce345f685"
  },
  {
    "fullRedirection": true, // should payment widget redirect to parent page after submitting, true by default
    "enableCancelButton": true
  }
);
</script>

At the end of the payment, the widget will do a full redirection of the page to the return URL provided when creating the payment.

Handling payment result directly in the redirect url

Here is the parameter that provides the result of the payment on the redirected URL:

  • for payment failure/refused : txState = CREATION_NOT_AUTHORIZED and state = KO
  • for payment success : txState = CREA_AUTHO and state = OK
  • for payment pending : txState = PENDING and state = OK

Payment success

Call the notifyOrder method with maxWaitingTime = 100

https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalOrderService_latest.html#notifyOrder

{  
    "requestId": null,  
    "orderId": 990735,  
   "maxWaitingTime":100
}

Expected result: success

Payment failure

If you want to reopen the order

Call immediately the notifyOrder method with maxWaitingTime = 3000

https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalOrderService_latest.html#notifyOrder

{  
    "requestId": null,  
    "orderId": 990735,  
   "maxWaitingTime":30000
}

Expected result:


{
    "statusCode": "success",
    "statusDetail": "Workcase failed : 990735_1759750930782, ROLLBACK, WARN, The payment process has been cancelled successfully.<br/>The order has been reopened.<br/>",
    "movementTicketDatas": [],
    "repaymentSafe": true
}

Then it will be possible to call createPaymentAndCloseOrder again.

If you want to abandon the order

Call the notifyOrder method with maxWaitingTime = 3000

https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalOrderService_latest.html#notifyOrder

{  
    "requestId": null,  
    "orderId": 990735,  
   "maxWaitingTime":100
}

Handling the “Cancel” button

To have the cancel button displayed, the following parameters must be used:

  • enableCancelButton: Put true to show inside the widget the cancel button
  • cancelUrl: URL to redirect the user to if he click on Cancel button. You need to handle the call to cancel the transaction in EPC. Example of value : "/checkout/cancelPayment"

When the widget redirects to the cancel url, you must implement the following calls

Update payment

Call to: https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalPaymentService_latest.html#updatePayments

{  
    "requestId": null,  
    "orderId": 990735,  
    "payments": [{  
      "paymentId" : 10229102727225,  
      "paymentIdentifier" : "1521143230",  
      "paymentStatus" : "CANCELLED_BY_USER",  
      "amount": 64000  
    }]  
}

To mark the payment as cancelled by the user

Expected result: success


    {
    "statusCode": "success",
    "paymentDetails": [
        {
            "paymentId": 10229102727225,
            "amount": 64,
            "paymentMethod": {
                "id": 121518554,
                "externalName": {
                    "translations": [
                        {
                            "locale": "en",
                            "value": "Credit Card"
                        }
                    ]
                },
                "paymentType": "CB",
                "subPaymentMethods": []
            },
            "paymentStatus": "ABANDONED",
            "paymentDate": "2025-10-06T12:18:34.845+01:00",
            "payerContact": false,
            "catalogCurrency": {
                "currencyCode": "GBP",
                "symbol": "£",
                "fractionDigit": 2,
                "minAmount": 10
            },
            "installment": false
        }
    ]
}

Then, depending on your choice

To reopen the order and allow another tentative

https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalOrderService_latest.html#notifyOrder

Call the method notify order with parameter maxWaitingTime=30000

(see above the example for payment failure handling)

To simply abandon the order

https://mosa.demo-ws.secutix.com/tnseb/apidocs/ExternalOrderService_latest.html#notifyOrder

Call the method notify order with parameter maxWaitingTime=100

(see above the example for payment failure handling)

Advanced

Advanced options for the widget

You can have access to advanced display options by sending more options in the JSON configuration in the 4th parameter. Here is the list of advanced parameters available for now :

  • fullRedirection : Force the full redirection of the page. Same as the 4th parameter when not using the JSON advanced parameter of createPaymentWidget function.
  • hide_alias_checkbox : Put true if you want to hide the checkbox to store the alias for the customer (can be used when customer is a guest)
  • widgetCss : Add CSS for the widget
    • Example : ".stx-Payment-form label {color: blue;}"

If the user remains on the widget

Or if the abandon of the order is not managed, the order remains opened around 25 minutes.