Elavon downloads and stores cookies on your device when you visit our website. We use these cookies to better understand and improve your browsing experience by identifying most visited pages, personalising content, and measuring site performance.

Essential cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies; they can only be disabled by changing your browser preferences.

These are cookies that support site functionality that is visible or advantageous to you or your experience of the site, they enable websites to remember choices and provide a more personalized experience.   Functional cookies help to provide services that you request, such as language preference or layout.

Performance cookies help us to improve our website by collecting and reporting information on its usage (for example, which of our pages are most frequently visited).

These cookies and similar technologies gather information about your browsing habits. They remember that you've visited a website and share this information with other organisations, such as advertisers and platforms on which we advertise. They do this in order to provide you with ads that are more relevant to you and your interests. Although these cookies and similar technologies can track your visits to other websites, they don't usually know who you are. Without these cookies, online advertisements you encounter will be less relevant to you and your interests.

Cookie Settings

U.S. Bank Europe DAC. Registered in Ireland – Number 418442..  Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.
 
U.S. Bank Europe DAC. Registered in Ireland with Companies Registration Office. The liability of the member is limited. United Kingdom branch registered in England and Wales under the number BR022122.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is a credit institution authorised and regulated by the Central Bank of Ireland.  Authorised by the Prudential Regulation Authority.  Subject to regulation by the Financial Conduct Authority and limited regulation by the Prudential Regulation Authority.  Details about the extent of our regulation by the Prudential Regulation Authority are available from us on request.

Most popular solutions

Additional solutions

Fusebox integration & options

Optional platform features

Documentation

North America

Europe

Regions

Integration with Elavon Cloud Payments Interface offers an out-of-the-box solution, eliminating the need for a physical connection between your POS application and the payment device. The PIN pads we support are configured with PCI-compliant software from :magic-link[Simplify]{id="/products/simplify/v1/overview"}, an Elavon payment application. 

This page outlines what you need to get started with your integration, describes Elavon Cloud Payments Interface's authentication process and clarifies some common terms used in this guide.

## Getting started

1. Determine your integration needs:
 - Which devices (PIN pads, printers, etc.) will be available on site? 
 - Will your integration support Simplify status feedback messages, to enable cashiers to help guide a consumer by sending guidance messages to the PIN pad? 
	 This feature utilizes asynchronous transactions, which require the integrator to act as a server that listens for responses. 
	 A webhook URL will need to be established and configured to listen for HTTP POST requests.

2. Contact Elavon Cloud Payments Interface (websales@elavon.com) to set up an account and receive credentials.

3. Set up one or more devices for development and testing. See :magic-link[How to Pair Your Payment Devices]{id="device-operations#pairing-a-device"}.

4. Develop your POS/PMS application using Elavon Cloud Payments Interface's :magic-link[test environment]{id="#endpoints"}. 

5. Work with your solution engineer to order production hardware (devices typically arrive within 7-10 days).

6. Once you've completed testing and certification, configure your POS/PMS application to use Elavon Cloud Payments Interface's :magic-link[production environment]{id="#endpoints"}.

## Terminology

The same terms can be used in different ways in the payments industry, so we want to be clear about our usage of them in our documentation.

- **POS** / **PMS** - the browser-based front-end used to accept payments at the counter. 
 - **POS** refers to *point of sale*, typically used by the retail and restaurant/service industries. 
 - **PMS** refers to *property management system*, typically used by the lodging industry.
	Both POS and PMS interact with Elavon Cloud Payments Interface in a comparable way to process transactions.

- **Integrator** - the portion of the POS/PMS application that communicates with Elavon Cloud Payments Interface.
 - Functions as a client when submitting requests via Elavon Cloud Payments Interface's RESTful API. Requires credentials (supplied by Elavon Cloud Payments Interface administrator) to communicate with Elavon Cloud Payments Interface.
 - Functions as a server when receiving responses to asynchronous transactions. Listens for asynchronous responses sent to its *webhook URL*.

- **Devices** - any internet-connected peripheral or system that opens and manages the connection to Elavon Cloud Payments Interface via TCP/IP and interacts with the POS or PMS. 
 Examples include payment devices (PIN pads), barcode scanners and receipt printers. 
 - Payment devices come bundled with Elavon's Simplify software.

