API

API Requests

Content-Type header: All requests sent are expected to have the Content-Type HTTP header set to application/json

Authorization header: Request headers should use Basic Authorization providing the Username and Password values. Credentials can be managed in the instance dashboard settings screen.

Host address: The host is unique for each deployed environment and will be provided as as part of merchant setup. You'll need to make sure this value is configurable in your POS.

Endpoints

Terminals

Endpoints to query currently connected terminal state.

Get Terminals

GET {{hostAddress}}/api/v1/pay-at-counter/terminals?currency=&status=

Gets a list of all connected terminals.

Request Parameters

Fields in bold are required.

Field Description
currency Filter the response to only terminals in a particular currency. Allowed values are: GBP
status Filter the response to only terminals with a particular status. Allowed values are: AVAILABLE or BUSY.
curl --location --request GET "{{hostAddress}}/api/v1/pay-at-counter/terminals" \
  --header "Authorization: Basic dGVzdDp0ZXN0"

RESPONSE FORMAT

{
  /* Array of currently connected terminals */
  "result": [
    {
      /* Unique terminal identifier (tid) */
      "terminal_id": "73570000",
      /* Terminal currency. Possible values: GBP, EUR */
      "currency": "GBP",
      /* Terminal status. Possible values: AVAILABLE, BUSY */
      "status": "AVAILABLE",
      /* Last terminal activity time */
      "last_activity": "2019-05-22T14:18:51.607Z",
      /* Device connection information */
      "device_address": "10.20.30.40:0"
    }
  ]
}
    

Get Terminal Details

