Introduction

This guide provides a comprehensive overview of integrating Ingenico Direct, with Maxxton Software. It outlines the steps for setup, payment method availability, and the Ingenico payment flow.

Ingenico / MXTS integration

Payment Method Availability

MXTS supports a variety of payment methods. The following table lists the payment methods implemented:

Initial Configuration Process

The configuration of Payment Service Provider (PSP) accounts is primarily conducted by Maxxton. Clients looking to integrate Ingenico Direct into their MXTS environment must submit a request via a Jira ticket.

The key steps include:

1. Creation of Ingenico account: Get a PSPID account from Ingenico

2. PSP Account Setup: Maxxton configures the client's PSP account with Ingenico. (We ask Ingenico to link Maxxton support account to client account)

3. Technical Setup: Includes enabling API settings and configuring endpoint URLs in the Ingenico Backoffice.

   1. Direct API key and Secret. (Please note secret is only visible when generated, you have to copy and save it in PaymentServiceProvider Configuration)

   2. Webhooks API key and Secret. (Please note secret is only visible when generated, you have to copy and save it in PaymentServiceProvider Configuration)

   3. Endpoint URLs - Postback URLs which are Maxxton's external API to process the payment notification and payment entries are added based on these postbacks.

   4. Endpoint URLs for Test and Production

      • https://api-test.maxxton.net/external/v1/payments/postback/ingenico/direct

      • https://api.maxxton.net/external/v1/payments/postback/ingenico/direct

4. Credential Management: Direct API keys and secrets are provided to Maxxton during setup and stored securely.

Open

Configuration in MXTS

Please follow this page to see an example of an implementation of a payment method in MXTS.

https://maxxton.atlassian.net/wiki/spaces/TP/pages/333905925

Customer website integration

Open

We have successfully established the required configurations for steps 1 and 3 of the process. It is important to note that upon completing a transaction, the customer will be redirected back to the client's website. This redirection is facilitated by the 'returnUrl' parameter, a component of the payment link endpoint developed by Maxxton.

However, simply redirecting the customer does not convey the outcome of the payment. Therefore, it is essential for the client to implement a mechanism on their website to interpret the 'returnUrl' and ascertain the payment status. The following section of the documentation will provide a detailed exploration of how to implement this functionality, ensuring that the client's website can accurately determine and respond to the success or failure of a transaction.

Generating Payment Links

Link to API documentation: https://developers.maxxton.com/maxxton/v1/documentation/html5/index.html#_ingenico_integration

Payment links for individual reservations are generated by Maxxton using the Ingenico API, simplifying the payment process for clients:

• Link Generation: MXTS creates a unique payment link for each reservation, which leads directly to the Ingenico payment page.

• Customization: Links can be customized with specific parameters, such as payment methods and language preferences.

This endpoint is used to generate a payment link that will direct the customer to the Ingenico Direct payment page with pre-filled transaction details. Below is the detailed description of each parameter that can be included in the request:

Endpoint Parameters: https://developers.maxxton.com/maxxton/v1/swagger/index.html#/Reservations/getPaymentLink

• currencyCode: Specifies the currency code (ISO 4217 format) for the transaction. Payments will be processed in the designated currency.

• countryCode: The country code (ISO 3166-1 alpha-2 format, e.g., 'NL' for the Netherlands, 'FR' for France) is necessary to determine the appropriate payment methods available from Ingenico. Note that this parameter does not affect the language or locale settings of the Ingenico payment page.

• payerType: Defines the classification of the payer. Possible values are:

  • PAYING_CUSTOMER: A direct customer making a payment.

  • AGENT: A representative or agent making a payment on behalf of a customer.

  • CUSTOMER: The default payer type for standard customer transactions.

• paymentMethods: A list of payment methods that should be available for selection on the payment page. If not specified, all payment methods configured in the Ingenico platform will be displayed. To limit the options, retrieve the available payment methods from the designated endpoint and pass the desired values in this request.

• price: The amount that the customer is required to pay. This could either be the full amount of the reservation or a partial amount, according to the installment terms configured for the reservation. To retrieve installment details, use the reservation endpoint.

