Endpoint Instance API

The Endpoint Instance REST API provides the ability to create and register endpoints in the platform. It enables you to initiate workflows for terminal creation and onboarding and also to query for the status of previously initiated workflows.

All APIs are defined using OpenAPI / Swagger and we make them available via postman. The documentation here is intended to give an overview of the API.

Endpoint Instance OpenAPI Specification

You can view and download the JSON formatted OpenAPI file directly here

Documentation

Case sensitivity

Note that all fields and parameters used in the API are case sensitive.

Endpoints

Create or update entities

POST /initiate

Calling this endpoint initiates a new workflow in the platform. This workflow can be used to create, update or delete entities (merchants, locations or terminals) in the platform.

The body of the request must specify the following mandatory fields for the API to identify the correct flow to execute.

• partnerId => Provided by Aevi to represent a partner/client of the API
• type => The type of flow to execute, such as onboard for onboarding
• format => The format of the request data
• contextData => The request data, bespoke to the type and format provided

Additionally, merchantAcquirerId can optionally be specified where required.

See the relevant integration guides for further information about the data models based on the flow type and format.

If your submitted data is validated successfully then this endpoint returns a 200 response and an object containing a workflowRequestId.

An example success response is shown below.

{
    "workflowRequestId": "c8805e8b-7404-44c5-852a-cfd43fb4e292",
    "status": "RECEIVED",
    "partnerId": "platformexample",
    "merchantAcquirerId": "isv1",
    "flowType": "create",
    "lastUpdateDateTime": 1690199028502
}

Get the status of a workflow

GET /status/:workflowRequestId

Retrieve the status of a previously initiated workflow by using the workflowRequestId returned from the initiation of a flow. The response object returned is the same as the response shown above for the initiate method.

This returns information about the outcome of the overall flow as well as the outcome of each individual stage the flow executed.

HTTP error codes

Any errors as a result of calling a HTTP endpoint will return a status code and a response body, as per the below format:

{
    "errorMessage": "someMessage",
    "errorCode": "someErrorCode"
}

Below is a table of the various errors.

HTTP status code	Error code	Description
400	failed	Unexpected failure
401	unauthorized	Missing or invalid Authorization bearer token
403	forbidden	The operation attempted is not allowed
404	notFound	The item requested or referenced does not exist
409	duplicateItem	The item can not be created as it already exists
410	connectionLost	The target the request was intended for is not available
412	preconditionFailed	The operation attempted can not be carried out due to existing preconditions
417	storageFailed	The item could not be persisted
422	invalidData	The request is missing required data or the data defined is invalid