API Calls

The GWDDeviceService provides an API for communicating with the IPP350 Card Payment Terminal. The base url for all API calls is http://localhost:8526/GWDDeviceService/IPP350/.

Authentication

When consuming the API, all calls must authenticate using Basic Authentication . The user name and password will be provided in your setup instructions.

---

Status

Get the current status of the IPP350 Terminal. This can be used to ensure the terminal is available before making a transaction request or when first starting the application.

URL:

/status

Method:

GET

URL Params:

none

Data Params:

none

Example:

GET http://localhost:8526/GWDDeviceService/IPP350/status HTTP/1.1
Authorization: Basic a2l0dGVuczphcmVzb2xvdmVseQ==
Content-Type: application/json

Success Response:  

Code:200 OK Content-Type:application/json Content Body:IPP350CardTerminalState

HTTP/1.1 200 OK
Content-Length: 37
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 11:12:53 GMT

{"Description":"Idle","StatusCode":1}

Error Response:

Code:401 Unauthorized Example:

HTTP/1.1 401 Unauthorized
Content-Length: 45
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 11:21:10 GMT

"Username or password provided is incorrect."

IPP350CardTerminalState

These are the status codes and descriptions returned in a Status request.

StatusCode	Description	Explanation
0	Unknown	Unable to get status of the terminal.
1	Idle	The terminal is available and ready to process transactions.
2	NotAvailable	Unable to communicate with the terminal. This may be a an error in the configuration or the terminal is not connected.
3	Busy	Terminal is already processing a request.

---

Transaction Request

Send a new transaction request to the terminal and receive a response detailing the transaction result. The request result will be returned after the card terminal returns the transaction information. This may take some time while the customer uses the terminal to pay. You should wait for the result to be returned as if you time out before the transaction has completed you will not receive the information but the terminal may still finish the transaction and charge the customer card.

URL:

/Transaction

Method:

POST

URL Params:

none

Data Params:

{ “amount”: [decimal or string]}

Amount must be a positive number. If more than 2 decimal places are included, they are truncated.

Example:

POST http://localhost:8526/GWDDeviceService/IPP350/transaction HTTP/1.1
Authorization: Basic a2l0dGVuczphcmVzb2xvdmVseQ==
Content-Type: application/json

{
    "amount":15.00
}

Success Response:  

Code:

200 OK

Content-Type:

application/json

Content Body:

Transaction

HTTP/1.1 200 OK
Content-Length: 1581
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 11:16:04 GMT

{
  "Transaction": {
    "CustomerReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT            £15.00",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": "PIN VERIFIED",
      "CourtesyMessage": "Thank You",
      "DataSource": "ICC",
      "DateAndTime": "16/03/17 11:13",
      "DiagnosticCode": "DIAG 73",
      "FinalMessage1": "     CUSTOMER COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:***07901",
      "MerchantName": "Global Payments         ",
      "Message": "AUTH CODE:004040",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025485348",
      "SCH_ID2": "77",
      "SequenceNumber": "337",
      "TerminalID": "TID:****1279        S",
      "TransactionNumber": "TXN 0219",
      "TransactionType": "SALE"
    },
    "ErrorCode": 0,
    "ErrorMessage": "NoError",
    "MerchantReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT            £15.00",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": "PIN VERIFIED",
      "DataSource": "ICC",
      "DateAndTime": "16/03/17 11:13",
      "DiagnosticCode": "DIAG 73",
      "ExpiryDate": "EXP 12/20",
      "FinalMessage1": "     MERCHANT COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:79807901",
      "MerchantName": "Global Payments         ",
      "Message": "AUTH CODE:004040",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025485348",
      "SCH_ID2": "77",
      "SequenceNumber": "337",
      "StartDate": "STT 11/06",
      "TerminalID": "TID:22161279        S",
      "TransactionNumber": "TXN 0219",
      "TransactionType": "SALE"
    }
  }
}

See Example Transaction JSON for more examples for different kind of transaction results.

Error Responses:  

