This document outlines the end-to-end process for integrating third-party payment providers into the Equinox platform, detailing webhook usage, merchant configuration, supported payment methods, and testing protocols for seamless ecommerce transactions.

Infosys Equinox Payments Service

Infosys Equinox Payment microservice processes and stores all transactions for an Infosys Equinox storefront. It allows merchants to manage and customize payment providers installed via Infosys Equinox App Marketplace.

Payment Extensions

Infosys Equinox provides payment extensions that enable app developers to integrate third-party payment providers into ecommerce storefronts.

Key capabilities include:

  • Providing merchants with additional payment methods
  • Automating synchronization with order creation across the entire payment lifecycle
  • Supporting various payment types, including cards, subscriptions, wallets, Buy Now Pay Later, bank debits, delayed bank transfers, and bank redirects
  • Enabling separate authorization and capture for transactions
  • Offering security checks such as 3D Secure

Payment App Overview

A payment app in the Infosys Equinox App Marketplace acts as a connector that enables payments with third-party payment providers and seamlessly integrates them into the platform’s checkout flow. The platform invokes the payment app’s endpoints during various stages of the user’s checkout journey. The app interacts with the third-party payment provider as needed and returns responses to the platform to continue the checkout process.

Payment Lifecycle

A payment app in the Infosys Equinox Commerce platform should cover the entire business logic of the payment lifecycle, including the following stages:

  1. Merchant Account Configuration and Validation
  2. Initiate Payment
  3. Complete a Payment Successfully (Authorization)
  4. Cancel the Order Fully or Partially (Cancel Authorization)
  5. Capture the Payment Fully or Partially
  6. Refund Order Items

This flow illustrates the complete payment lifecycle that a payment app in the Infosys Equinox Commerce platform must implement, covering all essential business logic stages.

<inf-eqx-payment-lifecycle.png>

1. Merchant Account Configuration and Validation

When a merchant installs a payment app, they provide their account credentials and other required information on the app configuration page. The Infosys Equinox platform triggers the validate webhook extension to notify the app of this event.

Extension/Webhook Used:

  • appmarketplaceservices/validator/merchantdetails: Validates merchant account credentials and configuration fields during app setup.

App Function Responsibilities:

  • Process the validation request payload sent by the platform.
  • Communicate with the third-party payment provider to verify the merchant’s credentials and configuration data.
  • Send a success or failure response to the platform indicating whether the account and configuration fields are valid.
  • Use the validated credentials to authenticate subsequent API requests to the payment provider.

Configuration Details:

  • The specific configuration elements required vary by app and are defined by the developer in the app creation JSON file.
  • Refer to the provided JSON template for sample structure and fields.

2. Initiate Payment

A customer selects a payment method from the available options on the storefront checkout page. The Infosys Equinox platform triggers the /createToken webhook extension to request the payment app to generate a payment token. The app should call the third-party payment provider’s API to create a payment intent or token. This token is then used by the storefront to load the payment provider’s frontend SDK and proceed with the payment.

Extension/Webhook Used:

  • paymentservice/payment/createToken: Generates a token based on payment details from the storefront.

App Function Responsibilities:

  • Process the event payload received from the Infosys Equinox createToken webhook.
  • Call the third-party payment provider API to create a payment token.
  • Securely store the transaction ID and token received from the provider.
  • Return the token to the platform.
  • Provide the customer session URL if needed (paymentservice/payment/customersession).
  • Ensure the token supports loading the SDK and initiating a payment intent or transaction.
  • Some payment providers may also require specific customer information before initiating a session
  • Handle any errors or token generation failures based on the API response.

Storefront Behavior:

  • The platform uses the returned token to load the frontend payment SDK and continue the payment flow.

3. Complete a Payment Successfully (Authorization)

The customer completes the payment using the frontend interface provided by the third-party payment provider. A successful payment at this stage results in an authorization (with the provider) for the transaction amount, and the order is placed. The customer’s funds are held until the merchant fulfills the order and captures the payment.

Extension/Webhook Used:

  • paymentservice/payment/authorize: Authorizes the payment amount.

