This interface manual is Copyright© 2015 by PayEx.
This document is the property of PayEx and the information contained herein is confidential. The compositions and contents herein are not to be copied, reproduced, printed, published, posted, displayed, incorporated, stored in or scanned into a retrieval system or database, transmitted, broadcast, bartered or sold, in whole or in part without the prior express written permission of the sole author, who is, unless otherwise denoted, PayEx. Unauthorized duplication is strictly prohibited and is an infringement of National and International Copyright laws.
Although the best efforts were made to ensure that the information in the manual is complete and correct, PayEx makes no warranty of any kind with regard to this material, including but not limited to the implied warranties of marketability and fitness for a particular purpose. Information in this manual is subject to change without notice.
PayEx shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this interface manual.


Contents
1      Changelog               4
2      Installation topology               5
3      Purpose               6
3.1      Scope               6
4      PosPay Client overview               7
4.1      General               7
5      Main flow of integration               10
5.1      Streaming:               10
5.2      Polling:               10
5.3      The main flow of all transactions:               10
6      HTTP/JSON API overview               10
6.1      HTTP headers               10
6.2      JSON format               11
6.3      Error handling               11
6.4      Service uri and versioning               13
7      Event handling and callback               14
7.1      HTTP streaming               14
7.2      Polling alternative               16
8      List of events               19
9      Special events               22
10      Input dialogs               23
10.1      Example of input dialogs               23
11      PosPay Client service requests               26
11.1      Get Event Request               26
11.2      Purchase               28
11.3      Refund               31
11.4      Reverse               33
11.5      Pre Authorization               35
11.6      Adjust Pre Authorization               37
11.7      Close Pre Authorization               39
11.8      Delete Pre Authorization               41
11.9      Get Pre Authorization               43
11.10      Get Pre Authorization Response               45
11.11      Late Debit               48
11.12      Late Credit               50
11.13      Get Transaction Result               52
11.14      Cancel               63
11.15      Open Ped               65
11.16      Close Ped               67
11.17      Activate               68
11.18      Verify               70
11.19      Deposit               72
11.20      Balance               74
11.21      Withdrawal               76
11.22      Card Info               78
11.23      Card Info Response               79
11.24      Get Input Dialog               80
11.25      Send Input               83
11.26      Cancel input               85
11.27      Ping               86


Changelog
Version
Changes
Date
0.1
Initial document
0.2
Some minor parameter changes, and typos.
Added input dialogs
2012.12.21
0.3
Changed JSON array description for get input dialog and send input
2013.01.04
0.4
Changed description and usage of posReference, orderId and retreivalReferenceNumber and .
Added accountOption to the transactionResponse
Added purchase, Refund and Reversal
2013.01.18
0.5
Added RESPONSE as event type
2013.01.28
1.0
Added Installation topology
Added Main flow of integration
Added List of event codes
2013.03.19
1.1
Added services:
closePreAuth
deletePreAuth
getPreAuth
getPreAuthResponse
adjustPreAuth
lateDebit
lateCredit
closePed
activate
verify
deposit
balance
withdrawal
cardInfo
getCardInfoResponse
ping
2013.11.11
1.4.1
Added STATUS and RESPONSE event types
2014.10.17
1.5
Corrections to JSON examples
Spelling corrections
Marked all parameters as mandatory in getPreAuth
2014.10.29
1.6, 1.7
Updated the document with input dialogues, descriptions of how to use component dll, pictures etc.
2014.12.19
2.3
Removed duplicate information, added new events and fixed typing errors.
2015.06.04
2.3.1
Reformatted transaction diagrams
2015.09.21
2.3.2
Added recurring payments
2015.10.06
Installation topology
This document describes changes made in PosPay Client v4.5.2 and above.
Below is a description of the communication links for Point of Sale installations with payment terminals (ECR - PosPay Client - Terminal - Host - TMS).
Payment requests:
The ECR sends a request to the PosPay Client. PosPay Client handles the request and forwards the request to the terminal, asking for card data input. Card data is sent back to PosPay Client and then sent to the Host for validation/confirmation. The host send a response back to the PosPay Client, which notifies both the terminal and the ECR the outcome (accepted/declined).
Terminal update requests:
When updates is needed for the payment terminal, this is triggered by the Host.
Host send a pending request to the terminal. The terminal finishes the current assignment, if any, and closes the connection with PosPay Client. The request is sent to TMS, which send the update back to the terminal. When the installation is complete, the terminal boots and the connection with PosPay Client is re-established.
Purpose
This document contains the PosPay Client interface specification. It does not cover the interfaces against neither the PIN-pad nor the PosPay Server.
Scope
The PosPay Client interface is a module intended to give a POS Application access to the various payment services provided by the PosPay Client. The PosPay Client offers all services required to process payment transactions (both online and offline). In addition, it supports a number of administrative services. The PosPay Client is also responsible for all communication with the PIN-pad and the PosPay Server.
The PosPay Client can also offer purchase restriction validation of each item group that the customer wants to purchase against the card used for payment, the detailed item information received from the POS Application and the card definitions & card profile tables loaded into the PosPay Client is used to check for purchase restrictions – if restrictions apply the purchase request from POS Application will be rejected.
The detailed item information is forwarded to the PosPay Server which in turn will send the item data to the card acquirer on a daily basis.
The PosPay Client is capable of handling Loyalty cards as part of either a card payment flow or as a separate transaction triggered by the POS Application (to be used if customer pays with cash).
Additionally, it has the capability to handle value code entry through the PIN-pad, using this as payment method instead of i.e. credit cards.
PosPay Client overview
This chapter describes some of the internals of PosPay Client and has been added for informational purposes only.
General
The EMV standard defines the interaction at the physical, electrical, data and application levels between IC cards and IC card processing devices for financial transactions. Portions of the Standard are heavily based on the IC chip card interface defined in ISO 7816.
The PIN-pad is EMV-compliant and supplied by PayEX. Below is an overview of internal communication within the till.
COM TCP/IP POS Application PosPay Client
Compared to previous versions, more of the business logic for handling cards and payment transactions is located within the PIN-pad and its accompanying software. It also transfers financial transaction data to PosPay Server using a transaction protocol based on international standards (ISO). Contact PayEx for more information. Any additional transaction data will be transferred using the PPP protocol directly from PosPay Client to PosPay Server (Note! Not mandatory). This is shown in the following figure.
POS Application PosPay Client PosPay Server ISO Receiver PPP Receiver ISO PPP