400 Bad Request

HTTP/1.1 400 Bad Request
Content-Length: 42
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 10:33:57 GMT

"Amount -1 is not valid for a transaction"

401 Unauthorized

HTTP/1.1 401 Unauthorized
Content-Length: 44
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 10:50:00 GMT

"No authorization header has been provided."

---

Transaction

Name	Description	Data Type
CustomerReceipt	Details of the transaction as provided by the terminal, aimed to be printed on customer receipt. May be null if transaction didn’t complete successfully. See CustomerReceipt for fields.	CustomerReceipt
MerchantReceipt	Details of the transaction as provided by the terminal, aimed to be printed on the merchant receipt. May be null if transaction didn’t complete successfully. See MerchantReceipt for fields.	MerchantReceipt
ErrorCode	Code that indicates wheter communication with the terminal was successful and what error was encountered. See the ErrorCode for all the possible values.	Integer
ErrorMessage	Description of the ErrorCode	String
ReceiptId	Unique identifier for the transaction. This can be used when requesting to print a receipt.	String

CustomerReceipt

Customer receipt contains all the information provided by the IPP350 Terminal after a transaction request has been made. Fields containing strings may be null if the terminal does not provide the information. Boolean fields default to false. Note that customer receipt will not be populated for Contactless transactions, all the transaction details will be included in the MerchantReceipt instead.

Name	Description	Data Type
AID	Application ID. Required on receipt for ICC/Contactless cards.	String
Amount	Amount. Required on receipt.	String
ApplicationLabel	Application label. Required on receipt for ICC/Contactless cards.	String
CourtesyMessage	Courtesy message. Optional on receipt.	String
CVMResult	Cardholder verification method, for example PIN VERIFIED or SIGNATURE VERIFIED. Required on receipt.	String
DataSource	ie. ICC/KEYED/SWIPE/CONTACTLESS Required on receipt.	String
DateAndTime	Time and date for the transaction. DD/MM/YY HH:mm Required on receipt.	String
DiagnosticCode	Diagnostic Code. Optional on receipt.	String
FinalMessage1	Message for customer. Optional on receipt.	String
FinalMessage2	Message for customer. Optional on receipt.	String
Handset	Handset. Optional on receipt.	String
IsDeclined	Indicates if the transaction was declined by the carrier. If the transaction was declined, this must be stated on the receipt.	Boolean
IssuerName	Card Issuer. Required on receipt.	String
IsVoid	Indicates if the transaction is void, for example Cancelled. Required on receipt if the transaction was void.	Boolean
MerchantID	The Merchant Account Number. Partly masked. Required on receipt.	String
MerchantName	Merchant name. Required on receipt but the value does not have to be provided by the terminal.	String
Message	ie. AUTH CODE/CANCELLED/DECLINED etc. Required on receipt.	String
PAN	Card number, masked so that only the last four numbers are shown. Required on receipt.	String
PanSequenceNumber	PAN Sequence number. Required on receipt for ICC/Contactless cards.	String
SCH_ID1	Optional on receipt.	String
SCH_ID2	Optional on receipt.	String
SequenceNumber	Sequence number. Optional on receipt.	String
TerminalID	The Terminal ID. Partly masked. Required on receipt.	String
TransactionNumber	Transaction number. Required on receipt.	String
TransactionType	ie. SALE or REFUND etc. Required on receipt.	String

MerchantReceipt

Merchant receipt contains all the information provided by the IPP350 Terminal after a transaction request has been made. Fields containing strings may be null if the terminal does not provide the information. Boolean fields default to false.

