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

This section provides details on sending requests and retrieving responses to communicate with Elavon Cloud Payments Interface.

## Constructing the header

The header-level information consists of the following:

| Header | Value | Comment |
|----------------|----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Accept | application/json | |
| Accept-Version | V2 | |
| Content-Type | application/vnd.elavon.transaction-b.v1+json | |
| Authorization | Bearer {token} | The bearer token retrieved from Elavon Cloud Payments Interface's token endpoint, for example "eyjhzzzz-zzzz-zzzz-zzzz-zzzzzzz9e1b2". |
| Correlation-Id | String (8-50 characters). | Optional client-generated identifier for the API request-response pairing. If provided, the value must be unique. This value may help in support and troubleshooting. |

### Example header

```
Accept: application/json
Accept-Version: V2
Content-Type: application/vnd.elavon.transaction-b.v1+json
Authorization: Bearer eyjhzzzz-zzzz-zzzz-zzzz-zzzzzzz9e1b2
Correlation-Id: abc12345679
```

## Sending your DeviceId

Your **deviceId** is sent to the Elavon Cloud Payments Interface API as part of the request URI path.

:::::notice{note}
The deviceId is **different from** the client\_id.

The deviceId ties the integrator to their devices, while a client\_id is used for authentication.
:::::

Substitute your deviceId for `{deviceId}` in all request URIs. 

For example, if your deviceId is "fq4mWHKM3hdrQJhB", then the URI 

`https://{host}/devices/{deviceId}/message` 

becomes 

`https://{host}/devices/fq4mWHKM3hdrQJhB/message`

## Sending the request

Requests are *synchronous* when Elavon Cloud Payments Interface immediately processes the request and returns a response directly to the integrator. For example, device pairing requests are processed synchronously.

*Asynchronous* requests are handled in a similar fashion to synchronous requests, but Elavon Cloud Payments Interface does not wait until the request has completed processing before returning a response. Instead, the response is sent to the integrator via another, separate webhook mechanism. Other status messages that identify the processing steps for the original request are also sent to the integrator's webhook.

Requests that are processed by Elavon Cloud Payments Interface asynchronously must:

- Identify the response channel type as **webhook**.

- Include a registered *webhook URL* - an address that Elavon Cloud Payments Interface should route the response back to in the response in the response channel object.

The integrator acts as a **server** and listens for responses sent to the webhook URL via HTTP POST. For example, credit card transactions may be processed asynchronously.

:::::notice{note}
An Integrator may have more than one webhook endpoint supported in Elavon Cloud Payments Interface. As long as each webhook is registered in Elavon Cloud Payments Interface and follows one of the three approved security formats, Elavon Cloud Payments Interface will return the response message to that webhook URL.
:::::

## Handling the response

When a request is sent, Elavon Cloud Payments Interface immediately responds to the integrator with a conventional HTTP response code to indicate the success or failure of an API request.

In the case of synchronous messaging, the immediate response includes the actual message response with a 200 HTTP response code.

In the case of asynchronous messaging, the immediate response is an acknowledgement the message was successfully received with a 202 HTTP response code or unsuccessfully received with an error response code. The actual message response is returned to the *webhook URL* provided in the message request.

### HTTP Response Codes

| Code Range | Description |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2xx | Success. <ul><li>For **pairing**, the details are contained in the response body</li><li>For **synchronous** requests, the response body is returned.</li><li>For **asynchronous** requests, further transaction responses from the device (such as authorization approval/decline from Fusebox) are sent back to the integrator at its webhook URL, with the details contained within the response body.</li></ul>|
| 4xx | Error due to the given information provided. |
| 5xx | Error on the Elavon Cloud Payments Interface side. |

### Error object

The HTTPS response body contains an error object to provide details on the error. 

| Name | Type / Format / Length / Valid Values | Description | Request? | Response? |
|---------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|---------------|
| code | String ({\#}.{\#}.{\#}, 1-14) | Format is {code}.{id}.{err} where {code} is the HTTPS numeric response code, {id} is a numeric unique identifier for Elavon Cloud Payments Interface and {err} is a numeric value indicating type of error. | | Yes |
| message | String (1-255) | The reason the request was not successful. | | Yes |
| help | String (URL) | This is an optional URL to online help. This will be populated once online help is available. This field is not populated at this time. | | Yes |
| details | Array | Array containing error objects. | | Yes |
| details .attributeName | String (1-50) | Attribute name that causes the error response. | | Yes |
| details .reason | String (1-50) | What is wrong with attribute. | | Yes |

Elavon Cloud Payments Interface numeric code values indicating type of error include the following:

| Code | Type | Description | Display Text |
|------|--------------|-----------------------------------------------------------------------------|----------------------------------|
| 0001 | Parameter | Invalid Parameter - no match in Elavon Cloud Payments Interface | Parameter Not Valid |
| 0002 | Parameter | Invalid Parameter - too many parameters | Too Many Parameters |
| 0003 | Parameter | Invalid Parameter - bad format (exceeds length/invalid datatype) | Invalid Format |
| 0004 | Parameter | Invalid Parameter - Missing required parameter | Missing Required Parameter |
| 0020 | Request Body | Missing Key Request Field | Missing Required Field |
| 0021 | Request Body | Badly/invalid formatted Field Value | Invalid Format |
| 0023 | Request Body | Pairing Code Expired | Pairing Code Expired |
| 0024 | Request Body | Pairing Code Does not Exist | Pairing Code Not Found |
| 0025 | Request Body | Request Array/List exceeds bounds | Bad Format - Check Size |
| 0026 | Request Body | Device exists, but is not connected, unavailable | Device Offline |
| 0027 | Request Body | Device is busy and cannot handle request, try again later | Device Busy - Retry |
| 0028 | Request Body | Timeout waiting for response from Device | Timeout on response from Device |
| 0029 | Request Body | Timeout waiting for response from Gateway | Timeout on response from Gateway |
| 0101 | | Unauthorized | Unauthorized |
| 0103 | | Forbidden | Not Authorized |
| 0105 | | Not Found (Parameter resource Not Found in Elavon Cloud Payments Interface) | Not Found |

Requests and responses