Dataflow example
The figure below depicts a normal purchase transaction. Only a general overview is provided.
Timeout/deadlock handling
The PosPay Client comes with additional fail-safe handling of timeout/deadlock events. When a request is received from POS Application, a timer is started. If the request is finished before the timeout limit is reached, no further action is necessary and the controller goes back to being idle.
If the timeout limit is reached, the controller will first inform the POS Application that a timeout has occurred before attempting to resolve the deadlock. Receipt data will be made available as soon as the timeout/deadlock has been resolved. The default timeout value is set to two minutes.
Main flow of integration
We offer two different ways of HTTP connections, Streaming and Polling. We will recommend to use Streaming.
Streaming:
At the first request we respond with the http header, and the connection is kept open. The PosPay Client will continuously send all events back in the response body when they occur. This technique is, among others, used by Twitter.
Polling:
Continuously sending new http requests listening for events. A response is sent regardless if there is an new event or not.
The main flow of all transactions:
We receive a HTTP/JSON request and the transaction starts. The transaction is performed asynchronously with the initializer, and run through the terminal (card, pin verification).
When the authorization is complete you will receive an ‘complete event’, approved/declined. After the ‘complete event’ you shall send a HTTP/JSON request to receive the receipt(s).
Example
ECR
PosPay Client
Terminal
Initiate preauthorization
→
←
Accept transaction
Initiate towards terminal
→
←
Send event 'insert card'
←
Display Insert card
←
Send event 'Enter pin'
←
Read card, display enter pin
←
Send event 'Communicating with host'
←
Validate Pin, send transaction to host
.....
←
Send complete event 'Approved'
←
Receive transaction from host, return approve data
Get transaction result
→
←
Return transaction result
HTTP/JSON API overview
Integration towards the PosPay Client is done with http requests, and the data sent back and forth is formatted in JSON (http://json.org/) format in the request and response bodies. All request bodies is to be encoded with UTF-8.
HTTP headers
In addition to ordinary headers requests to the PosPay Client shall always include the following headers:
     Content-Type: application/json; charset=utf-8
     Date: <request date/time ISO-8601>
And responses from the PosPay Client includes:
     Date: <response date/time ISO-8601>
     Content-Type: application/json; charset=utf-8
     Expires: 0
     Connection: close
JSON format
All string values in JSON objects that has a text that include line shifts, the line shifts should be replaced by the characters ‘\r\n’. Example:
{ “textIncludingLineshift”: “This text has a line shift here.\r\n\And next line continues here.” }
All dates and times should be a string formatted according to ISO-8601. Example:
     2012-10-08T13:56+01:00     
{ “dateAndTime”: “2012-10-08T13:56+01:00” }
Error handling
If there is any error in handling the request PosPay Client will respond with an appropriate HTTP response code, and also a descriptive error message in the response body.
Error
Object name
Description
Value format
Mandatory
error
A short error text/code for the type of error
String
X
message
A more descriptive message explaining the error situation.
String
Example of an error message
{
"error": "NotSupported",
"message": "/pospayclient/api/1.2/Purchase is no longer supported. Please use newer version."
}
{
"error": "NotSupported",
"message": "/pospayclient/api/1.2/Purchase is no longer supported. Please use newer version."
}
General errors for any kind of request
Error
Condition
HTTP response code
NotSupported
Indicates this version of the service is no longer available.
301 Moved Permanently
ServiceRemoved     
Indicates this service is no longer available. Description might indicate what other service to use instead
410 Gone
NoSuchVersion
Indicates the version specified does not exist
404 Not Found
NotImplemented
Indicates the service called upon does not exist
501 Not implemented
MethodNotAllowed
Method used is not allowed for this service. For instance use of GET for a service expecting a POST
405 Method Not Allowed
MalformedData
JSON data provided is malformed
400 Bad Request
IllegalRequest
Error in headers, body applied for a GET request, incorrect content length specified etc
400 Bad Request
InternalError
We encountered an internal error. Please try again.
500 Internal Server Error
MissingRequestBodyError
When request that should have provided JSON data has an empty body
400 Bad Request
OperationAborted
Returned if another service is running, preventing this call to be accepted.
409 Conflict
NotAvailable
If a service is unable to respond because it is not active or configured to be enabled
403 Forbidden
Specific errors for specific kinds of request(s)
Error
Condition
HTTP response code
Request
NoEvent
If no event is ready to be delivered this error is returned
404 Not found
Get event
NoTransactionResult     
If there is no transaction result data to be returned. E.g. no transaction is processed yet, or transaction has no result data to return (e.g. Ping etc)other service to use instead
404 Not found
Get transaction result
CannotCancel
If the service knows beforehand it cannot be cancelled, or if cancelled was called in Open Ped state.
409 Conflict
Cancel
PedNotOpened
PosPay client has no running open ped service.
409 Conflict
PedAlreadyOpened     
If the open ped is already opened
500 Internal Error
NoInputDialogAvailable
The ECR requests a input dialog when the PosPay client has no one available. E.g. the PosPay client has not sent a 4002 event
404 Not found
Get input dialog
NotExpectingInputResponse
PosPay client has no running input dialog it is expecting a response for
409 Conflict
Send input
NoInputDialogRunning
PosPay client has no running input dialog to cancel
409 Conflict
Cancel input
Example of a HTTP error response:
HTTP/1.1 301 Moved Permanantly
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 133
Connection: close
{
"error": "NotSupported",
"message": "/pospayclient/api/1.2/Purchase is no longer supported. Please use newer version."
}
HTTP/1.1 301 Moved Permanantly
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 133
Connection: close
{
"error": "NotSupported",
"message": "/pospayclient/api/1.2/Purchase is no longer supported. Please use newer version."
}
Service uri and versioning
The PosPay Client API will be versioned separately from the PosPay Client application implementing this API. This in order to more clearly state the specific versioning changes that will affect integrated products. Changes in the PosPay Client application that will affect the API services outcome might affect API version. All services in the PosPay Client API will have the same version number.
A service in the PosPay Client API is accessible through this URI           /pospayclient/api/<verison>/<service>
Or if <version> is omitted, latest’s version implementation is referenced           /pospayclient/api/<service>
Version numbering in the API consist of two parts, <major.minor>. Example 2.13. It is possible to only reference the major part in the URI. It would then refer to the latest minor version for that major. As an example – if we have these versions:
     /pospayclient/api/1.0/<service>
     /pospayclient/api/1.1/<service>
     /pospayclient/api/1.2/<service>
     /pospayclient/api/2.0/<service>
     /pospayclient/api/2.1/<service>
    
Then the following will refer to the exact same service version implementation:           /pospayclient/api/1/<service>
     /pospayclient/api/1.2/<service>
And these too:
     /pospayclient/api/<service>
     /pospayclient/api/2/<service>
     /pospayclient/api/2.1/<service>                    
Major version part is changed when changes will affect existing integrations, and potentially requires integrators to adapt their integration to the new version. Such as:
Minor version part is changed when changes will not affect existing integrations. Such as:
Event handling and callback
HTTP streaming
Since HTTP is a one way communication protocol with synchronously responses, it is hard for the server side (in this case PosPay Client) of the request to notify/callback to the client side (in this case the ECR). This is needed for us in order to update the ECR with information etc during transaction flow.
One way to solve this is by using the HTTP streaming technique.
This is done by the client invoking a GET request on an URL and never closing the connection. E.g. continuing to read a response body from the server side as the server side asynchronously continues to add more and more data to the response body.
The HTTP response will have the HTTP header Transfer-Encoding: chunked in order to specify that this is an persistent http connection for dynamically generated content. (http://en.wikipedia.org/wiki/Chunked_transfer_encoding)
See here for an explanation from Twitter how this works: https://dev.twitter.com/docs/streaming-apis.
In order to start a stream send a HTTP GET request to the event stream url /pospayclient/api/eventstream/add
Defaullt TCP/IP port for the HTTP streaming is 8090, and might be configured with the configuration parameter pospay.client.api.event.port.
If no new event has occurred within 30 seconds since the last event was dispatched, an empty heartbeat will be sent. This will be an empty JSON object.
Example:
GET /pospayclient/api/eventstream/add/ HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-10-08T12:56:02+01:00
Content-Length: 0
Connection: keep-alive
GET /pospayclient/api/eventstream/add/ HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-10-08T12:56:02+01:00
Content-Length: 0
Connection: keep-alive
Every event sent back in the HTTP body response for this request will be in the format of <event object byte size><lineshift (\r\n)><event object><lineshift (\r\n)>. The empty heartbeat will also have a size etc. See example below.
Event
Object name
Description
Value format
Mandatory
eventId
This is an id representing the event
Numeric
X
eventDescription
A more descriptive message explaining the error situation. This message is localized, and locale can be configured with the configuration parameter pospay.client.locale=<ISO 639>_<ISO_3166>. Default is ‘no_NO’
String
X
eventType
Categorization of event type.
<ERROR|COMPLETE|INFO|RESPONSE >
String
X
Example of event stream:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: 2012-10-08T12:56:02+01:00
Connection: keep-alive
2
{}
77
{"eventDescription":"VENTER PÅ KODE+KLAR/OK","eventId":3,"eventType":"INFO"}
76
{"eventDescription":"AUTORISASJON PÅGÅR","eventId":118,"eventType":"INFO"}
<… And more and more events will be added to the open socket as time passes…>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: 2012-10-08T12:56:02+01:00
Connection: keep-alive
2
{}
77
{"eventDescription":"VENTER PÅ KODE+KLAR/OK","eventId":3,"eventType":"INFO"}
76
{"eventDescription":"AUTORISASJON PÅGÅR","eventId":118,"eventType":"INFO"}
<… And more and more events will be added to the open socket as time passes…>
Polling alternative
There is a possibility for the ECR to receive events in a polling fashion instead of the recommended streaming alternative described above. We do provide a service to get events on request , but will either create a high amount of requests, or an actual latency between the moment an event arises in the PosPay Client and the ECR actually receives this.
In order to alleviate this latency problem we have a built in functionality to check for an available event to return on a event request multiple times internally in small intervals before returning the final response to the request.
This is how it works. ECR calls get event service, and our service handler will check if any events is available to dispatch to ECR. If so, the event is returned at once as a response to the request. If not, this handler will wait a short amount of time, and check if an event has arrived since it last checked. When an event then becomes available for dispatching, the service returns the event. If no event becomes available for dispatching within 10 times of checking, the service will return a NoEvent response. There is a configuration parameter pospay.client.eventHandler.timeout controlling how long time this service handler should take before returning an event. This parameter is default 10 (seconds), and this implies it will check every 1 second if any event is available to dispatch, and if no event becomes available, it will return a NoEvent 10 seconds after ECR has sent the get event request. Please see below for examples of how this flow might behave.
In order to use this polling alternative the configuration parameter pospay.client.localeventhandler.enable has to be set to ‘true’, default is ‘false’.
pospay.client.eventHandler.timeout=10
pospay.client.localeventhandler.enable=false
Polling events flow example:
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
2,2s
Event queued
Event arises, placed on queue
3s
Check queue, get event
→
Event queued
3s
Event
←
Return event
Empty
3,1s
Call getEvent
→
Empty
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
2,2s
Event queued
Event arises, placed on queue
3s
Check queue, get event
→
Event queued
3s
Event
←
Return event
Empty
3,1s
Call getEvent
→
Empty
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
….
9s
Check queue, no event
→
Empty
10s
No Event
←
Return NoEvent
→
Empty
10,1s
Call getEvent
→
Empty
11,1s
Check queue, no event
→
Empty
…
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
….
9s
Check queue, no event
→
Empty
10s
No Event
←
Return NoEvent
→
Empty
10,1s
Call getEvent
→
Empty
11,1s
Check queue, no event
→
Empty
…
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
2,2s
Event queued
Event arises, place on queue
2,3s
2 Events queued
Event arises, place on queue
2,7s
3 Events queued
Event arises, place on queue
3s
Check queue, get event
→
3 Events queued
3s
Event
←
Return event
2 Events queued
3,1s
Call getEvent
→
2 Events queued
3,1s
Check queue, get event
→
2 Events queued
3,1s
Event
←
Return event
1 Event queued
3,2s
Call getEvent
→
1 Event queued
3,2s
Check queue, get event
→
1 Events queued
3,2s
Event
←
Return event
Empty
3,3s
Call getEvent
→
Empty
Time
ECR
EventPollingHandler 
PosPayClient EventQueue
Backbone
0s
Call getEvent
→
Empty
0s
Check queue, no event
→
Empty
1s
Check queue, no event
→
Empty
2s
Check queue, no event
→
Empty
2,2s
Event queued
Event arises, place on queue
2,3s
2 Events queued
Event arises, place on queue
2,7s
3 Events queued
Event arises, place on queue
3s
Check queue, get event
→
3 Events queued
3s
Event
←
Return event
2 Events queued
3,1s
Call getEvent
→
2 Events queued
3,1s
Check queue, get event
→
2 Events queued
3,1s
Event
←
Return event
1 Event queued
3,2s
Call getEvent
→
1 Event queued
3,2s
Check queue, get event
→
1 Events queued
3,2s
Event
←
Return event
Empty
3,3s
Call getEvent
→
Empty
List of events
Events are divided into different event types: Error, Complete, Info, UI and Response. See below for a complete list of all the events.
List of events
ERROR
Id range: 3000 – 3999.
Error events is used to describe system failure. E.g. Could be a configuration failure or host communication failure.
Event ID
Message
Description
3003
UNKNOWN_ISSUER
The card is not registered in the bin table
3006
CARD_FORBIDDEN
Invalid service for the card
3007
LUHN_CHECK_FAILED
Incorrect card number
3021
INTERNAL_ERROR
Technical error
3024
PINPAD_ERROR
Terminal error
3025
COMMUNICATION_ERROR
Error in communication with the PosPay client or PosPay server
3027
UNKNOWN_SERVER_ACQUIRER_RESPONSE
Transaction rejected
3028
PING_FAILED
PosPay server ping failed
3998
TECHNICHAL_REVERSAL
Transaction reversed, the customer is not charged
COMPLETE
Id range: 1000 – 1999
1000 – 1499: Complete events for transactions rejected by host. Mapped from the host response code. E.g: RC=58 “Ugyldig tjeneste for kortet”, mapped to Event 1058
1500 – 1699: Complete events for transactions rejected by PosPay Client or the terminal.
1700 – 1999: Complete events for approved transactions.
Event ID
Message
Description
1510
CANCELLED
Cancelled
1511
REJECTED
Rejected
1512
UNKNOWN_SERVER_RESPONSE
Rejected by card issuer
1514
CARD_EXPIRED
Card expired
1515
SERVICE_NOT_ENABLED
Invalid card service
1516
OFFLINE_NOT_ENABLED
Card is not enabled for offline transactions
1518
OFFLINE_LIMIT_EXCEEDED
The card’s offline limit is exceeded
1523
INVALID_AUTHORIZATION_CODE
Invalid authorization code
1524
WRONG_PIN_NO_RETRY
Wrong pin, no more tries
1525
CARD_ERROR
Card error
1527
DUPLICATE_TRANSACTION
Duplicate transaction for this card
1528
WRONG_CARD
Wrong card
1539
AMOUNT_LIMIT_EXCEEDED
The card’s amount limit is exceeded
1540
CASHBACK_LIMIT_EXCEEDED
The card’s cash back limit is exceeded
1541
CASHBACK_NOT_ALLOWED
Cash back not allowed for the card
1542
TIMEOUT_ERROR
Transaction failed due to time out
1543
REJECTED_REVERSAL
Reversal not allowed at this point
1544
MANUAL_ENTRY_NOT_ALLOWED
Manual card entry is not allowed
1549
FAILED_PROCESS_CARDDATA
Failed to process card data
1550
FALLBACK_FAILED
Fallback failed
1551
DECLINED_USE_CHIP
Mag stripe declined, use chip
1552
REJECTED_NO_PREVIOUS_TX_FOUND
Rejected, no previous transactions is found
1553
UNKNOWN_CARD
Unknown card
1561
TECHNICHAL_ERROR
Technical error
1569
ONLINE_PIN_REJECTED_OFFLINE_PLEASE_RETRY
Online pin rejected offline
1700
APPROVED
Approved
1701
APPROVED_ONLINE_WITH_SIGNATURE
Approved with signature
1702
APPROVED_ELECTRONIC_OFFLINE
Approved with signature
1703
APPROVED_ELECTRONIC_OFFLINE_HOURS_EXCEEDED
Approved with signature
1704
APPROVED_MANUAL_OFFLINE
Approved with signature
1705
APPROVED_MANUAL_OFFLINE_HOURS_EXCEEDED
Approved with signature
1706
APPROVED_ONLINE_WITH_ID
Approved with id
1707
APPROVED_ONLINE_WITH_ID_AND_SIGNATURE
Approved with signature and id
1710
APPROVED_REVERSAL
Approved reversal
1711
APPROVED_ELECTRONIC_OFFLINE_WITHOUT_SIGNATURE
Approved
1712
APPROVED_NO_CVM
Approved
1902
APPROVED_CARD_INFO
Approved card info
1905
APPROVED_PING
PosPay server ping ok
INFO
Id range: 0 – 999
Provide information during the transaction. E.g. The terminal waiting for card, host communication, etc.
Event ID
Message
Description
1
WAIT_CARD
Wait for customer to insert card
3
WAIT_PIN_AND_VERIFY
Wait for customer to enter pin and ok
4
WAIT_RESPONSE
Waiting for server response
6
WAIT_VERIFY
Wait for customer to verify
7
WRONG_PIN
Wrong pin entered
8
CONNECTING
ECR connecting to terminal
9
USE_CHIP_CARD
Use chip
10
USE_MAGNETIC_STRIPE_CARD
Use mag stripe
11
REMOVE_CARD
Remove card
14
WAIT_2ND_CARD
Wait for customer to insert 2nd card
15
WAIT_USER_INPUT_ON_PINPAD
Wait for customers user input
17
LOYALTY_CARD_READ
Loyalty card read
19
WAIT_TOTAL_AMOUNT_ENTRY
Wait for customer to enter total amount
23
CANCEL_NOT_ALLOWED
Cancel not allowed
24
CONNECTED
ECR connected to terminal
25
CONNECTION_FAILED
ECR connection with terminal failed
26
VOICEAUTH_CODE_REQUIRED
Voice authorization code required
27
PIN_BYPASS
Pin bypass initiated
29
PIN_BYPASS_NOT_ALLOWED
Pin bypass not allowed
118
AUTHORIZATION_IN_PROGRESS
Authorization in progress
119
POSPAY_SERVER_PING
PosPay server ping
120
TMS_UPDATE_IN_PROGRESS
Terminal update in progress
121
TMS_UPDATE_DONE
Terminal update done
122
TMS_UPDATE_FAILED
Terminal update failed
123
DATA_DUMP_IN_PROGRESS
Terminal data dump in progress
124
DATA_DUMP_DONE
Terminal data dump done
405
SEND_OFFLINE_TXN
Initiate send offline transactions
406
FLUSHING_FAILED
Flushing offline transactions failed
407
FLUSHING_ENDED
Flushing offline transactions is ended
408
ALL_FLUSHING_COMPLETE
All offline transactions is sent
550
PED_OPENED
Open ped activated (pin before amount)
555
AWAITING_TOTALAMOUNT_TRANSACTION
Wait for total amount
560
PED_CLOSED
Open ped deactivated
705
CARD_REMOVED
Card removed
706
UNKNOWN_CARD_NUMBER
Card number not recognized by terminal
753
SENDING_TRX_OFFLINE
Sending offline transactions
830
SEE_PHONE
Used for contactless transactions, when the transaction must be authorized with the phone application
831
CARD_NOT_SUPPORTED
Card is not supported
999
NO_EVENT
No event
RESPONSE
Id range: 4000 – 4999
Events that control the exchange of information with the ECR during a transaction. E.g. The input dialog.
Event ID
Message
Description
4000
RECEIPT_RESPONSE
Receipt response
4001
TRANSACTION_DATA_RESPONSE
Transaction data response
4002
INPUT_REQUEST_RESPONSE
Input request response
4003
CANCEL_INPUT_REQUEST
Cancel input request
4004
DATA_REQUEST_RESPONSE
Data request response
4006
ITEMS_VALIDATED_RESPONSE
Items validated response
Special events
Special Events
Event id
Event text
Description
1902
APPROVED CARD INFO
When requesting Card Info, the ECR will receive event 1902. When it’s received, Card Info Response is to be called to get the requested card data: /pospayclient/api/getCardInfoResponse
4000
RECEIPT RESPONSE
ECR receive this event when it is needed to print a receipt during a transaction, e.g. signature verification where the signature must be confirmed by the cashier prior to completion of the transaction
Call get transaction result:
/pospayclient/api/transactionResult
4002
INPUT REQUEST RESPONSE
ECR receive this event whenever an input dialog is required. Call get input dialog to start the input dialog:
/pospayclient/api/inputDialog
The dialogs which can be triggered is:
Voice authorization
Verify signature
Pin bypass
Input dialogs
Input dialogs are used in a number of situations where information to the POS Application operator is required, and where data from the operator may be required in order to complete the payment transaction.
Some of the input dialogs to be expected:
Signature verification: The operator shall approve / decline the ongoing transaction based on the signature and ID given by the customer.
Voice authorization: The operator shall call the given phone number and input the data given by the acquirer in order to complete the transaction.
Pin bypass: The operator may force signature verification instead of Pin verification.
When a input dialog is required, the PosPay Client sends a ‘4002 – Input request’ event, the ECR shall call Get Input dialog service to initiate the input dialog. The ECR will then receive a dialog description of what the PosPay Client expects data for. Most of these dialogs is intended for dialog display to the operator. For instance a dialog where the cashier is intended to confirm signature verification etc. If a dialog is optional (indicated by the ‘optional’ parameter in the inputDialog, the ECR might cancel the dialog or provide a cancel button to the operator. If a dialog is to be cancelled like this, call cancel input service.
If the PosPay client sends a ‘4003 – Cancel input request’ the ECR application is instructed to close/end any running dialog windows towards the cashier, and should not provide an answer to the input request. This might happen if the transaction is cancelled/terminated from terminal etc during the transaction at the time PosPay Client is awaiting an input dialog response.
The ECR is to call send input service in order to provide the data requested in the input dialog.
Example of input dialogs
Manual authorization
When the operator is required to call the Bank/Acquirer in order to obtain an manual authorization code to provide with a transaction the PosPay Client will request this with a input dialog request. This dialog is optional, and if the dialog is cancelled, the entire transaction will be cancelled.
Input dialog from PosPay Client
{
     "dialogId": "VOICE_AUTH",
     "dialogText": "Ring 810 10 001 for autorisasjon av kortnr(se kundens kort) Brukersted: 123123",
     "optional": "true",
     "textInputs": [
          {
               "inputId": "InputId",
               "text": "Tast inn autorisasjonskode",
               "type": "ALPHA_NUMERIC”,
               "minLength": 6,
               "maxLength": 6               
          }
     ]
}
{
     "dialogId": "VOICE_AUTH",
     "dialogText": "Ring 810 10 001 for autorisasjon av kortnr(se kundens kort) Brukersted: 123123",
     "optional": "true",
     "textInputs": [
          {
               "inputId": "InputId",
               "text": "Tast inn autorisasjonskode",
               "type": "ALPHA_NUMERIC”,
               "minLength": 6,
               "maxLength": 6               
          }
     ]
}
Input response in sendInput from ECR
{
     "dialogId": "VOICE_AUTH",
     "inputResponses": [
          {
               "intputId": "InputId",
               "value": "123456"
          }
     ]
}
{
     "dialogId": "VOICE_AUTH",
     "inputResponses": [
          {
               "intputId": "InputId",
               "value": "123456"
          }
     ]
}
Verify signature
If PosPay client is configured to ask for signature verification confirmation during signature approved transactions, this input dialog is dispatched.
Input dialog from PosPay Client
{
     "dialogId": "VERIFY_SIGN",
     "dialogText": " Bekreft signatur ",
     "optional": "false",
     " selectionList ": {
"multipleSelction": "false",
"selectionItems" : [
               {
                    "inputId": "ChoiceId1",
                    "text": "Ikke godkjent",
                    "returnValue": "false"
               },
               {
                    "inputId": "ChoiceId0",
                    "text": "Godkjent",
                    "returnValue": "true"
               }
          ]
}
}
{
     "dialogId": "VERIFY_SIGN",
     "dialogText": " Bekreft signatur ",
     "optional": "false",
     " selectionList ": {
"multipleSelction": "false",
"selectionItems" : [
               {
                    "inputId": "ChoiceId1",
                    "text": "Ikke godkjent",
                    "returnValue": "false"
               },
               {
                    "inputId": "ChoiceId0",
                    "text": "Godkjent",
                    "returnValue": "true"
               }
          ]
}
}
Input response in sendInput from ECR
{
     "dialogId": " VERIFY_SIGN",
     "inputResponses": [
          {
               "intputId": " ChoiceId0",
               "value": "true"
          }
     ]
}
{
     "dialogId": " VERIFY_SIGN",
     "inputResponses": [
          {
               "intputId": " ChoiceId0",
               "value": "true"
          }
     ]
}
PosPay Client service requests
Get Event Request
If event polling is performed instead of HTTP streaming, the configuration parameter pospay.client.localeventhandler.enable has to be set to ‘true’, default is ‘false’.
Please see chapter about          Polling alternative for more information.
Request Method
GET
Request URL
/pospayclient/api/event
Request object
None
Response object
Event
Object name
Description
Value format
Mandatory
EventId
This is an id representing the event
Numeric
X
eventDescription
A more descriptive message explaining the error situation. This message is localized, and locale can be configured with the configuration parameter pospay.client.locale=<ISO _639>_<ISO_3166>. Default is ‘no_NO’
String
X
eventType
Categorization of event type.
<ERROR|COMPLETE|INFO|RESPONSE >
String
X
Example
{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
Specific error responses
Error
Condition
HTTP response code
Request
NoEvent
If no event is ready to be delivered this error is returned
404 Not found
Get event
Examples
Request
GET /pospayclient/api/ event HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-10-08T12:57:14+01:00
Content-Length: 0
GET /pospayclient/api/ event HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-10-08T12:57:14+01:00
Content-Length: 0
Response
HTTP/1.1 200 OK
Date: 2012-11-08T13:57:14+01:00
Content-Length: 99
Expires: 0
Connection: close
{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
HTTP/1.1 200 OK
Date: 2012-11-08T13:57:14+01:00
Content-Length: 99
Expires: 0
Connection: close
{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}

 Purchase
Use this service to perform an ordinary purchase transaction.
Request Method
POST
Request URL
/pospayclient/api/purchase
Request object
Purchase
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
cashbackAmount
If this is a payment including cash back, this amount represents the cash back amount part of the total amount above.
I.e. if merchandize cost 20,00 NOK and cardholder wants 100,00 NOK as cashback, amount above should be ‘12000’, and this filed should be ‘10000’.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
voiceAuthCode
If authorization code has already been collected by phone with the bank, this might be delivered with the transaction in this field.
String
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String
vatAmount
If acquirer expects vat amount specification with the transaction this amount must be provided. This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
pan
This is a reference id used as PAN or an actual pan from a PCI insensitive card (gift card etc) delivered from the ECR, and used in the transaction instead of reading a physical card in the terminal.
This is only used in special cases.
String
recurring
The payment is a recurring payment.
Boolean
Example
{
"posReference": "000012000522",
"amount": 12000,
"cashbackAmount": 100000
}
{
"posReference": "000012000522",
"amount": 12000,
"cashbackAmount": 100000
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Examples
Request
POST /pospayclient/api/1.0/purchase HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 92
{
"posReference": "000012000522",
"amount": 12000,
"cashbackAmount": 100000
}
POST /pospayclient/api/1.0/purchase HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 92
{
"posReference": "000012000522",
"amount": 12000,
"cashbackAmount": 100000
}
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Refund
Use this service to perform a refund transaction. Also called ‘return of goods’.
Request Method
POST
Request URL
/pospayclient/api/refund
Request object
Refund
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
amountType
Used to specify the transaction type. If it is a regular refund, amount type = 0. The second option is price payment, amount type = 7.
Since version 4.10.0
Numeric
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String
vatAmount
If acquirer expects vat amount specification with the transaction this amount must be provided. This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
pan
This is a reference id used as PAN or an actual pan from a PCI insensitive card (gift card etc) delivered from the ECR, and used in the transaction instead of reading a physical card in the terminal.
This is only used in special cases.
String
Example
{
"posReference": "000012000532",
"amount": 35000,
"amountType": 0
}
{
"posReference": "000012000532",
"amount": 35000,
"amountType": 0
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/1.0/refund HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000532",
"amount": 35000
}
POST /pospayclient/api/1.0/refund HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000532",
"amount": 35000
}
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Reverse
This is to reverse the last performed transaction. This is no ordinary refund/return, but a cancellation of the last performed transaction.
Request Method
POST
Request URL
/pospayclient/api/reverse
Request object
Reverse
Object name
Description
Value format
Mandatory
posReference
Use the posReference of the last performed transaction. E.g. the one to reverse.
If the parameter pospay.client.enableReversalPosRefCheck =true the transaction is aborted if the previous transaction has another posReference.
12 characters long numeric id
String
X
amount
The amount in the original transaction being reversed. Only needed if the parameter pospay.client.enableReversalAmountCheck =true the amount provided here is verified with the amount of the previous transaction. If these differs, transaction is aborted. The parameter is default set to ‘false’.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String
Example
{
"posReference": "000012000532",
"amount": 35000
}
{
"posReference": "000012000532",
"amount": 35000
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/1.0/reverse HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000532",
"amount": 35000
}
POST /pospayclient/api/1.0/reverse HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000532",
"amount": 35000
}
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Pre Authorization
Use this service to pre authorize/reserve an amount on the cardholders account that might later be captured.
Request Method
POST
Request URL
/pospayclient/api/preAuthorization
Request object
Pre authorization
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the PayEx transaction server generates this reference.
String
voiceAuthCode
If authorization code has already been collected by phone with the bank, this might be delivered with the transaction in this field.
String
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String
vatAmount
If acquirer expects vat amount specification with the transaction this amount must be provided. This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
Example
{
"posReference": "000012000511",
"amount": 66000
}
{
"posReference": "000012000511",
"amount": 66000
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/1.0/preAuthorization HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000511",
"amount": 66000
}
POST /pospayclient/api/1.0/preAuthorization HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 60
{
"posReference": "000012000511",
"amount": 66000
}
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Adjust Pre Authorization
Use this service to change the pre authorization.
Request Method
POST
Request URL
/pospayclient/api/adjustPreAuth
Request object
Pre authorization adjust request
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
Arn
Authorization Reference Number.
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String
Response object
None
Examples
Request
POST /pospayclient/api/adjustPreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-11T10:16:08.128+02:00
Connection: close
Content-Length: 88
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference": "136689360475",
"amount": 233300,
"arn": "0000707307",
"multiMerchantId": 996
}
POST /pospayclient/api/adjustPreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-11T10:16:08.128+02:00
Connection: close
Content-Length: 88
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference": "136689360475",
"amount": 233300,
"arn": "0000707307",
"multiMerchantId": 996
}
Response

HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Specific error responses
None
For general error responses please see:          General errors for any kind of request



Close Pre Authorization
Use this service to close pre authorizations.
Request Method
POST
Request URL
/pospayclient/api/closePreAuth
Request object
Close Pre Authorization
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the Payex transaction server generates this reference.
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String

Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.


Specific error responses
None.
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/closePreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 97
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":20000,
"arn":"0000707319",
"multiMerchantId":996
}
POST /pospayclient/api/closePreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 97
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":20000,
"arn":"0000707319",
"multiMerchantId":996
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Delete Pre Authorization
Use this service to delete pre authorizations.
Request Method
POST
Request URL
/pospayclient/api/deletePreAuth
Request object
Close Pre Authorization
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the Payex transaction server generates this reference.
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String

Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Examples
Request
POST /pospayclient/api/deletePreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-05-03T10:54:10.990+02:00
Connection: close
Content-Length: 72
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136757125098",
"arn":"0000707334",
"multiMerchantId":996
}
POST /pospayclient/api/deletePreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-05-03T10:54:10.990+02:00
Connection: close
Content-Length: 72
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136757125098",
"arn":"0000707334",
"multiMerchantId":996
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Get Pre Authorization
Use this service to get pre authorizations. Fill in the authorization number for the wanted pre auth and initiate the service. When ECR receive event 1904, /pospayclient/api/getPreAuthResponse must be called.
Request Method
POST
Request URL
/pospayclient/api/getPreAuth
Request object
GetPreAuth
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
Arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the Payex transaction server generates this reference.
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
X
Example
{
"posReference": "137725660150",
"arn": "0000707780",
"multiMerchantId": 996
}
{
"posReference": "137725660150",
"arn": "0000707780",
"multiMerchantId": 996
}
Response object
None
Specific error responses
None
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/getPreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-08-23T13:16:41.512+02:00
Connection: close
Content-Length: 72
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
POST /pospayclient/api/getPreAuth HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-08-23T13:16:41.512+02:00
Connection: close
Content-Length: 72
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Get Pre Authorization Response
Use this service to get pre auth response from get pre authservice.
Request Method
GET
Response URL
/pospayclient/api/getPreAuthResponse
Response object
GetPreAuthResponse
Object name
Description
Value format
Mandatory
authorizationCode
The authorization reference (P-38 Authorization Id response code) for this transaction.
This is an 6 character alphanumeric code. If offline authorized by terminal or STP (stand-in transaction processor) this value will start with an 'L' in first character. Rest (or otherwise all) of the characters numeric, left padded with 0's.
String
preAuthorizationId
Id for the pre authorization to get
String
hostResponseCode
If online transaction this field holds the response code from the transaction server.
String
responseCodeText
If host response code exists, this field holds the language dependant description
for this response code. Configuration parameter pospay.client.locale sets the language
String
currencyString
Currency code for the transaction. Three character ISO-4217 code.
String
amount
The original amount for the transaction from the ECR, not including surcharge, tip etc.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
totalAmount
The total amount debited/credited the account, including any added surcharge, tip etc.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
tipAmount
The tip amount for the transaction. If tip has been enabled in the terminal, the terminal gives the cardholder the option to add tips to the transaction.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
cardIssuerNumber
Number referencing the card issuer of the card used. 8 digits     
String
cardNumber
If this is a PCI sensitive card, this number is screened. If it is an unsensitive card, the full card number is delivered
String
cardNumberScreened
Screened representation of cardNumber no matter if it is PCI sensitive or not.
String
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
String
terminalId
Terminal id for the transaction. Up to 8 digits
String
transactionTime     
Local transaction time in ISO-8601 format
String
vatOnReceipt
Print VAT information on receipt
Numeric