GET {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id

Gets details for a terminal.

RESPONSE FORMAT

{
  /* Array of currently connected terminals */
  "result": {
      /* Unique terminal identifier (tid) */
      "terminal_id": "73570000",
      /* Terminal currency. Possible values: GBP, EUR */
      "currency": "GBP",
      /* Terminal status. Possible values: AVAILABLE, BUSY */
      "status": "AVAILABLE",
      /* Last terminal activity time */
      "last_activity": "2019-05-22T14:18:51.607Z",
      /* Device connection information */
      "device_address": "10.20.30.40:0"
    }
}

Fields in bold are required.

Field Description
terminal_id {{tid}} Unique identifier assigned of the terminal.

Example success Response

{
  "result": [
    {
      "terminal_id": "73570000",
      "currency": "GBP",
      "status": "AVAILABLE",
      "last_activity": "2019-05-23T07:07:21.174Z",
      "device_address": "test:0"
    }
  ]
}

Transactions

Endpoints for the transaction creation and management.

Start Transaction

POST {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/transactions

Starts new transaction.

Request Body Format

{
    /* Transaction type. Possible values are SALE, REFUND, DUPLICATE */
    "transaction_type": "SALE",

    /* Transaction amount in pence. Required for SALE and REFUND transactions */
    "amount": 100,

    /* Transaction currency. Required for SALE and REFUND transactions */
    "currency": "GBP"
}

Response Format

{
    "result": {
        /* Started transaction identifier */
        "transaction_id": "f161183c-1be9-4349-b5c5-7e28367d42de"
    }
}

Headers

Key Value
Content-Type application/json

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.

Body

{
    "transaction_type": "SALE",
    "amount": 2,
    "currency": "GBP"
}

Duplicate Transaction Receipt

POST {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/transactions/duplicate

Reprints receipt of last transaction on the PDQ device.

Headers

Key Value
Content-Type application/json

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.

Get Transaction Details

GET {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/transactions/:transaction_id

Gets data for the transaction.

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.
transaction_id {{transactionId}} Unique identifier of the transaction.

Example success Response

{
  "result": {
    /* Unique transaction identifier. Can be used with other API endpoints. */
    "id": "0a2e0f51-38c3-4cad-b1ed-5aa3cdf60540",

    /* Terminal identifier (TID) */
    "tid": "22163227",

    /* Number of the transaction for current terminal session. */
    "transaction_number": "TXN 0096",

    /* Type of transaction. Can be SALE or REFUND */
    "transaction_type": "SALE",

    /* Transaction result. Can be CANCELLED, TRANSACTION_UNSUCCESSFUL, CANCELLED_BY_USER, SUCCESSFUL, VOID, FAILED_NOT_SUPPORTED, FAILED_ERROR, TIMED_OUT */
    "transaction_result": "SUCCESSFUL",

    /* Time transaction was created */
    "transaction_time": "2019-05-30T12:23:37.000Z",

    /* Identifier of the application in the card used. */
    "application_id": "AID: A0000000031010",

    /* Title of the application in the card. */
    "application_label": "Visa Prepaid",

    /* Transaction authorisation code */
    "auth_code": "692314",

    /* Unique transaction reference number */
    "reference_number": "10796628",

    /* Transaction currency */
    "currency": "GBP",

    /* Base amount in pence without gratuity */
    "amount_base": 1,

    /* Cashback amount in pence */
    "amount_cashback": 0,

    /* Gratuity amount in pence */
    "amount_gratuity": 0,

    /* Total amount in pence*/
    "amount_total": 1,

    /* Card issuer name. */
    "issuer_name": "VISA CREDIT",

    /* Method used to verify that the person presenting the card. */
    "card_holder_verification_method": "NO CARDHOLDER",

    /* Expiry date of the card used in the transaction. */
    "date_of_expiry": "EXP 12/23",

    /* Start date of the card used in the transaction. */
    "date_of_start": null,

    /* Method used to read the card details */
    "payment_method": "CONTACTLESS",

    /* Primary Account Number of the card used in the transaction. */
    "primary_account_number": "************6902",

    /* Sequence number of the PAN of the card used in the transaction. */
    "primary_account_number_sequence": "PAN SEQ NO. 00",

    /* Notifications indicating the progress of the transaction. Possible values CONNECTING,  CONNECTION_MADE, APPROVED,
    DECLINED, INSERT_CARD, CARD_ERROR, PROCESSING_ERROR, REMOVE_CARD, RETRYING, PRESENT_CARD, REPRESENT_CARD,
    CARD_NOT_SUPPORTED, PRESENT_ONLY_ONE_CARD, PLEASE_WAIT, BAD_SWIPE, CARD_EXPIRED, DECLINED_BY_CARD, PIN_ENTRY,
    CASHBACK_AMOUNT_ENTRY, PAPER_OUT, UNSUPPORTED, SIGNATURE_VERIFICATION, SIGNATURE_VERIFICATION_COMPLETED,
    SIGNATURE_VERIFICATION_COULD_NOT_BE_COMPLETED, SIGNATURE_VERIFICATION_TIMEOUT, TRANSACTION_FINISHED */
    "device_notifications": [
      "PRESENT_CARD",
      "REMOVE_CARD",
      "CONNECTING",
      "CONNECTION_MADE",
      "APPROVED",
      "TRANSACTION_FINISHED"
    ],

    /* Time the transaction was created */
    "created_at": "2019-05-30T12:23:37.000Z",

    /* Last time the transaction was modified */
    "updated_at": "2019-05-30T12:23:47.000Z",

    "receipt_lines": {
      "MERCHANT": [
        {
          /* Line format, can contain list any of  BOLD, DOUBLE_HEIGHT, DOUBLE_WIDTH */
          "format": [
            "BOLD",
            "DOUBLE_HEIGHT"
          ],
          /* Line type, can be any of TEXT, CARRIAGE_RETURN, LINE_SEPARATOR, DOUBLE_LINE_SEPARATOR, TICKET_FEED, VOID_BOX, DECLINE_BOX */
          "type": "TEXT",

          /* Line contents */
          "value": "AIB Test IWL258         "
        }
      ],

      "CUSTOMER": [
        {
          /* Line format, can contain list any of  BOLD, DOUBLE_HEIGHT, DOUBLE_WIDTH */
          "format": [
            "BOLD",
            "DOUBLE_HEIGHT"
          ],
          /* Line type, can be any of TEXT, CARRIAGE_RETURN, LINE_SEPARATOR, DOUBLE_LINE_SEPARATOR, TICKET_FEED, VOID_BOX, DECLINE_BOX */
          "type": "TEXT",

          /* Line contents */
          "value": "AIB Test IWL258         "
        }
      ]
    }
  }
}

Cancel Transaction

DELETE {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/transactions/:transaction_id

Attempts to cancel pending transaction.

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.
transaction_id {{transactionId}} Unique identifier of the transaction.

Sign Transaction

PUT {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/transactions/:transaction_id/signature

Apply signature verification on the transaction.

Request Format

{
    /* flag to indicate if the signature was verified succesfully. */
    "accepted": true
}

Headers

Key Value
Content-Type application/json

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.
transaction_id {{transactionId}} Unique identifier of the transaction.

Body

{
	"accepted": true
}

Reports

Endpoints for report retrieval

Retrieve Report From Terminal

POST {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/reports

Starts report retrieval from device.

Request Format

{
    /* Requested report type. Possible values are END_OF_DAY, BANKING, X_BAL, Z_BAL */
    "type": "BANKING"
}

Headers

Key Value
Content-Type application/json

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.

Body

{
	"type": "BANKING"
}

Get Report Details

GET {{hostAddress}}/api/v1/pay-at-counter/terminals/:terminal_id/reports/:report_id

Gets details for a report.

Response Format

{
  "result": {
    /* Unique report identifier. Can bve used in other API calls */
    "id": "7ef7be61-3f17-4fb7-bb5c-879c3112190a",

    /* Terminal id (TID) of device used to make the report. */
    "tid": "22163227",

    /* Report type. Can me one of X_BAL, Z_BAL, END_OF_DAY, BANKING */
    "report_type": "BANKING",

    /* COMPLETE, FAILED_NOT_SUPPORTED, FAILED_ERROR, TIMED_OUT */
    "report_result": "COMPLETE",

    /* Time report was requested */
    "report_time": "2019-05-30T13:17:06.000Z",

    /* Report status updates, Can contain any of REPORT_STARTED, REPORT_FINISHED */
    "device_notifications": [
      "REPORT_STARTED",
      "REPORT_FINISHED"
    ],

    /* Time report was created */
    "created_at": "2019-05-30T13:17:06.000Z",

    /* Time report was last updated */

    "updated_at": "2019-05-30T13:17:13.000Z",

    /* Banking totals for the current terminal session. Has value for report of types BANKING and END_OF_DAY. Contains reports by acquirer name. */
    "banking": {
      "{example acquirer}": {

        /* Currency of the report. */
        "currency": "GBP",

        /* Totals (in pence) split for each issuer. */
        "current_session_issuer_totals": {
          "MASTERCARD": {
            /* Currency used. */
            "currency": "GBP",

            /* Total amount. */
            "total_amount": 1,

            /*Total amount of refunds */
            "total_refunds_amount": 0,

            /* Total amount of sales */
            "total_sales_amount": 1,

            /* Number of refunds */
            "total_refunds_count": 0,

            /* Number of sales */
            "total_sales_count": 1
          }
        },

        /* Totals (in pence) split for each issuer. */
        "previous_session_issuer_totals": {
          "MASTERCARD": {
            /* Currency used. */
            "currency": "GBP",

            /* Total amount. */
            "total_amount": 1,

            /*Total amount of refunds */
            "total_refunds_amount": 0,

            /* Total amount of sales */
            "total_sales_amount": 1,

            /* Number of refunds */
            "total_refunds_count": 0,

            /* Number of sales */
            "total_sales_count": 1
          }
        },

        "current_session_totals": {
          /* Currency used. */
          "currency": "GBP",

          /* Total amount. */
          "total_amount": 12,

          /*Total amount of refunds */
          "total_refunds_amount": 0,

          /* Number of refunds */
          "total_refunds_count": 0,

          /* Total amount of sales */
          "total_sales_amount": 12,

          /* Number of sales */
          "total_sales_count": 7
        },

        "previous_session_totals": {
          "currency": "GBP",

          /* Total amount. */
          "total_amount": 12,

          /*Total amount of refunds */
          "total_refunds_amount": 0,

          /* Number of refunds */
          "total_refunds_count": 0,

          /* Total amount of sales */
          "total_sales_amount": 12,

          /* Number of sales */
          "total_sales_count": 7
        },

        /* Transaction numbers (range) for the current session. */
        "current_session_transaction_numbers": [
          "0088",
          "0101"
        ],

        /* Transaction numbers (range) for the previous session. */
        "previous_session_transaction_numbers": [
          "0052",
          "0087"
        ]
      }
    },

    /* Local totals for the current terminal session. Has value for report of types END_OF_DAY, X_BALANCE, Z_BALANCE */
    "balances": {

      /* Totals split by issuer. */
      "issuer_totals": {
        "MASTERCARD": {
          /* Currency used. */
          "currency": "GBP",

          /* Total amount. */
          "total_amount": 1,

          /*Total amount of refunds */
          "total_refunds_amount": 0,

          /* Total amount of sales */
          "total_sales_amount": 1,

          /* Number of refunds */
          "total_refunds_count": 0,

          /* Number of sales */
          "total_sales_count": 1
        }
      },

      /* Currency used. */
      "currency": "GBP",

      /* Total amount of cashback that has been taken in the current session. */
      "total_cashback_amount": 0,
      /* Total number of transactions with cashback that have taken place in the current session. */
      "total_cashback_count": 0,

      /* Total amount of gratuity that has been taken in the current session. */
      "total_gratuity_amount": 0,

      /* Total number of transactions with gratuity that have taken place in the current session. */
      "total_gratuity_count": 0,

      /* Total amount of refunds that has been taken in the current session. */
      "total_refunds_amount": 0,

      /* Total number of transactions with refunds that have taken place in the current session. */
      "total_refunds_count": 0,

      /* Total amount of sales that has been taken in the current session. */
      "total_sales_amount": 5,

      /* Total number of transactions with sales that have taken place in the current session. */
      "total_sales_count": 4,

      /* Time at which the terminal totals were last reset. */
      "totals_since": "Since 30/05/19 09:59",

      /* Total amount that has been taken in the current session. */
      "total_amount": 5
    },

    /* Receipt for the report */
    "receipt_lines": [
      {
        /* Line format, can contain list any of  BOLD, DOUBLE_HEIGHT, DOUBLE_WIDTH */
        "format": [
          "BOLD",
          "DOUBLE_HEIGHT"
        ],
        /* Line type, can be any of TEXT, CARRIAGE_RETURN, LINE_SEPARATOR, DOUBLE_LINE_SEPARATOR, TICKET_FEED, VOID_BOX, DECLINE_BOX */
        "type": "TEXT",

        /* Line contents */
        "value": "END OF DAY"
      }
    ]
  }
}

Path Variables

Key Value
terminal_id {{tid}} Unique identifier assigned of the terminal.
report_id {{reportId}} Unique identifier of the report.
Last Updated: 12/12/2019, 5:37:00 PM