Overview

The Infosys Equinox Commerce platform allows the apps to register for extensions to extend the behavior of specific Infosys Equinox Commerce APIs with the business logic. In other words, apps can extend the behavior of the APIs using these extensions or synchronous webhooks.

In this synchronous approach, the process is intercepted, and the outcome of the process is determined by the apps or applications based on some business logic. The transaction or process that is intercepted would be a failure unless the extension receives a valid response payload from the application or app.

The extension is called while processing the create, patch, update, or delete request of an API call, but the result persists based on the response received from the application or app.

Configure an Extension

Apps must expose REST API endpoints to support the request and response structure for each extension point the app has subscribed to. Develop and host an app (HTTPS endpoint function) that accepts webhook extensions with a POST method.

Sample Endpoint:

The following is the sample endpoint:

POST https://<your-domain>/webhookname

When apps receive the payload for the registered extension, the app must transform and construct the payload to call the third-party API, receive the response from the third party, and convert the response to the Infosys Equinox Commerce platform.

Sample Extension Configuration in the App Template:

In the app template, the webhook has to be configured. The following is a sample configuration:

{
                    "url": "https://eq-pdn-apps.equinox.shop/avalara/tax/v1/calculatetax",
                    "webhookType": "SYNC",
                    "priority": "Normal",
                    "events": [
                        "taxservice/tax/calculatetax"
                    ]
                }

The following table describes the parameters of the sample configuration:

Attribute	Description
url	App hosted endpoint
webhookType	SYNC
priority	High or Normal
events	The name of the extension Note: Refer to the Extensions for Standard Apps section for the list of extensions supported for different standard apps.

Extensions for Standard Apps

Payment App Extensions

The following is the list of extensions available for the payment app integrations:

• Get Customer Session
• Create Token
• Authorize Payment
• Capture Payment
• Cancel Payment
• Refund Payment
• Get Token
• Update Token

Postman Collection

Refer to the following Postman collection for the integration of payment apps:

Get Customer Session

The following table lists the details of the get customer session extension:

Endpoint	Extension	Description
https://<your-domain>/customer	paymentservice/payment/getcustomersession	This extension can be used to get the customer session URL from the payment provider to load the payment SDK in the front end. When a user selects the payment option in the storefront, a call is made to the app to get the session URL from the third-party payment provider to load the SDK.

The following diagram shows the flow of the get customer session extension:

Create Token

The following table lists the details of the create token extension:

Endpoint	Extension	Description
https://<your-domain>/token/create	paymentservice/payment/createToken	This extension can be used to create the token based on the provided payment details. When a user provides the payment/card details and submits the payment, a call is made to the app to get a token from the payment provider.

The following diagram shows the flow of the create token extension:

Authorize Payment

The following table lists the details of the authorize payment extension:

Endpoint	Extension	Description
https://<your-domain>/auth	paymentservice/payment/authorize	To authorize the payment transaction of an order by a payment provider. When the order is created in the Order microservices, a transaction with transaction type = AUTH is created in the Payment service. The app will get the details of this transaction, call the third-party payment provider to authorize the transaction, and send the confirmation code as a response to the Infosys Equinox Commerce platform.

The following diagram shows the flow of the authorize payment extension:

Capture Payment

The following table lists the details of the capture payment extension:

Endpoint	Extension	Description
https://<your-domain>/capture	paymentservice/payment/capture	To capture or charge/commit the payment transaction of an order by a payment provider. When the order is updated to shipped status in the Order microservices, a transaction with transaction type = CHARGE is created in the Payment service. The app will get the details of this transaction, call the third-party payment provider to commit/charge the transaction and send the confirmation code as a response to the Infosys Equinox Commerce platform.

The following diagram shows the flow of the capture payment extension:

Cancel Payment

The following table lists the details of the cancel payment extension:

Endpoint	Extension	Description
https://<your-domain>/auth/cancel	paymentservice/payment/cancel	To cancel the payment transaction of an order by a payment provider. When the order is updated to the “cancelled” status in the Order microservices, a transaction with transaction type = CANCELAUTH is created in the Payment service. The app will get the details of this transaction, call the third-party payment provider to cancel the transaction, and send the confirmation code as a response to the Infosys Equinox Commerce platform.

The following diagram shows the flow of the cancel payment extension:

Refund Payment

The following table lists the details of the refund payment extension:

Endpoint	Extension	Description
https://<your-domain>/refund	paymentservice/payment/refund	To refund the payment transaction of an order by a payment provider. When the order is submitted for return and it is updated to return approved status in the Order microservices, a transaction with transaction type = REFUND is created in the Payment service. The app will get the details of this transaction, call the third-party payment provider to refund the transaction, and send the confirmation code as a response to the Infosys Equinox Commerce platform.