Specific error responses
Error
Condition
HTTP response code
Request
NoResponse
If no response is delivered this error is returned
404 Not found
Get preAuth
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/getPreAuthResponse HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-08-26T10:02:53.176+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
GET /pospayclient/api/getPreAuthResponse HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-08-26T10:02:53.176+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
Response
HTTP/1.1 202 Accepted
Content-Length: 383
Connection: close
Server: Jetty(7.4.5.v20110725)
{
“authorizationCode":"L00244",
"preAuthorizationId":"0000707795",
"hostResponseCode":"0",
"responseCodeText":"OK",
"currencyString":"578",
"amount":55500,
"totalAmount":55500,
"tipAmount":0,
"cardIssuerNumber":"20",
"cardNumber":"401550******1736",
"cardNumberScreened":"401550******1736",
"multiMerchantId":"996",
"terminalId":"6",
"transactionTime":"2013-08-26T10:02:44+02:00",
"vatOnReceipt":1
}
HTTP/1.1 202 Accepted
Content-Length: 383
Connection: close
Server: Jetty(7.4.5.v20110725)
{
“authorizationCode":"L00244",
"preAuthorizationId":"0000707795",
"hostResponseCode":"0",
"responseCodeText":"OK",
"currencyString":"578",
"amount":55500,
"totalAmount":55500,
"tipAmount":0,
"cardIssuerNumber":"20",
"cardNumber":"401550******1736",
"cardNumberScreened":"401550******1736",
"multiMerchantId":"996",
"terminalId":"6",
"transactionTime":"2013-08-26T10:02:44+02:00",
"vatOnReceipt":1
}