Name	Description	Data Type
AID	Application ID. Required on receipt for ICC/Contactless cards.	String
Amount	Amount. Required on receipt.	String
ApplicationLabel	Application label. Required on receipt for ICC/Contactless cards.	String
CVMResult	Cardholder verification method, for example PIN VERIFIED or SIGNATURE VERIFIED. Required on receipt.	String
DataSource	ie. ICC/KEYED/SWIPE/CONTACTLESS Required on receipt.	String
DateAndTime	Time and date for the transaction. DD/MM/YY HH:mm Required on receipt.	String
DiagnosticCode	Diagnostic Code. Optional on receipt.	String
ExpiryDate	Card Expiry date. Required on receipt.	String
FinalMessage1	Message for customer. Optional on receipt.	String
FinalMessage2	Message for customer. Optional on receipt.	String
Handset	Handset. Optional on receipt.	String
IsDeclined	Indicates if the transaction was declined by the carrier. If the transaction was declined, this must be stated on the receipt.	Boolean
IssuerName	Card Issuer. Required on receipt.	String
IsVoid	Indicates if the transaction is void, for example Cancelled. Required on receipt if the transaction was void.	Boolean
MerchantID	The Merchant Account Number. Required on receipt.	String
MerchantName	Merchant name. Required on receipt but the value does not have to be provided by the terminal.	String
Message	ie. AUTH CODE/CANCELLED/DECLINED etc. Required on receipt.	String
PAN	Card number, masked so that only the last four numbers are shown. Required on receipt.	String
PanSequenceNumber	PAN Sequence number. Required on receipt for ICC/Contactless cards.	String
SCH_ID1	Optional on receipt.	String
SCH_ID2	Optional on receipt.	String
SequenceNumber	Sequence number. Optional on receipt.	String
StartDate	Card Start date. Required on receipt.	String
TerminalID	The Terminal ID. Required on receipt.	String
TransactionNumber	Transaction number. Required on receipt.	String
TransactionType	ie. SALE or REFUND etc. Required on receipt.	String

ErrorCode

These are the error codes and messages returned in a Transaction.

ErrorCode	ErrorMessage	Description
0	NoError	Successful communication with the terminal. Note that the transaction itself may not have been successful.
1	TerminalBusy	The terminal is already processing a request.
2	HardwareError	Error communicating with the terminal, for example if the terminal is not connected or the port is not correct.
3	InternalError	Internal error while dealing with the request.
4	CancelledBeforeCardIn	Customer clicks cancel on terminal before entering card or transaction times out when card was never inserted.
5	ReceiptNotAvailable	Receipt cannot be provided.

---

Example Transaction JSON

Here are some examples of the JSON returned by a transaction request for different kinds of transaction results.

Chip and Pin:

{
  "Transaction": {
    "CustomerReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT             £2.00",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": "PIN VERIFIED",
      "CourtesyMessage": "Thank You",
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:06",
      "DiagnosticCode": "DIAG 73",
      "FinalMessage1": "     CUSTOMER COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:***07901",
      "MerchantName": "Global Payments         ",
      "Message": "AUTH CODE:003608",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025442144",
      "SCH_ID2": "45",
      "SequenceNumber": "321",
      "TerminalID": "TID:****1279        S",
      "TransactionNumber": "TXN 0204",
      "TransactionType": "SALE"
    },
    "ErrorCode": 0,
    "ErrorMessage": "NoError",
    "MerchantReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT             £2.00",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": "PIN VERIFIED",
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:06",
      "DiagnosticCode": "DIAG 73",
      "ExpiryDate": "EXP 12/20",
      "FinalMessage1": "     MERCHANT COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:79807901",
      "MerchantName": "Global Payments         ",
      "Message": "AUTH CODE:003608",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025442144",
      "SCH_ID2": "45",
      "SequenceNumber": "321",
      "StartDate": "STT 11/06",
      "TerminalID": "TID:22161279        S",
      "TransactionNumber": "TXN 0204",
      "TransactionType": "SALE"
    }
  }
}

Declined:

{
  "Transaction": {
    "CustomerReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT           £147.77",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": null,
      "CourtesyMessage": "Thank You",
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:10",
      "DiagnosticCode": "DIAG 1073",
      "FinalMessage1": "     CUSTOMER COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": true,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:***07901",
      "MerchantName": "Global Payments         ",
      "Message": "DECLINE",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025442244",
      "SCH_ID2": "46",
      "SequenceNumber": "322",
      "TerminalID": "TID:****1279        S",
      "TransactionNumber": "TXN 0205",
      "TransactionType": "SALE"
    },
    "ErrorCode": 0,
    "ErrorMessage": "NoError",
    "MerchantReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT           £147.77",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": null,
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:10",
      "DiagnosticCode": "DIAG 1073",
      "ExpiryDate": "EXP 12/20",
      "FinalMessage1": "     MERCHANT COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": true,
      "IsVoid": false,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:79807901",
      "MerchantName": "Global Payments         ",
      "Message": "DECLINE",
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:00000000025442244",
      "SCH_ID2": "46",
      "SequenceNumber": "322",
      "StartDate": "STT 11/06",
      "TerminalID": "TID:22161279        S",
      "TransactionNumber": "TXN 0205",
      "TransactionType": "SALE"
    }
  }
}

Contactless:

{
  "Transaction": {
    "CustomerReceipt": {
      "AID": null,
      "Amount": null,
      "ApplicationLabel": null,
      "CVMResult": null,
      "CourtesyMessage": null,
      "DataSource": null,
      "DateAndTime": null,
      "DiagnosticCode": null,
      "FinalMessage1": null,
      "FinalMessage2": null,
      "Handset": null,
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": null,
      "MerchantID": null,
      "MerchantName": null,
      "Message": null,
      "PAN": null,
      "PanSequenceNumber": null,
      "SCH_ID1": null,
      "SCH_ID2": null,
      "SequenceNumber": null,
      "TerminalID": null,
      "TransactionNumber": null,
      "TransactionType": null
    },
    "ErrorCode": 0,
    "ErrorMessage": "NoError",
    "MerchantReceipt": {
      "AID": "AID: A0000000041010",
      "Amount": "AMOUNT             £0.20",
      "ApplicationLabel": "MASTERCARD",
      "CVMResult": null,
      "DataSource": "CONTACTLESS",
      "DateAndTime": "13/03/17 16:56",
      "DiagnosticCode": "DIAG 1073",
      "ExpiryDate": "EXP 02/20",
      "FinalMessage1": "     MERCHANT COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": false,
      "IssuerName": "MASTERCARD",
      "MerchantID": "M:79807901",
      "MerchantName": "Global Payments         ",
      "Message": "AUTH CODE:001008",
      "PAN": "************6451",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": "SCH ID:HNR0057660313  ",
      "SCH_ID2": null,
      "SequenceNumber": "327",
      "StartDate": "STT 17/02",
      "TerminalID": "TID:22161279        S",
      "TransactionNumber": "TXN 0209",
      "TransactionType": "SALE"
    }
  }
}

Void:

{
  "Transaction": {
    "CustomerReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT           £147.77",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": null,
      "CourtesyMessage": "Thank You",
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:12",
      "DiagnosticCode": null,
      "FinalMessage1": "     CUSTOMER COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": true,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:***07901",
      "MerchantName": "Global Payments         ",
      "Message": null,
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": null,
      "SCH_ID2": null,
      "SequenceNumber": "323",
      "TerminalID": "TID:****1279        S",
      "TransactionNumber": null,
      "TransactionType": "SALE"
    },
    "ErrorCode": 0,
    "ErrorMessage": "NoError",
    "MerchantReceipt": {
      "AID": "AID: A0000000031010",
      "Amount": "AMOUNT           £147.77",
      "ApplicationLabel": "Visa Debit Test ",
      "CVMResult": null,
      "DataSource": "ICC",
      "DateAndTime": "13/03/17 15:12",
      "DiagnosticCode": null,
      "ExpiryDate": "EXP 12/20",
      "FinalMessage1": "     MERCHANT COPY      ",
      "FinalMessage2": " PLEASE RETAIN RECEIPT",
      "Handset": "HANDSET:1",
      "IsDeclined": false,
      "IsVoid": true,
      "IssuerName": "VISA DEBIT",
      "MerchantID": "M:79807901",
      "MerchantName": "Global Payments         ",
      "Message": null,
      "PAN": "************5234",
      "PanSequenceNumber": "PAN SEQ NO. 01",
      "SCH_ID1": null,
      "SCH_ID2": null,
      "SequenceNumber": "323",
      "StartDate": "STT 11/06",
      "TerminalID": "TID:22161279        S",
      "TransactionNumber": null,
      "TransactionType": "SALE"
    }
  }
}