The following diagram shows the flow of the refund payment extension:

Get Token

The following table lists the details of the get token extension:

Endpoint	Extension	Description
https://<your-domain>/token/get	paymentservice/payment/getToken	To get the tokenized payment details for the saved payment from the Payment service provider. The app will get the details of the token saved for a payment in the Payment service. The app will call the third party to fetch the payment details of that saved token and will send the payment details (masked card details) as a response to the Infosys Equinox Commerce platform.

The following diagram shows the flow of the get token extension:

Update Token

The following table lists the details of the update token extension:

Endpoint	Extension	Description
https://<your-domain>/token/update	paymentservice/payment/updateToken	For the payment information saved for a user, when the user updates the shipping/billing address information, the app will get the details of the saved token and updated address details. The app will call the third-party payment provider to update the details and send an updated token in response to the Infosys Equinox Commerce platform.

 

The following diagram shows the flow of the update token extension:

Shipping App Extensions

The following is the list of extensions available for the shipping app integrations:

• Get Shipping Rate

Postman Collection

Refer to the following Postman collection for the integration of payment apps:
USPS_Postman_collection.json

Shipping Rate

The following table lists the details of the get shipping rate extension:

Endpoint	Extension	Description
https://<your-domain>/calculaterate	shippingservice/shipping/getshippingrate	To get the shipping rate from a third-party shipping provider. When a user updates or adds a shipping address during the checkout journey, the app will get the shipping address and cart item details. The app will call the third-party shipping provider to get the shipping rates for various shipping methods supported by the shipping provider and send them as a response to the Infosys Equinox Commerce platform.

Sample Payload Request:

• shippingrate_request.json

Sample Payload Response:

• shippingrate_response_200.json

The following diagram shows the flow of the get shipping rate extension:

Tax App Extensions

The following is the list of extensions available for the tax app integrations:

• Calculate Tax

Postman Collection

Refer to the following Postman collection for the integration of payment apps:
avalara_postman_collection.json

Calculate Tax

The following table lists the details of the calculate tax extension:

Endpoint	Extension	Description
https://<your-domain>/calculatetax	taxservice/tax/calculatetax	To get the sales tax quote for an order value. When a user updates or adds a shipping address during the checkout journey, the app will get the shipping address and cart item details. The app will call the third-party tax provider to get the sales tax quote for the cart/order value and send it as a response to the Infosys Equinox Commerce platform.

Sample Payload Request:

• calculatetax_request.json

Sample Payload Response:

• calculatetax_response.json

The following diagram shows the flow of the calculate tax extension:

Address App Extensions

The following is the list of extensions available for the address app integrations:

• Validate address

Postman Collection

Refer to the following Postman collection for the integration of payment apps:

CYBERSOURCE_ADDRESS_postman_collection.json

Validate Address

The following table lists the details of the validate address extension:

Endpoint	Extension	Description
https://<your-domain>/addressVerification	addressservices/validator/physicaladdress addressservices/validator/digitaladdress addressservices/validator/phonedetails	When a user adds or updates the shipping address during the checkout journey, the details are sent to the app. The app calls the third-party provider to validate the address, sends the validation status, and recommends the address as a response to the Infosys Equinox Commerce platform. When a user adds or updates the shipping address on the profile page, the details are sent to the app. The app calls the third-party provider to validate the address, sends the validation status, and recommends the address as a response to the Infosys Equinox Commerce platform.

Sample Payload Request:

• validateaddress_request.json

Sample Payload Response:

• validateaddress_response_400.json
• validateaddress_response_200.json

Validator Extensions

The validator extensions are available in the Infosys Equinox Commerce platform across many services, as shown here. The extensions can be used to validate the request object based on custom business logic and the result will persist in the Infosys Equinox Commerce platform based on the response received for the extension.

Postman Collection

The following are the Postman collections:

• Reference_postman_environment.json
• Validators_postman_collection.json

Sample Response Payload for All Extensions

Success:

{     “responseMessage”: “Product Validated Successfully”,     “status”: 200 }

Error:

{     “responseCode”: “ERROR_PROPERTIES_MISSING”,     “responseMessage”: “Properties field required”,     “timeStamp”: “2024-05-08T09:36:52.188Z”,     “status”: 409 }

The following table describes the parameters in the Error response:

Parameter	Description
responseCode	This holds a string value. The error codes for the validation are to be provided.
responseMessage	This holds a string value. The response message for the validation is to be provided.
timeStamp	This holds the validation timestamp.
status	This holds the status of the response such as Success: 200 and Failure: 409.

 

 

Revision History

2024-05-23 | AN – Updated the content.
2024-05-20 | JP – Updated the content.
2024-05-15 | AN – Created the page and uploaded the contents for release 8.17.4.