Late Debit
Use this service to perform late debit of an closed pre authorization.
Request Method
POST
Request URL
/pospayclient/api/lateDebit
Request object
Late Debit
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the Payex transaction server generates this reference.
String
cardToken
Card token can be used as a replacement for ARN. The card token is created by the Payex transaction server during a pre authorization.
String
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String

Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Examples
Request
POST /pospayclient/api/lateDebit HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 93
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":23000,
"arn":"0000784123",
"multiMerchantId":996
}
POST /pospayclient/api/lateDebit HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 93
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":23000,
"arn":"0000784123",
"multiMerchantId":996
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Late Credit
Use this service to perform late credit of a closed pre authorization.
Request Method
POST
Request URL
/pospayclient/api/lateCredit
Request object
Late Credit
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
arn
Authorization Reference Number.
Only to be provided if merchant is intended to create the reference number themselves. Standard is that the Payex transaction server generates this reference.
String
cardToken
Card token can be used as a replacement for ARN. The card token is created by the Payex transaction server during a pre authorization.
String
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
orderId
An order id created by the ECR that will follow the transaction all the way to the acquirer in P-62.
String

Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Examples
Request
POST /pospayclient/api/lateCredit HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 93
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":23000,
"arn":"0000784123",
"multiMerchantId":996
}
POST /pospayclient/api/lateCredit HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-29T13:58:31.907+02:00
Connection: close
Content-Length: 93
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136723671190",
"amount":23000,
"arn":"0000784123",
"multiMerchantId":996
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Specific error responses
None.
For general error responses please see:          General errors for any kind of request