- **Terminal Management System** - software used to update payment devices. 
 Currently this refers to :magic-link[Hosted Estate Manager (HEM)]{id="/products/simplify/v1/initiate-hem-or-ingestate-message-tran-type-3607"}, which is used to update Simplify PIN pads.

- **Payment gateway** - an electronic service that processes card transactions by secure communication between a merchant, payment processor and financial institutions. 
 Currently, Elavon Cloud Payments Interface uses :magic-link[Fusebox]{id="/products/fusebox/v1/overview"} as its payment gateway.

## Networking

Inter-application communication between Elavon Cloud Payments Interface, PIN pads, the payment gateway and the terminal management system uses TLS 1.2 over TCP/IP, where each system is assigned its own base URI. 

For example: `uat.pos.hpi.elavonaws.com:443`. 

All request URIs referenced in this guide appear with a placeholder {host}, where the endpoint for the desired system and environment (test, production) should be substituted. 

For example, using the above endpoint, the URI 

`https://{host}/...` 

would become: 

`https://uat.pos.hpi.elavonaws.com:443/...`

## Endpoints

**Test environment**

| Client System | Target System | Environment | Address | Port |
|--------------------|----------------------------------------------------------|-------------|---------------------------|------|
| Integrator System | Elavon Cloud Payments Interface | Test | uat.pos.hpi.elavonaws.com | 443 |
| Simplify (PIN Pad) | Fusebox (Payment Gateway) | Test | gatewaydemomoc.elavon.net | 7000 |
| Simplify (PIN Pad) | Hosted Estate Manager (HEM) (Terminal Management System) | Test | termupdateuat.elavon.net | 6423 |
| Simplify (PIN Pad) | Elavon Cloud Payments Interface | Test | uat.sa.hpi.elavonaws.com | 6000 |

**Production environment**

| Client System | Target System | Environment | Address | Port |
|--------------------|----------------------------------------------------------|-------------|----------------------------|------|
| Integrator System | Elavon Cloud Payments Interface | Production | devices.elavongateway.com | 443 |
| Simplify (PIN Pad) | Fusebox (Payment Gateway) | Production | fuseboxtrant.elavon.net | 7000 |
| Simplify (PIN Pad) | Hosted Estate Manager (HEM) (Terminal Management System) | Production | termupdate.elavon.net | 6423 |
| Simplify (PIN Pad) | Elavon Cloud Payments Interface | Production | simplify.elavongateway.com | 6000 |

:::::notice{note}

These addresses and ports must be opened on the firewall at the merchant's location to enable the proper communication.
:::::

## Authentication 

Elavon Cloud Payments Interface requires the integrator to identify itself for all transactions and device operations. 
A unique ID (integratorId) is provided for this purpose by an Elavon Cloud Payments Interface administrator. 
The integratorId is tied to the OAuth credentials of the integrator.

### Bearer tokens

Elavon Cloud Payments Interface uses bearer tokens to authenticate requests. The tokens must be passed in the header of each request sent to Elavon Cloud Payments Interface. 
Tokens are retrieved from Elavon Cloud Payments Interface's endpoint using client credentials supplied by your Elavon Cloud Payments Interface administrator.

### Client credentials

Elavon Cloud Payments Interface's endpoint requires client credentials in order to retrieve tokens. 
These credentials are provided by a Elavon Cloud Payments Interface administrator, in the form of a username (client\_id) and password (client\_secret). 
These are generated by Elavon Cloud Payments Interface - the integrator cannot choose their own client\_id or client\_secret.

:::::notice{note}

If your client credentials become compromised, notify your Elavon Cloud Payments Interface Client Executive immediately and they will provide new ones.

:::::

### Retrieving tokens

Tokens are retrieved by submitting a request via POST, containing the base64-encoded client credentials, to the Elavon Cloud Payments Interface endpoint 

`https://{host}/credentials/token` 

substituting the **Elavon Cloud Payments Interface endpoint** for {host}. 