App Function Responsibilities:

  • Process the authorization event payload received from the Infosys Equinox authorize webhook.
  • When the user clicks the “Submit Order” button, invoke the third-party authorization API.
  • Upon receiving a successful response, Infosys Equinox creates a transaction with the status AUTH SUCCESS.
  • The order is successfully placed in the Order service.
  • Handle authorization failures, timeouts, and cancellations by notifying the user and prompting them to retry.

Edge Cases:

  • Authorization expiration varies depending on the payment method and provider. Refer to the provider’s documentation for more details.
  • Authorization may fail if the customer abandons the payment process or if the session times out.

4. Cancel the Order Fully or Partially (Cancel Authorization)

If an order is placed but not yet fulfilled, it can be canceled by either the shopper or the merchant. In such cases, the authorization should be canceled to release the hold on the customer’s funds.

Extension/Webhook Used:

  • paymentservice/payment/cancel: Cancels authorized payment amounts.

App Function Responsibilities:

  • Process the cancellation event payload received from the Infosys Equinox cancel webhook.
  • Call the payment provider to cancel the authorization.
  • Handle partial cancellations by adjusting the authorization amount to match the canceled items.
  • Cancel or delete the payment intent stored by the provider for the transaction.

5. Capture the Payment Fully or Partially

The authorization is captured once the merchant fulfills the order (or part of it).

Extension/Webhook Used:

  • paymentservice/payment/charge: Charges the authorized amount.

App Function Responsibilities:

  • When the merchant fulfills the order, it is marked as “Shipped,” triggering the capture webhook.
  • Process the capture event payload from the Infosys Equinox charge webhook.
  • Call the third-party capture API to initiate the capture request.
  • On a successful response, update the transaction status in Infosys Equinox to Capture Success.
  • Handle partial captures as needed.

6. Refund Order Items

Shoppers may request refunds for specific items. Upon merchant approval, the corresponding charged amount should be refunded to the shopper.

Extension/Webhook Used:

  • paymentservice/payment/refund: Refunds charged amounts.

App Function Responsibilities:

  • Process the refund event payload received from the Infosys Equinox refund webhook.
  • Initiate the refund request with the payment provider.

Payment Methods

Payment providers often support multiple payment methods such as cards, wallets, and bank debits. These methods must be declared in your app creation JSON to ensure they are available for configuration and use.

How to Define Payment Methods in App Creation JSON:

  • Use the property “paymentOptions” to list all supported methods as comma-separated values.
    • Example: “paymentOptions“: “STRIPE,BANK_REDIRECT,BANK_DEBIT“
  • Each method listed should correspond to a valid integration supported by the payment provider.

Configuration and Usage:

  • In the Infosys Equinox Payment Admin console, store admins can enable or disable specific payment methods for each store or region.
  • When a customer selects a payment method at checkout:
    • The app loads the corresponding payment provider SDK element using the payment method ID.
    • This ID is passed to the third-party API to create a payment instance specific to the selected method.

Testing

Ensure that your payment app meets the following functional requirements:

  1. Verify that users can install the payment app from the Infosys Equinox App Marketplace.
  2. Test app activation with both valid and invalid configurations, ensuring appropriate error messages are displayed.
  3. Confirm that the activated app appears in the Create Payment Option list within the Payment Admin console, displaying the correct image and supported payment methods.
  4. Verify that merchants can create payment options for all payment methods supported by the app.
  5. Ensure that each created payment option includes the correct payment provider (the provider should match the app name) and locale (which should match the store locale or a locale supported by the payment method).
  6. Confirm that the app’s payment SDK loads correctly in the Customer Admin (Enterprise), CSR component in the Ultra Admin console,  React, and/or Ultra Storefront environments using the created payment options, and that a valid session ID is generated.
  7. Verify that users can successfully make payments using valid card or other payment details.
  8. Ensure that users cannot make payments or place orders using cards intended to recreate failure scenarios
  9. Confirm that customers can successfully cancel payments.
  10. Verify that merchants can successfully cancel, and refund payments.
  11. Validate that:
    • Payments are cancelled when an order is canceled from Order Admin.
    • Payments are captured when the order is marked as shipped in Order Admin.
    • Payments are refunded when a refund is approved.

Revision History
2025-07-10 | JP – Added the content.