Get Transaction Result
When a transaction has completed there has been sent a COMPLETE event to the ECR. After this the ECR should call this service in order to get all information about the transaction, including receipt part to print on the receipt
Request Method
GET
Request URL
/pospayclient/api/transactionResult
Request object
None
Response object
Transaction result
Object name
Description
Value format
Mandatory
merchantId
Merchant id for the transaction. Up to 8 digits
Numeric
X
terminalId
Terminal id for the transaction. Up to 8 digits
Numeric
X
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
originalRequestType
The transaction request type this receipt is for.
< PURCHASE | PURCHASE WITH CASHBACK | RETURN | REVERSAL | PRE AUTHORIZATION | DEPOSIT | WITHDRAWAL | BALANCE | ACTIVATION >
String
X
stan
'System Trace Audit Number' generated by terminal that follows the transaction. (P-11)
Numeric
transactionTime     
Local transaction time in ISO-8601 format
String
X
operatorId
Operator/cashier id. Alphanumeric value of max 8 characters.
String
currency
Currency code for the transaction. Three character ISO-4217 code.
String
retrievalReferenceNumber
This is the unique identifier for used by the terminal which is transported all the way to the acquirer. This reference number is printed on the receipt, and is the best reference to use in dialog with the bank regarding lookup of transactions.
String
amounts
Different amounts belonging to this transaction
amounts
authInformation
Transaction authorization information
authInformation
Receipt
Preformatted receipt parts to be printed
receipt
cardInformation
Information about the card used in the transaction
cardInformation
Amounts
Object name
Description
Value format
Mandatory
originalAmount
The original amount for the transaction from the ECR, not including surcharge, tip etc.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
totalAmount
The total amount debited/credited the account, including any added surcharge, tip etc.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
cashbackAmount
Part of original amount for cashback for the transaction.                    
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
tipAmount
The tip amount for the transaction. If tip has been enabled in the terminal, the terminal gives the cardholder the option to add tips to the transaction.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
surchargeAmount
Added surcharge amount to the transaction. If surcharge is activated in the terminal it might add an amount (usually a percentage of the purchase amount) to the transaction. This handling is used for credit card transactions in Denmark.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
balanceAmount
Return of balance amount for a balance request.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
authInformation
Object name
Description
Value format
Mandatory
approved
Tells if the transaction approved.
Boolean
X
hostResponseCode
If online transaction this field holds the response code from the transaction server.
String
responseCodeText
If host response code exists, this field holds the language dependant description
for this response code. Configuration parameter pospay.client.locale sets the language
String
denialMessage
If transaction has been rejected this field might contain a explanation text for this rejection.
The language of this language dependent text is set with pospay.client.locale.
String
canceled
Indicates if transaction was cancelled.
Boolean
X
canceledMethod
Indicates how the transaction was cancelled. Was it cancelled by the cardholder/terminal     
(pull chip, cancel pressed etc), by the pospay client (duplicate control etc), by the ECR (cancel request retrieved from ECR). Mandatory if 'canceled=TRUE'.
< TERMINAL | CLIENT | ECR >
String
authorizationMethod
How this transaction was authorized.     
< ONLINE | OFFLINE | VOICE_AUTH | REFUND | FORCED_OFFLINE | NOT
_AUTHORIZED>
Not provided if transaction is declined before authorization.
String
X
entryMode
How this transaction has received its PAN. < CHIP | MAG_STRIPE | KEY_ENTRY | FALLBACK_TO_MAG_STRIPE | NFC >
String
verificationMethod
How cardholder for this transaction has been verified. (CVM - cardholder verification method)
< NO_CVM_PERFORMED | NO_CVM_REQUIRED | ONLINE_PIN | OFFLINE_PIN | SIGNATURE |
ONLINE_PIN_AND_SIGNATURE | OFFLINE_PIN_AND_SIGNATURE | CVM_FAILED >
NO_CVM_PERFORMED might be either because transaction was declined before verification, or the card might not be personalised with a CVM list. NO_CVM_REQUIRED is explicit that the card did not require any cardholder verification to be performed.
String
authorizationCode
The authorization reference (P-38 Authorization Id response code) for this transaction.
This is an 6 character alphanumeric code. If offline authorized by terminal or STP (stand-in transaction processor) this value will start with an 'L' in first character. Rest (or otherwise all) of the characters numeric, left padded with 0's.
String
arn
Authorization Reference Number.
The reference from a pre authorization that is to be used in subsequent adjust, cancel end/or complete requests.
String
sessionNumber
Session number returned from the acquirer which the transaction belongs to. Aka. host reconciliation batch session.
Numeric
authorizingEntity
Swedbank specific information indicating who actually authorized the transaction.
Also called (Card Authorisation) Responder
  • 1 - Offline authorized (approved in terminal)
  • M - Voice authorized
  • _ - If none of the above, and this is not a transaction towards Swedbank
  • [1-9] - If none of the above, the actual code returned by Swedbank host
