Introduction to integrations: Hosted, Host2Host and JavaScript

Introduction

Addon Payments allows you to integrate the payment gateway into your business. This introductory guide provides a basic overview of the following topics: types of integration available, data needed to start integration, where to get the data and the different environments (staging and production).

Checkout types

Addon Payments offers three (3) different types of checkout integration.

Hosted Integration | Safe

Integration Host2Host | Flexible

Provides full control over the payment process, PCI required in case of card data processing
Allows access to a full set of transaction management applications
Suitable for call centre integrations and advanced projects
Recommended for alternative payment methods with redirection ready

JavaScript integration | Customizable

What do you need to start integration?

Before getting started with any of the integrations, you have to collect some information you will need for the process. In addition to this information, you should also be aware of the difference between the environments.

The following points of this guide have information on both things.

Data needed for integration (and where to get it)

Before starting any of the three (3) integrations, you need to have the following information to hand:

merchantId: It is the ID for your merchant on the Addon Payments platform.
- It is a numerical code provided by Support in the welcome email.
- It has between 4 and 7 digits and is the same for both environments (staging/production).
- For example: 14983.
Encryption password (merchantPass): This is your merchant password. It varies depending on the environment you will send the request to. You can get it in several ways:
- The password for the staging environment comes in the welcome email. To recover it, see the going live guide.
- For the production environment, recover it through the Addon Payments BackOffice Portal. To recover it, see the going live guide.
- The password is in PBKDF2 with HmacSHA256 format, where the merchantId is used as the salt and 10,000 iterations are applied. For example:
  - merchantId and Salt: 2150100
  - Raw password: NewPassword123!
  - Iterations: 10,000
  - Result: Odm1hxMXWmkRs9bs3ibrQLs1YUcepvR3JguIzBHt7Sw=

The following is only required for JavaScript integrations:

JavaScript password (merchantKey): The JavaScript password is a Universal Unique Identifier (UUID) that authorizes the connection and rendering of the cashier using JS.
- It must have a valid UUID format. To recover it, see the going live guide.

Environments: staging and production

Addon Payments offers two (2) separate operating environments:

Staging environment:
- This is the first environment you will use.
- There is a list of cards to use for testing the system, simulating transactions of various operations, authentication types (frictionless, challenge) and results (authorized, declined).
- This will allow you to make sure that the different situations are handled properly by your integration.
- Real cards and accounts don’t work.
Production Environment:
- In this environment, transactions are real.
- You can only use real, operational cards and accounts.

Integrations

Below is a brief description of the basic functioning of the integrations.

Hosted

Hosted integration consists in redirecting customers to a payment form (cashier) hosted by Addon Payments. Customers reach that form from your website by their browser being redirected or through an iframe. Since your business doesn’t have access to customer details, you can accept payment without PCI DSS certification.

When the transaction is complete in any of the statuses (authorized, declined, cancelled, etc.):

Your platform receives a notification with the result of the transaction.
The customer is redirected to the corresponding URL for each transaction result (authorized, declined, cancelled).

You can change the functions and appearance of the payment form (cashier) either in your merchant settings or by sending certain parameters in the payment request.

Host2Host (H2H)

H2H integration consists in sending requests directly from your ecommerce platform to the endpoint provided by Addon Payments (AP). The process is as follows:

Your ecommerce platform generates a request containing the data needed for the operation (card payment, APM payment, secondary operation, etc.).
- Card payments require the customer’s card details or a token generated previously.
- To capture, store or send card data, you merchant must have valid PCI DSS certification.

2. Your platform sends the request to the Apendpointendpoint , which returns a response such as:

- Redirect required:
  - The payment solution responds by requiring the customer be redirected to a URL, where they will follow the instructions given (authentication, login, operation approval, etc.).
  - If the customer completes the process, your ecommerce platform will receive a “Result” notification to the notification URL from the request in point 1.
- Result:
  - The payment solution has authorized or declined the transaction and the final transaction status is given.

3. Your ecommerce platform manages the response received from AP with the transaction result and updates the payment status for the order.

JavaScript (JS)

JavaScript integration consists in rendering the AP cashier on your ecommerce platform using JS. This rendering is done with an <div> HTML element.

Integration into your ecommerce platform is very high. Plus, your merchant doesn’t require PCI DSS certification, as you won’t have access to the customers’ data.

Note: It requires an underlying H2H integration to process transactions.

Introduction to integrations: Hosted, Host2Host and JavaScript

Introduction

Checkout types

What do you need to start integration?