Link Search Menu Expand Document
Centrapay Docs

Integration Requests

Integration Requests enable terminal integrations and acceptance of asset types for a Merchant.

Contents

Models

Integration Request

Mandatory Fields

Field Type Description
id String The Integration Request’s unique identifier.
accountId String The Integration Request’s owning Centrapay Account id.
merchantId String The Merchant id for the Integration Request.
type String The type of the Integration Request. Refer to Integration Types.
status String The current status of the Integration Request. Supported values are active, available, pending, rejected and disabled.

Optional Fields

Field Type Description
terminalId String The payment system terminal id. Required for NZ Epay integration.
terminal Terminal The terminal configuration. Required for all terminal vendors except Vista.
product Product The requested Epay gift card types to support.

Terminal

Required Fields

Field Type Description
terminalId String The software or logical id of the payment terminal.

Optional Fields

Field Type Description
deviceId String The hardware id or serial number of the payment terminal.

Product

Required Fields

Field Type Description
name String The name of the requested Epay product.

Integration Types

Name Description
verifone Terminal vendor Verifone
windcave Terminal vendor Windcave
epay Asset provider ePay
smartpay Terminal vendor smartpay
invenco Terminal vendor invenco
skyzer Terminal vendor skyzer
vista Terminal vendor vista

Operations

Create an Integration Request EXPERIMENTAL

POST /api/integration-requests 

curl -X POST https://service.centrapay.com/api/integration-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "5ee0c486308f590260d9a07f",
    "type": "verifone",
    "terminal": {
      "terminalId": "002039390093939",
      "deviceId": "002-039-390"
    }
  }'

curl -X POST https://service.centrapay.com/api/integration-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "5ee0c486308f590260d9a07f",
    "type": "epay",
    "product": {
      "name": "koha-card"
    }
  }'

Required Fields

Field Type Description
merchantId String The Merchant id for the Integration Request.
type String The type of the Integration Request.

Optional Fields

Field Type Description
terminal Terminal The terminal configuration. Required for Verifone and Windcave integration.
product Product The requested Epay gift card types to support.

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "merchantId": "5ee0c486308f590260d9a07f",
  "type": "verifone",
  "status": "pending",
  "createdAt": "2020-06-12 01:17:46 UTC",
  "updatedAt": "2020-06-12 01:17:46 UTC",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "terminal": {
    "terminalId": "002039390093939",
    "deviceId": "002-039-390"
  }
}

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "merchantId": "5ee0c486308f590260d9a07f",
  "type": "epay",
  "status": "pending",
  "createdAt": "2020-06-12 01:17:46 UTC",
  "updatedAt": "2020-06-12 01:17:46 UTC",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "product": {
    "name": "koha-card"
  }
}

Get an Integration Request EXPERIMENTAL

GET /api/integration-requests/{integrationRequestId} 

curl https://service.centrapay.com/api/integration-requests/DKTs3U38hdhfEqwF1JKoT2 \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "merchantId": "5ee0c486308f590260d9a07f",
  "type": "epay",
  "status": "pending",
  "terminalId": "11000021",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "product": {
    "name": "koha-card"
  }
}

Search Integration Requests EXPERIMENTAL

Returns a paginated list of Integration Requests.

GET /api/integration-requests 

curl -G https://service.centrapay.com/api/integration-requests \
  -H "X-Api-Key: $api_key" \
  -d type=epay \
  -d pending=true \
  -d accountId=Jaim1Cu1Q55uooxSens6yk

Query Parameters

Parameter Description
accountId The Integration Request’s owning Centrapay Account id. Required unless caller has global read access permission.
type The type of Integration Request.
pending When set to true, only include Integration Requests with pending status.

Example response payload 

{
  "items": [
    {
      "id": "DKTs3U38hdhfEqwF1JKoT2",
      "accountId": "Jaim1Cu1Q55uooxSens6yk",
      "merchantId": "5ee0c486308f590260d9a07f",
      "type": "epay",
      "status": "pending",
      "terminalId": "11000021",
      "createdAt": "2020-06-12T01:17:46.499Z",
      "updatedAt": "2020-06-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "product": {
        "name": "koha-card"
      }
    }
  ]
}

Configure Integration Request EXPERIMENTAL

Supply configuration values for the Integration Request.

PUT /api/integration-requests/{integrationRequestId}/configs 

curl -X PUT https://service.centrapay.com/api/integration-requests/DKTs3U38hdhfEqwF1JKoT2/configs \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "terminalId": "11000021"
  }'

Optional Fields

Field Type Description
terminalId String Epay terminalId for the Integration Request. Required if type is epay.

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "merchantId": "5ee0c486308f590260d9a07f",
  "type": "epay",
  "status": "pending",
  "terminalId": "11000021",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "product": {
    "name": "koha-card"
  }
}

Get Integration Request Configuration EXPERIMENTAL

GET /api/integration-requests/{integrationRequestId}/configs 

curl https://service.centrapay.com/api/integration-requests/DKTs3U38hdhfEqwF1JKoT2/configs \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "terminalId": "11000021"
}

Activate Integration Request EXPERIMENTAL

POST /api/integration-requests/{integrationRequestId}/activate 

curl -X POST https://service.centrapay.com/api/integration-requests/DKTs3U38hdhfEqwF1JKoT2/activate \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "merchantId": "5ee0c486308f590260d9a07f",
  "type": "epay",
  "status": "active",
  "terminalId": "11000021",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "product": {
    "name": "koha-card"
  }
}

Error Responses

Status Code Description
403 INTEGRATION_PARAM_MISSING Integration Request needs updating with the required parameters before activating.
403 INTEGRATION_ALREADY_ACTIVATED Integration Request is already activated.

Delete Integration Request EXPERIMENTAL

DELETE /api/integration-requests/{integrationRequestId} 

curl -X DELETE https://service.centrapay.com/api/integration-requests/DKTs3U38hdhfEqwF1JKoT2 \
  -H "X-Api-Key: $api_key"

Example response payload 

{
}