• returnUrl: The URL to which the customer will be redirected after completing the payment. This parameter is exclusively used with Ingenico Direct. For the legacy Ingenico platform, different URLs (declineUrl, acceptUrl, cancelUrl, homeUrl, exceptionUrl) corresponding to the transaction outcome were used. Ingenico Direct consolidates these into a single returnUrl.

• locale: Determines the language used on the payment page. The fields 'name' and 'infoTexts' in the payment page generation will be translated based on the provided locale code. Example values include 'en' for English, 'nl' for Dutch, 'fr' for French, among others.

• reservationId: Uniquely identifies the reservation to which the payment is applied. Upon successful payment processing by Ingenico, the outstanding amount for this reservation will be reduced by the paid amount.

To ensure a seamless payment process and facilitate post-payment actions, the returnUrl parameter is critical. Upon the completion of a payment, Ingenico appends additional information to this URL, effectively creating a full redirect URI that guides the customer back to your site. Here's a more in depth explanation of the flow involving the returnUrl parameter:

1. Setting the returnUrl Parameter: When initiating a payment process, you will pass the returnUrl parameter within the request. This URL is the destination where the customer should land after completing the payment flow on Ingenico's platform. You will get from the previous endpoint a link similar to this: https://payment.preprod.direct.worldline-solutions.com/hostedcheckout/PaymentMethods/Selection/a1325c92c35450dfa981051d29adfe9e

2. Appending Information: After the payment is done, Ingenico augments the returnUrl with query string parameters. These parameters will contain the information needed for the next call. (RETURNMAC=d89fa6d5-cca6-42a6-9430-a37c3864314d&hostedCheckoutId=3990539467)

3. Custom Query Strings: You have the option to include any number of custom key-value pairs in the returnUrl query string. These pairs can be tailored to assist in identifying the returning customer or the transaction context (for example the reservationId)

4. Customer Redirection: The customer is then redirected to the provided returnUrl, which now includes the Ingenico supplied information as well as any custom query strings you have added.

5. Retrieving Payment Status: Once the customer is redirected back to your site with the enhanced returnUrl, you can use the appended information to make a subsequent API call to retrieve the full status and details of the payment.

Handling Payment Status

To provide the correct page for your customers, clients must implement the call to Ingenico's Hosted Checkout Status:

• Status Check: Clients should use Ingenico API to retrieve the current status of the payment session.

• Customer Direction: Based on the payment status, clients can direct customers to the appropriate page (e.g., payment confirmation or cancellation page).

This endpoint allows you to obtain the current status of a payment session initiated through Ingenico's hosted checkout. Here's how you can use the endpoint to track payment progress:

Endpoint Description

• HTTP Method: GET

• Endpoint: /hostedcheckouts/{hostedCheckoutId}/status

• Purpose: To check the real-time status of an ongoing payment session or confirm the details of a completed payment.

Parameters

• merchantId (required): This is your unique Merchant Identifier provided by Ingenico, which is essential for authenticating the request (PSPID)

• hostedCheckoutId (required): A unique identifier for the hosted checkout session, which you receive when the payment session is initiated.

Usage

• Initiating a Status Request: Perform a GET request using the hosted checkout session's unique hostedCheckoutId.

• Understanding the Response: If a payment has been initiated or completed during the hosted checkout session, the response object will contain the relevant details, such as the payment status and transaction IDs.

• Session Time Limit: Each hosted checkout session has a maximum duration of 3 hours. It is crucial to retrieve the status within this timeframe, as the information is inaccessible after the session expires.

• Dynamic Status: The status information is dynamic. It updates throughout the checkout session, reflecting the customer's actions in real-time until the session concludes.

With this implementation in place, clients are able to establish a logical flow for directing customers to the appropriate page post-payment. By leveraging the information provided by the returnUrl, clients can tailor the redirection experience based on the outcome of the transaction, ensuring a better customer flow.

Asynchronous Callback from Ingenico

Maxxton ensures that the asynchronous callback from Ingenico is seamlessly integrated:

• Data Handling: Validation and recording of payment information are automated within MXTS.

• No Client Development: This process requires no additional development on the client's side.

Support and Maintenance

• Requesting Assistance: For configuration changes or support, clients should submit a Jira ticket to Maxxton.

• Updates & Notifications: Clients will be informed of any changes to endpoint URLs or other critical updates by Maxxton.