String
X
Receipt
Object name
Description
Value format
Mandatory
customer
Preformatted ready to print terminal part of the customer receipt.
Remember all linebreaks are represented by \r\n. Format of the receipt is set with pospay.client.receiptProfile, and possibly language dependent texts is set with pospay.client.locale. Receipt texts is formatted as max 42 characters wide.
String
X
merchant
Preformatted ready to print terminal part of the customer receipt.
Remember all linebreaks are represented by \r\n. Format of the receipt is set with pospay.client.receiptProfile, and possibly language dependent texts is set with pospay.client.locale. Receipt texts is formatted as max 42 characters wide.
String


cardInformation
Object name
Description
Value format
Mandatory
cardNumber
If this is a PCI sensitive card, this number is screened. If it is an un-sensitive card, the full card number is delivered
String
X
cardNumberScreened
Screened representation of cardNumber no matter if it is PCI sensitive or not.
String
X
expireDate
If known this field contains the expire date for the card.               
Format is YYMM
String
cardProductName
For mag. stripe transactions this is the name of the card product name set in server configuration.
For example Visa, MasterCard etc. For chip card usage this is the chip application name used.
Note. this is for viewable/receipt print only, not for programmatically usage.
Only provided if card is used, and cardProductName is actually known.
(E.g. Unknown mag stripe we do not know any name for)
String
cardIssuerNumber
Number referencing the card issuer of the card used. 8 digits     
Numeric
cardIssuerName
Name of the card issuer of the card used. 16 characters
String
acquirerString
String representing the acquirer.
String
X
agreementId
Acquirer agreement id as set in Server and host configuration. If not applicable merchant id is used instead.
Numeric
X
cardOwnerID
This field returns a registered customer id with a digital receipt provider (such as dSafe)
If a customer of this digital receipt provider has registered his credit card with the provider, and the merchant has an agreement with this provider, we will return this registered card owner id for a this transaction (if registered). The ECR/merchant is then responsible for sending the receipts to the digital receipt provider for digital storage. Note this will only work for online transactions.
String
cardToken
If tokenization is enabled this is a reference to the card data used in this online transaction. This token might be later used in late debit/credit transactions or in a pre-authorization.
String
accountOption
For Swedish solution where there is a possibility to select in terminal if debit or credit account. In those cases this value will return ‘20’ or ‘30’. In all other cases this will return ‘00’.
00 – Default
20 – Debit (Konto)
30 – Credit (Kredit)
String
emvData
Data from the chip card used in the transaction.
emvData
emvData
Object name
Description
Value format
Mandatory
aid
The application identifier for the chip card used. Mandatory if this is an EMV chip transaction.
String
atc
Application transaction counter from the chip. Mandatory if this is an EMV chip transaction.
Numeric
aed
Application effective date. Date from which the application may be used.
< YYMMDD >
Mandatory if this is an EMV chip transaction.
String
psn
Pan sequence number. Identifies and differentiates cards with the same PAN.
Mandatory if this is an EMV chip transaction.
Numeric
tvr
Terminal verification result. Binary coded information describing the result of the
EMV chip verification. Mandatory if this is an EMV chip transaction.
String
tsi
Transaction status information. Binary coded information describing chip transaction status result
String
cryptogram
Chip application cryptogram. Used in transaction for chip authentication/verification.
Mandatory if this is an EMV chip transaction.
String
Example
{
     "merchantId": 20070001,
     "terminalId": 2,
     "posReference": "000012000511",
     "originalRequestType": "PRE AUTHORIZATION",
     "stan": 000212,
     "transactionTime": "2012-11-08T13:56:23+01:00",
     "currency": "NOK",
     "retrievalReferenceNumber": "200700010659",
     "amounts": {
          "originalAmount": 66000,
          "totalAmount": 66000
     },
     "authInformation": {
          "approved": true,
          "hostResponseCode": "00",
          "responseCodeText": "GODKJENT",
          "canceled": false,
          "authorizationMethod": "ONLINE",
          "entryMode": "CHIP",
          "verificationMethod": "ONLINE_PIN",
          "authorizationCode": "L01498",
          "arn": "0000767292",
          "sessionNumber": 16,
          "authorisingEntity": "_"
     },
     "receipt": {
          "customer": "BAX 20070001-2\r\nVisa ************1736\r\n2012-11-08 13:56\r\nRef:000012000511-L01498\r\nReserveringsnr:0000767292\r\nBeløp NOK 660.00\r\nTotal NOK 660.00\r\n\r\nAID: A0000000031010\r\nCG: 20D3DAF20A49ABF3\r\nTVR: 0000001800\r\n\r\nResponskode:00\r\nGODKJENT\r\n \r\nKundens kopi"
     },
     "cardInformation": {
          "cardNumber": "************1736",
          "cardNumberScreened": "************1736",
          "expireDate": "1303",
          "cardProductName": "VISA",
          "cardIssuerNumber": 3,
          "cardIssuerName": "Visa",
          "acquirerString": "BAX",
          "agreementId": 20070001,
          “accountOption”: “00”
          "emvData": {
               "aid": "A0000000031010",
               "atc": 112,
               "aed": "100403",
               "psn": 1,
               "tvr": "0000001800",
               "tsi": "E800",
               "cryptogram": "20D3DAF20A49ABF3"
          }
     }
}
{
     "merchantId": 20070001,
     "terminalId": 2,
     "posReference": "000012000511",
     "originalRequestType": "PRE AUTHORIZATION",
     "stan": 000212,
     "transactionTime": "2012-11-08T13:56:23+01:00",
     "currency": "NOK",
     "retrievalReferenceNumber": "200700010659",
     "amounts": {
          "originalAmount": 66000,
          "totalAmount": 66000
     },
     "authInformation": {
          "approved": true,
          "hostResponseCode": "00",
          "responseCodeText": "GODKJENT",
          "canceled": false,
          "authorizationMethod": "ONLINE",
          "entryMode": "CHIP",
          "verificationMethod": "ONLINE_PIN",
          "authorizationCode": "L01498",
          "arn": "0000767292",
          "sessionNumber": 16,
          "authorisingEntity": "_"
     },
     "receipt": {
          "customer": "BAX 20070001-2\r\nVisa ************1736\r\n2012-11-08 13:56\r\nRef:000012000511-L01498\r\nReserveringsnr:0000767292\r\nBeløp NOK 660.00\r\nTotal NOK 660.00\r\n\r\nAID: A0000000031010\r\nCG: 20D3DAF20A49ABF3\r\nTVR: 0000001800\r\n\r\nResponskode:00\r\nGODKJENT\r\n \r\nKundens kopi"
     },
     "cardInformation": {
          "cardNumber": "************1736",
          "cardNumberScreened": "************1736",
          "expireDate": "1303",
          "cardProductName": "VISA",
          "cardIssuerNumber": 3,
          "cardIssuerName": "Visa",
          "acquirerString": "BAX",
          "agreementId": 20070001,
          “accountOption”: “00”
          "emvData": {
               "aid": "A0000000031010",
               "atc": 112,
               "aed": "100403",
               "psn": 1,
               "tvr": "0000001800",
               "tsi": "E800",
               "cryptogram": "20D3DAF20A49ABF3"
          }
     }
}
Specific error responses
Error
Condition
HTTP response code
NoTransactionResult
If there is no transaction result data to be returned. E.g. no transaction is processed yet, or transaction has no result data to return (e.g. Ping etc)
404 Not found
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/transactionResutlt HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
GET /pospayclient/api/transactionResutlt HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
Response
HTTP/1.1 200 OK
Date: 2012-11-08T13:56:45+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 1499
Expires: 0
Connection: close
{
     "merchantId": 20070001,
     "terminalId": 2,
     "posReference": "000012000511",
     "originalRequestType": "PRE AUTHORIZATION",
     "stan": 000212,
     "transactionTime": "2012-11-08T13:56:23+01:00",
"currency": "NOK",
     "retrievalReferenceNumber": "200700010659",
     "amounts": {
          "originalAmount": 66000,
          "totalAmount": 66000
     },
     "authInformation": {
          "approved": true,
          "hostResponseCode": "00",
          "responseCodeText": "GODKJENT",
          "canceled": false,
          "authorizationMethod": "ONLINE",
          "entryMode": "CHIP",
          "verificationMethod": "ONLINE_PIN",
          "authorizationCode": "L01498",
          "arn": "0000767292",
          "sessionNumber": 16,
          "authorisingEntity": "_"
     },
     "receipt": {
          "customer": "BAX 20070001-2\r\nVisa ************1736\r\n2012-11-08 13:56\r\nRef:000012000511-L01498\r\nReserveringsnr:0000767292\r\nBeløp NOK 660.00\r\nTotal NOK 660.00\r\n\r\nAID: A0000000031010\r\nCG: 20D3DAF20A49ABF3\r\nTVR: 0000001800\r\n\r\nResponskode:00\r\nGODKJENT\r\n \r\nKundens kopi"
     },
HTTP/1.1 200 OK
Date: 2012-11-08T13:56:45+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 1499
Expires: 0
Connection: close
{
     "merchantId": 20070001,
     "terminalId": 2,
     "posReference": "000012000511",
     "originalRequestType": "PRE AUTHORIZATION",
     "stan": 000212,
     "transactionTime": "2012-11-08T13:56:23+01:00",
"currency": "NOK",
     "retrievalReferenceNumber": "200700010659",
     "amounts": {
          "originalAmount": 66000,
          "totalAmount": 66000
     },
     "authInformation": {
          "approved": true,
          "hostResponseCode": "00",
          "responseCodeText": "GODKJENT",
          "canceled": false,
          "authorizationMethod": "ONLINE",
          "entryMode": "CHIP",
          "verificationMethod": "ONLINE_PIN",
          "authorizationCode": "L01498",
          "arn": "0000767292",
          "sessionNumber": 16,
          "authorisingEntity": "_"
     },
     "receipt": {
          "customer": "BAX 20070001-2\r\nVisa ************1736\r\n2012-11-08 13:56\r\nRef:000012000511-L01498\r\nReserveringsnr:0000767292\r\nBeløp NOK 660.00\r\nTotal NOK 660.00\r\n\r\nAID: A0000000031010\r\nCG: 20D3DAF20A49ABF3\r\nTVR: 0000001800\r\n\r\nResponskode:00\r\nGODKJENT\r\n \r\nKundens kopi"
     },
(Example continues)
"cardInformation": {
          "cardNumber": "************1736",
          "cardNumberScreened": "************1736",
          "expireDate": "1303",
          "cardProductName": "VISA",
          "cardIssuerNumber": 3,
          "cardIssuerName": "Visa",
          "acquirerString": "BAX",
          "agreementId": 20070001,
          “accountOption”: “00”
          "emvData": {
               "aid": "A0000000031010",
               "atc": 112,
               "aed": "100403",
               "psn": 1,
               "tvr": "0000001800",
               "tsi": "E800",
               "cryptogram": "20D3DAF20A49ABF3"
          }
     }
}
"cardInformation": {
          "cardNumber": "************1736",
          "cardNumberScreened": "************1736",
          "expireDate": "1303",
          "cardProductName": "VISA",
          "cardIssuerNumber": 3,
          "cardIssuerName": "Visa",
          "acquirerString": "BAX",
          "agreementId": 20070001,
          “accountOption”: “00”
          "emvData": {
               "aid": "A0000000031010",
               "atc": 112,
               "aed": "100403",
               "psn": 1,
               "tvr": "0000001800",
               "tsi": "E800",
               "cryptogram": "20D3DAF20A49ABF3"
          }
     }
}
Receipt print example
Customer receipt