The Elavon Cloud Payments Interface endpoint can be found in section [Endpoints](#endpoints), in the table for the desired environment, where target system is "Elavon Cloud Payments Interface Authentication".

For example, in the UAT environment, the URI would be: `https://uat.pos.hpi.elavonaws.com/credentials/token.` Elavon Cloud Payments Interface responds with a token which can be used for up to 15 minutes.

:::::notice{important}

Only send token requests when it has expired. Frequent token requests will be seen as a DDOS attack by Elavon Cloud Payments Interface's system, and the IP address will be blocked for a period of time.
:::::

### Token request

For a token request, you will need your **client\_id** (synonymous with username) and **client\_secret** (synonymous with password). Use these to derive {Base64EncodedCredentials} by concatenating client\_id, a colon (":") and client\_secret (e.g., client\_id:client\_secret) and Base64-encoding that as a string. The {Base64EncodedCredentials} must be sent as part of the authorization header.

A Correlation-Id header can optionally be sent, containing a unique identifier (8-50 characters) for the request and response. This value may help in support and troubleshooting. The request body is always "grant\_type=client\_credentials".

:::::notice{note}
For token request, the content-type should be specified "application/x-www-form-urlencoded".
:::::

#### Request URI

`https://{host}/credentials/token`

#### Request headers
```
Authorization: Basic {Base64EncodedCredentials}
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Accept-Version: V2
Correlation-Id: {Correlation-Id}
```
**Request body:** `Grant\_type=client\_credentials`

#### Request example

```
curl -X POST
'https://uat.pos.hpi.elavonaws.com/credential/token'
-H 'Authorization: Basic {Base64EncodedCredentials}'
-H 'Content-Type: application/x-www-form-urlencoded'
-H 'Accept: application/json'
-H 'Accept-Version: V2'
-H 'Correlation-Id: abc12345678'
-d 'grant\_type=client\_credentials'
```

### Token response

**Response HTTP codes**

| Code | Comment |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 200 OK | Success - details in response body. |
| 401 Unauthorized | Failure - typically related to an invalid client\_id or client\_secret. |
| 404 Not Found | Failure - not able to contact Elavon Cloud Payments Interface. Please contact your Elavon Cloud Payments Interface administrator. |

#### Response body

For a successful request (HTTP response code 200), the response body contains the following details in the JSON payload: 

| Name | Type / Format / Length / Valid Values | Description | Request? | Response? |
|---------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|----------------------------------------------------------|
| access\_token | String | The is your authentication key (AKA apiKey), which must be included in the header of all Elavon Cloud Payments Interface requests (this is further explained in Constructing the Header). | | Yes |
| token\_type | String VALID VALUES: bearer | The type of token, for Elavon Cloud Payments Interface this should be "bearer". | | Yes |
| expires\_in | Number | Number of seconds the token expires in. | | Yes |
| Jit | String | JWT ID, a unique identifier (case-sensitive string) for the JSON Web Token (JWT). This is provided as additional information and can be ignored. | | Yes |

#### 200 OK (Success)

```json
{
 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ZZZZZZZZZXZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZzZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZInWh85PHrdkDgmmcgvTL6AKhcbErAuXnHyrI7xPrEwd11VSbQSL3dB_FmBvbhK6XrR4ggKGHDh40WUImdwwNBvWCckfKKbA",
 "token_type": "bearer",
 "expires_in": 899,
 "jti": "ce54zzzz-d41a-zzzz-a12a-12f709zzzzz"
}
```

#### 401 Unauthorized (Invalid client secret)

```json
{
 "code" : "401.0809.0101",
 "message" : "Authentication failed. You are unauthorized for this resource",
 "details" : [ {
 "errorDetail" : {
 "attributeName" : "Unauthorized",
 "reason" : "Unauthorized"
 }
 } ]
}
```

#### 404 Not Found (Invalid client id)

```json
{
 "code" : "404.0809.0104",
 "message" : "Not Found",
 "details" : [ {
 "errorDetail" : {
 "attributeName" : "integrator-id",
 "reason" : "Integrator Not Found"
 }
 } ]
}
```

## Using tokens

The authentication key (token) must be passed in the header of each request sent to Elavon Cloud Payments Interface.

- Tokens expire after 15 minutes. If more than 15 minutes have passed since you retrieved your token, you will need to request another from the endpoint. If an expired token is used, Elavon Cloud Payments Interface will respond with an HTTP response code of 401. Do not retrieve a new token before every API call, as this will make your transactions take longer and complicates the flow. Use tokens as long as they are valid and request a new one only as needed.

- If an Integrator's POS application has a need to support a JSON Web Token (JWT) per merchant account, that can be supported. It is important to not request a new JWT every transaction as depending on the transaction volume, it could be detected as a denial of service (DDOS) attack and that Integrator would be blocked for a temporary time period.

Integration overview