Hardware Error:

{
  "Transaction": {
    "CustomerReceipt": null,
    "ErrorCode": 2,
    "ErrorMessage": "HardwareError",
    "MerchantReceipt": null
  }
}

Cancelled:

{
  "Transaction": {
    "CustomerReceipt": null,
    "ErrorCode": 4,
    "ErrorMessage": "CancelledBeforeCardIn",
    "MerchantReceipt": null
  }
}

---

Print Receipt

Send a request to print a receipt for a card transaction.

URL:

/PrintReceipt

Method:

POST

URL Params:

none

Data Params:

{

“merchantName”: [string], (REQUIRED)

“merchantAddress”: [string], (REQUIRED)

“merchantPhone”: [string], (OPTIONAL)

“receiptId”: [string], (REQUIRED)

“transactionId”: [string], (OPTIONAL)

“totalAmount”: [decimal or string], (REQUIRED)

“itemisedCost”: (OPTIONAL)

[list [

{“label” : [string], “value”: [decimal or string]},

{“label” : [string], “value”: [decimal or string]}]]

}

Required parameters must be provided, if they are missing or incorrect you will receive a 400 response. Optional parameters will be printed on receipt if they are provided, if you don’t wish to include them they can be left out altogether.

totalAmount must be a positive number. If more than 2 decimal places are included, they are truncated.

transactionId is any ID in your system for the transaction that you wish to include on the receipt.

receiptId must match an id provided with a recent Transaction response. The receipt will only be available while service is running. If the service is restarted then previous receipts will no longer be available. If a receipt is not found a 400 response is returned.

ItemisedCost must be provided as a list of label and value pairs. The itemisation will be printed on receipt with the labels provided, if you provide the itemised cost you should ensure the itemisation matches the total as this will not be checked. Each label provided must be unique.

Example:

POST http://localhost:8526/GWDDeviceService/IPP350/PrintReceipt HTTP/1.1
Authorization: Basic a2l0dGVuczphcmVzb2xvdmVseQ==
Content-Type: application/json

{
    "merchantName": "Kittens Ltd",
    "merchantAddress": "Purr Street 1, London E1 1XX",
    "merchantPhone": "0104 12301123",
    "receiptId": "abcdefgh-fe3a-4410-aa40-b33132d91611",
    "transactionId": "123121323232323",
    "totalAmount": 15.00,
    "itemisedCost": [{"label" : "First item", "value": 8.00},
                     {"label" : "Service Charge", "value": 7.00}]
}

Success Response:  

Code:

200 OK

Content-Type:

application/json

Content Body:

PrintingStatus

HTTP/1.1 200 OK
Content-Length: 1581
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 11:16:04 GMT

{
  "Description": "SuccessfullySentToPrintQueue",
  "StatusCode": 1
}

Error Responses:  

400 Bad Request

HTTP/1.1 400 Bad Request
Content-Length: 42
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 10:33:57 GMT

"Please provide Merchant name and address."

401 Unauthorized

HTTP/1.1 401 Unauthorized
Content-Length: 44
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 16 Mar 2017 10:50:00 GMT

"No authorization header has been provided."

---

PrintingStatus

These are the error codes and messages returned for a Print Receipt request.

StatusCode	Description	Explanation
0	NoPrintQueue	Unable to send receipt to be printed because printer is not available.
1	SuccessfullySentToPrintQueue	Receipt created successfully and sent to print queue. We cannot guarantee the printing finishes successfully, but a printer was found and the receipt was added to the queue.
2	ErrorCreatingReceipt	Internal error while creating the receipt.