19/03/2013 13:47
KJØP NOK 184.50
--------
Total NOK 184.50
BankAxept PSN: 01
**** **** **** **01 98
TERM: 996-6
IA1 Loopback: 996
ATC: 00583
AID:      D5780000021010
CG:      D428FABF92A2FA41
TVR: 8000048800
STATUS: 00
AUT KODE: L34753
REF: 000000000421 AUTORISERT
POSREF: 136369726635
GODKJENT
Cancel
It is possible to try and cancel an ongoing transaction from the ECR side. After Pin entry and the transaction authorization has started it will most likely not be possible to cancel, but after starting purchase and before card holder swipes card, it’s allowed.
If cancel is invoked and there is a service running, and it accept this cancel request, and asynchronously try to cancel the service. A HTTP response 202 Accepted is then returned. If the transaction actually gets cancelled it will finish with a Cancel complete event. If it was not possible to cancel a Cancel not allowed event is sent, and the transaction will proceed. (Most often this is the response, instead of a synchron HTTP 200 response (see below). This is due to the need to keep everything in state, and any cancel effort towards the terminal has to be processed at certain stages in order not to break the order of state handling.
If there is no service running when the cancel is invoked, HTTP response 200 OK is returned.
If the PosPay client is in openPed state and cancel is invoked, then HTTP response 409 Conflict is returned. Close Ped should be used instead.
If running service is uncancellable or has reached a state where it declares itself uncancellable, HTTP response 409 Conflict is returned.
Request Method
GET
Request URL
/pospayclient/api/cancel
Request object
None.
Response object
None, unless error
Specific error responses
Error
Condition
HTTP response code
CannotCancel
If the service knows beforehand it cannot be cancelled, or if cancelled was called in Open Ped state.
409 Conflict
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/cancel HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
GET /pospayclient/api/cancel HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Open Ped
Open ped is used when a customer is to validate a card before the amount is sent to the payment terminal.
Request Method
POST
Request URL
/pospayclient/api/openPed
Request object
OpenPed request
Object name
Description
Value format
Mandatory
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
X
Response object
None, unless error
Specific error responses
Error
Condition
HTTP response code
PedAlreadyOpened
If the open ped is already opened
500 Internal Error
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/openPed HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 33
{
"multiMerchantId":996
}
GET /pospayclient/api/openPed HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 33
{
"multiMerchantId":996
}
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close


Close Ped
The ECR may call this service to cancel an ongoing open ped service.
Request Method
GET
Request URL
/pospayclient/api/closePed
Request object
None
Response object
None
Specific error responses
Error
Condition
HTTP response code
PedNotOpened
PosPay client has no running open ped service.
409 Conflict
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/closePed HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T16:45:21.584+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
GET /pospayclient/api/closePed HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T16:45:21.584+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
Response
HTTP/1.1 200 OK
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 200 OK
Connection: close
Server: Jetty(7.4.5.v20110725)
Activate
Use this service to perform an activate transaction.
Request Method
POST
Request URL
/pospayclient/api/activate
Request object
Activate
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
upc
The value cards numeric barcode.
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
pan
This is a reference id used as PAN or an actual pan from a PCI insensitive card (gift card etc) delivered from the ECR, and used in the transaction instead of reading a physical card in the terminal.
This is only used in special cases.
String
Example
{
"posReference": "000012000532”,
"upc":"01234567899",
"amount": 35000
}
{
"posReference": "000012000532”,
"upc":"01234567899",
"amount": 35000
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Verify
This is called to verify an activation.
Request Method
POST
Request URL
/pospayclient/api/verify
Request object
Verify request
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
upc
Barcode number. Up to 13 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200
Numeric
X
pan
Non sensitive card, the full card number is delivered
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
Response object
None, unless error
Specific error responses
None
For general error responses please see:          General errors for any kind of request
Examples
Request
POST /pospayclient/api/verify HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-08T14:36:47.714+02:00
Connection: close
Content-Length: 126
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136575231419",
"upc":"123456",
"amount":15800,
"pan":"6394570001000000074",
"multiMerchantId":996,
"operatorId":"666"
}
POST /pospayclient/api/verify HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-08T14:36:47.714+02:00
Connection: close
Content-Length: 126
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)
{
"posReference":"136575231419",
"upc":"123456",
"amount":15800,
"pan":"6394570001000000074",
"multiMerchantId":996,
"operatorId":"666"
}
Response
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 202 Accepted
Connection: close
Server: Jetty(7.4.5.v20110725)
Deposit
Use this service to deposit money.
Request Method
POST
Request URL
/pospayclient/api/deposit
Request object
Deposit
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
Amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
Pan
This is a reference id used as PAN or an actual pan from a PCI insensitive card (gift card etc) delivered from the ECR, and used in the transaction instead of reading a physical card in the terminal.
This is only used in special cases.
String
Example
{
"posReference": "000012000532”
"amount":1200
}
{
"posReference": "000012000532”
"amount":1200
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Balance
Use this service to check balance on a gift card.
Request Method
POST
Request URL
/pospayclient/api/balance
Request object
Balance
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
pan
This is a reference id used as PAN or an actual pan from a PCI insensitive card (gift card etc) delivered from the ECR, and used in the transaction instead of reading a physical card in the terminal.
This is only used in special cases.
String
expiryDate
Expiry date, YYMM formatted
String
Example
{
"posReference": "000012000532”
}
{
"posReference": "000012000532”
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request
Withdrawal
Use this service to withdraw money.
Request Method
POST
Request URL
/pospayclient/api/withdrawal
Request object
Withdrawal
Object name
Description
Value format
Mandatory
posReference
This is an unique id generated by the ECR for each payment transaction invoked towards the terminal. This reference is transported to the PosPay Host, and will appear in reports and selections.
12 characters long numeric id
String
X
amount
The amount to authorize.
This is in the decimal representation of the currency used. E.g. For Norwegian kroner, the amount is in øre. 12,00 NOK is represented as 1200     
Numeric
X
multiMerchantId
Multi Merchant id for the transaction. E.g. the merchant id for the multi merchant child
Numeric
operatorId
Operator/cashier id.
Alphanumeric value of max 8 characters. May be used for selection and sorting in reports
String
shiftNumber
This ECR generated number might be used in conjunction with debit/credit transactions in order to tag it to a certain cashier shift etc. This might be used in reports etc from server side. Note there is no default usage of this information at the moment.
This is a numeric value of up to 10 digits
Numeric
Example
{
"posReference": "000012000532”
"amount":1200
}
{
"posReference": "000012000532”
"amount":1200
}
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None.
For general error responses please see:          General errors for any kind of request


Card Info
Use this service to get card information. Initiate the service and insert/swipe a card in the payment terminal. When ECR receive event 1902, /pospayclient/api/getCardInfoResponse must be called.
Request Method
GET
Request URL
/pospayclient/api/cardInfo
Request object
None
Response object
None
Specific error responses
None. For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/cardInfo HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T08:39:38.178+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
GET /pospayclient/api/cardInfo HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T08:39:38.178+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
Response
HTTP/1.1 200 OK
Connection: close
Server: Jetty(7.4.5.v20110725)
HTTP/1.1 200 OK
Connection: close
Server: Jetty(7.4.5.v20110725)
Card Info Response
Use this service to get card info response from card info service.
Request Method
GET

Response URL
/pospayclient/api/getCardInfoResponse
Response object
CardInfo
Object name
Description
Value format
Mandatory
response
Card information
String
X
Specific error responses
Error
Condition
HTTP response code
Request
NoResponse
If no response is delivered this error is returned
404 Not found
Get cardInfo
For general error responses please see:          General errors for any kind of request
Examples
Request

GET /pospayclient/api/getCardInfoResponse HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T08:39:38.178+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
GET /pospayclient/api/getCardInfoResponse HTTP/1.1
Content-Type: application/json;charset=utf-8
Date: 2013-04-05T08:39:38.178+02:00
Connection: close
Host: localhost:8085
User-Agent: Apache-HttpClient/4.1.2 (java 1.5)




{
"eventDescription": "AUTORISASJON PÅGÅR",
"eventId": 118,
"eventType": "INFO"
}
Response
HTTP/1.1 202 Accepted
Content-Length: 82
Connection: close
Server: Jetty(7.4.5.v20110725)
{"response":"2:401550******1736=********************\r\nPAN:401550******1736\r\n"}
HTTP/1.1 202 Accepted
Content-Length: 82
Connection: close
Server: Jetty(7.4.5.v20110725)
{"response":"2:401550******1736=********************\r\nPAN:401550******1736\r\n"}
Get Input Dialog
The ECR is expected to call this service when receiving a ‘4002 – input request’ event. See also Input dialogs chapter.
Request Method
GET
Request URL
/pospayclient/api/inputDialog
Request object
None
Response object
Input dialog
Object name
Description
Value format
Mandatory
dialogId
A unique dialog id used to represent this particular input request dialog. This id is to be referenced in the answer from the ECR in the send input service call
String
X
dialogText
A text to display to the operator/cashier
String
optional
Indicates if this input dialog is optional, and thus possible to cancel from ECR and/or operator
Boolean
X
selectionList
List of values to select between.
selectionList
textInputs
Array of text inputs for this dialog
textInputs []
selectionList
Object name
Description
Value format
Mandatory
multipleSelection
Indicates if it is possible to select several items, or if it is a single selection possibility. E.g. should this selection list be presented with checkboxes or radio buttons to the operator.
Boolean
X
selectionItems
An array of items in the selection list
selectionItems[]
X
selectionItems[]
Object name
Description
Value format
Mandatory
inputId
A unique id representing this input value expected from the ECR in this dialog. Should be used to reference correct input value in the send input service
String
X
Text
The text to present to the operator for this selection item
String
returnValue
The value to return for this inputId if this item is selected
String
X
textInputs []
Object name
Description
Value format
Mandatory
inputId
A unique id representing this input value expected from the ECR in this dialog. Should be used to reference correct input value in the send input service
String
X
text
The text to present to the operator for this input field
String
type
Describing the expected input format. <NUMERIC | ALPHA_NUMERIC>
String
X
minLength
Minimum size of the response in characters
Numeric
maxLength
Maximum size of the response in characters
Numeric
Specific error responses
Error
Condition
HTTP response code
NoInputDialogAvailable
The ECR requests a input dialog when the PosPay client has no one available. E.g. the PosPay client has not sent a 4002 event
404 Not found
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/ inputDialog HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
GET /pospayclient/api/ inputDialog HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
Response
HTTP/1.1 200 OK
Date: 2012-11-08T13:57:14+01:00
Content-Length: 327
Expires: 0
Connection: close
{
     "dialogId": "VOICE_AUTH",
     "dialogText": "Ring 810 10 001 for autorisasjon av kortnr(se kundens kort) Brukersted: 123123",
     "optional": "true",
     "textInputs": [
          {
               "inputId": "InputId",
               "text": "Tast inn autorisasjonskode",
               "type": "ALPHA_NUMERIC,
               "minLength": 6,
               "maxLength": 6               
          }
     ]
}     
HTTP/1.1 200 OK
Date: 2012-11-08T13:57:14+01:00
Content-Length: 327
Expires: 0
Connection: close
{
     "dialogId": "VOICE_AUTH",
     "dialogText": "Ring 810 10 001 for autorisasjon av kortnr(se kundens kort) Brukersted: 123123",
     "optional": "true",
     "textInputs": [
          {
               "inputId": "InputId",
               "text": "Tast inn autorisasjonskode",
               "type": "ALPHA_NUMERIC,
               "minLength": 6,
               "maxLength": 6               
          }
     ]
}     
Send Input
The ECR shall call this service to provide input response to an input dialog obtained from the get input dialog. See also description in the input dialogs chapter
Request Method
POST     
Request URL
/pospayclient/api/sendInput
Request object
Send input
Object name
Description
Value format
Mandatory
dialogId
The dialog id from the get input dialog this is an response to
String
X
inputResponses
An array of the responses for the dialog
inputResponses[]
X
inputResponses[]
Object name
Description
Value format
Mandatory
inputId
The input id from the get input dialog this is particular response belongs to
String
X
Value
The response value from the ECR
String
X
Response object
None
Specific error responses
Error
Condition
HTTP response code
NotExpectingInputResponse
PosPay client has no running input dialog it is expecting a response for
409 Conflict
For general error responses please see:          General errors for any kind of request


Examples
Request
POST /pospayclient/api/sendInput HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 123
{
     "dialogId": " VOICE_AUTH",
     "inputResponses": [
          {
               "inputId": " InputId ",
               "value": "123456"
          }
     ]
}
POST /pospayclient/api/sendInput HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:22+01:00
Content-Length: 123
{
     "dialogId": " VOICE_AUTH",
     "inputResponses": [
          {
               "inputId": " InputId ",
               "value": "123456"
          }
     ]
}
Response
HTTP/1.1 200 OK
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 200 OK
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Cancel input
The ECR may call this service to cancel an ongoing optional input dialog. See also description in the input dialogs chapter
Request Method
GET
Request URL
/pospayclient/api/cancelInput
Request object
None
Response object
None
Specific error responses
Error
Condition
HTTP response code
NoInputDialogRunning
PosPay client has no running input dialog to cancel
409 Conflict
For general error responses please see:          General errors for any kind of request
Examples
Request
GET /pospayclient/api/ inputDialog HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
GET /pospayclient/api/ inputDialog HTTP/1.1
Host: localhost
Content-Type: application/json; charset=utf-8
Date: 2012-11-08T13:56:45+01:00
Content-Length: 0
Response
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
HTTP/1.1 202 Accepted
Date: 2012-11-08T13:56:22+01:00
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: close
Ping
Use this service to ping PosPay Server.
If ping successful, ECR will receive event 1905. If ping fails, event 3025 is received.
Request Method
GET
Request URL
/pospayclient/api/ping
Request object
None
Response object
No response object. HTTP response 202 Accepted is returned if transaction is accepted.
Specific error responses
None. For general error responses please see:          General errors for any kind of request