Intech, all rights reserved. 2016 ©

Changelog

v1.4.4

Tuesday, 3rd December 2019

new Added chapter Response codes.

v1.4.2

Tuesday, 22nd October 2019

update Updated chapter Introduction. Added setup types.

new Added chapter Client Samples with Source Code.

v1.4.1

Thursday, 10th October 2019

v1.4.0

Friday, 26th September 2019

new Created a new page POS Integration.

update Moved and updated chapter Integrating PayWiser MiniPOS from Payment Gateway to here.

update Moved and updated chapter InitPOSPayment from Payment Gateway to here.

update Moved and updated chapter CheckPOSPaymentStatus from Payment Gateway to here.

update Moved and updated chapter InitPOSRefund from Payment Gateway to here.

update Moved and updated chapter CheckPOSRefundStatus from Payment Gateway to here.

new Added chapter Receiving Transaction Callbacks.

new Added chapter List Payment Transactions.

new Added chapter List Refund Transactions.

Introduction

PayWiser PaymentGateway POS enables you to easily initiate POS card payments from your desktop, web or any other implementations and solutions of your own, using unified API.

PayWiser PaymentGateway POS enables you to:

  • Initiate transactions:
    • payment
    • refund
  • Receive transaction status callbacks:
    • to your own webservice
    • using SignalR hub
  • check for transaction status manually
    • payment
    • refund
  • list transactions
    • payment
    • refund
  • Repeat printing of the transaction slip

Based on a card reader type we offer 2 different setups:

Terminal with a built-in printer

In this setup, a terminal with a built-in printer is used so no additional printer or device is needed for printing transaction slip. This setup is suggested to be used in cases where ECR is stationary and terminal does not need to be carried around.

Prerequisites:

  • PayWiser PaymentGateway POS account
  • Terminal with a built-in printer

Limitations:

  • A terminal can process only one transaction at the time.
  • A transaction can be canceled only on terminal.

Terminal without a built-in printer

In this setup, a terminal without a built-in printer is used which means that a separate external Bluetooth printer must be used with MiniPOS Lite app running on an Android device. This setup is suggested to be used in cases where ECR is carried around, for instance, a waiter.

Prerequisites:

  • PayWiser PaymentGateway POS account
  • Terminal without a built-in printer
  • Bluetooth printer
  • MiniPOS Lite mobile app (Setup instructions)
  • Android mobile device (support Android 6.0 and newer)

Limitations:

  • A terminal can process only one transaction at the time.
  • A transaction can be canceled only on terminal.

Enviroments

We offer two separate environments:

Test environment

API:
copy
https://posgatewaytest.paywiser.eu
SignalR hub:
copy
https://gateway.paywiser.eu:8094

Production environment

API:
copy
https://posgateway.paywiser.eu
SignalR hub:
copy
https://gateway.paywiser.eu:8093

List of response codes

Every POS API response contains status code and status message in accordance with the following list:

Status Message
0 OK
-1 Invalid caller
-2 Invalid parameters
-3 Duplicate ReferenceID
-9 Amount is too small
-10 Amount is too large
-11 General processing error
-132 Invalid currency
-158 Invalid ReferenceID
-173 General POS error
-174 POS payment not found
-175 POS payment is already in progress
-176 POS refund not found
-177 POS refund is already in progress
-178 Invalid refund PIN
-179 Daily allowed amount exceeded
-180 Monthly allowed amount exceeded
-181 Unsupported operation
-222 Printing not supported on this terminal

Client samples with source code

InitPOSPayment

copy
/InitPOSPayment

Initiates (starts) PayWiser POS payment.

After the payment was successfully initiated and the payment status changes, you can receive status changes either using callback or manual checks.

Request parameters

Parameter name Type Max. Length Description
ReferenceID string 200 Your own unique reference ID
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
StatementText string 255
Amount int Amount in minor units of given currency (e.g. cents if in Euro)
Currency string 3 ISO 4217 3-letter currency code Please note that the currency must match PayWiser MiniPOS terminals currency
TerminalID string 255 PayWiser MiniPOS ID of the terminal on which payment should be initiated
CallbackMethod int 0 – none (you will user manual checks)
1 – SignalR
2 – WebService callback
CallbackMethodURL string 255 must be specified if CallbackMethod == 2

Response

Parameter name Description
CallerReferenceID Caller reference ID
PGReferenceID PayWiser reference ID
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Test_pos_payment_1",
    "StatementText":"Test payment",
    "Amount":120,
    "Currency":"EUR",
    "TerminalID":"ECR_TST1",
    "CallbackMethod":0
}

Sample response

copy
{
    "PGReferenceID": "d7bceab3-b1f9-4d97-af5c-eb18863c1134",
    "CallerReferenceID": "Test_pos_payment1",
    "StatusCode": 0,
    "StatusDescription": "Ok"
}

Initiating Refund Transaction

copy
/InitPOSRefund

Initiates (starts) PayWiser POS refund.

After the refund was successfully initiated and the refund status changes, you can receive status changes either using callback or manual checks.

Request parameters

Parameter name Type Max. Length Description
ReferenceID string 200 Your own unique reference ID
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
StatementText string 255
Amount int Amount in minor units of given currency (e.g. cents if in Euro)
Currency string 3 ISO 4217 3-letter currency code Please note that the currency must match PayWiser MiniPOS terminals currency
TerminalID string 255 PayWiser MiniPOS ID of the terminal on which payment should be initiated
CallbackMethod int 0 – none (you will use manual checks)
1 – SignalR callback
2 – WebService callback
CallbackMethodURL string 255 must be specified if CallbackMethod == 2
RefundPIN string 255 Refund PIN code, as set up in the PaymentGateway Dashboard

Response

Parameter name Description
CallerReferenceID Caller reference ID
PGReferenceID PayWiser reference ID
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Test_pos_refund_1",
    "StatementText":"Test refund",
    "Amount":100,
    "Currency":"EUR",
    "TerminalID":"ECR_TST1",
    "CallbackMethod":0,
    "RefundPIN":"53498",
}

Sample response

copy
{
    "PGReferenceID": "fea00af2-9d6c-4bc3-b0b7-7aa00ef3147d",
    "CallerReferenceID": "Test_pos_refund_1",
    "StatusCode": 0,
    "StatusDescription": "Ok"
}

Receiving Transaction Callbacks

If POS transaction was successfully initiated and you specified either Webservice or SignalR callback with your request, you will receive transaction status changes via the selected method.

Generally speaking, SignalR callbacks are noticeably faster than Webservice callbacks and arrive almost instantly (very low latency).
This is due to the inherent technological difference, as SignalR is intended for real-time messaging and is utilizing WebSockets.

For webservice callbacks:

  • PayWiser will make HTTP POST to the specified URL, sending JSON data
  • TLS 1.2 will be used and must be supported by your webservice
  • when your webservice receives callback, it must return HTTP 200 status code
  • if HTTP 200 is not returned, PayWiser will make 5 attempts in 1 minute intervals to resend the data (after that, no further attempts will be made)

For SignalR callbacks:

  • your client must establish SignalR connection to the appropriate hub
  • connection can be established for a single payment (specifying both PGReferenceID and ApiKey when connecting to the hub)
  • alternately, you can establish a single connection for all of the account payments (specifying just ApiKey when connection to the hub)
  • if at the time of the status change no clients that could receive data are connected, they will receive all of the status changes once reconnected

For C# samples, please see:

Callback data structure

Regardless of the callback method, the data structure you will receive is always the same.

Example:

copy
{
    "Type":"pos_payment",
    "Data":{
        "PGReferenceID":"d7bceab3-b1f9-4d97-af5c-eb18863c1134",
        "CustomerReferenceID":"Test_pos_payment1",
        "TransactionType":1,
        "PaymentStatus":2,
        "PaymentStatusDescription":"POS payment succeeded",
        "CardScheme":"Mastercard",
        "CardType":"Credit",
        "TerminalID":"ECR_TST1",
        "TerminalIP":null,
        "TerminalPort":null
    },
    "HMAC":"d174aeda196cfe1cd5d8449689f910a3"
}

Parameters:

Key name Description
Type pos_payment
pos_refund
Data data payload
PGReferenceID PayWiser reference ID of the transaction
(as returned in response from InitPOSPayment or InitPOSRefund)
CustomerReferenceID Your own reference ID of the transaction
(as specified in request of InitPOSPayment or InitPOSRefund)
TransactionType 1 – POS payment
2 – POS refund
PaymentStatus status of the payment
PaymentStatusDescription description of the payment status
CardScheme Mastercard
Visa
CardType Debit
Credit
TerminalID PayWiser MiniPOS ID of the terminal on which payment was initiated
TerminalIP IP of the payment terminal (card reader)
TerminalPort port of the payment terminal (card reader)
HMAC

Transaction statuses

After initiating transaction (payment or refund), different statuses may be reported over time.

Transaction status Status description Possible next status codes
0 Not initiated none (initiation failed, final status)
1 Initiated 2, 3, 4, 5
2 Succeeded none (final status)
3 Cancelled none (final status)
4 Failed none (final status)
5 Error none (final status)

When callback with status 1 is received, the callback data will contain TerminalIP and TerminalPort, which can be used to do a simple TCP ping operation (open port, close port) in order to wake up connected card reader.
One more callback, containing statuses 2, 3, 4 or 5 will be sent by PayWiser, as transaction status will change once more.

When callback with final status is received, no further callbacks will be send by PayWiser, as transaction status will no longer change.

Calculating HMAC

HMAC is HMAC-MD5 (Hash Based Authentication Code), calculated from callback data payload and your confirmation string, as entered into PaymentGateway Dashboard for your account.

By calculating HMAC yourself and comparint it to the HMAC sent by PayWiser, you can ensure that the callback indeed originated from PayWiser and that the data payload is unchanged.

Examples:

For C# samples, please see: HMAC_MD5_Sample.cs

Checking payment transaction status manually

copy
/CheckPOSPaymentStatus

Returns current status of the PayWiser POS payment as started by InitPOSPayment.

It is suggested method to be called every 2 seconds at most after the payment was initiated and until the final status is received.

Request parameters

Parameter name Type Max. Length Description
ReferenceID string 200 Your own unique reference ID
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
CheckReferenceID string 255 PayWiser PG reference ID as returned from InitPOSPayment
CheckCustomerReferenceID string 255 Your own reference ID, as specified with InitPOSPayment

Either CheckReferenceID or CheckCustomerReferenceID must be specified.

Response

Parameter name Description
PGReferenceID PayWiser reference ID
CallerReferenceID Caller reference ID
PaymentStatus Payment status code
PaymentStatusDescription Payment status description
CardScheme Mastercard
Visa
CardType Debit
Credit
TerminalIP IP of the payment terminal (card reader)
TerminalPort port of the payment terminal (card reader)
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Pos_payment_status_1",
    "CheckReferenceID":"d7bceab3-b1f9-4d97-af5c-eb18863c1134"
}

Sample response

copy
{
    "PGReferenceID": " bdd07725-7a9e-4eb2-8d19-337d10f856dc",
    "CallerReferenceID": "Pos_payment_status_1",
    "PaymentStatus": 1,
    "PaymentStatusDescription": "POS payment initiated",
    "StatusCode": 0,
    "StatusDescription": "Ok"
}

Checking refund transaction status manually

copy
/CheckPOSRefundStatus

Returns current status of the PayWiser POS refund as started by InitPOSRefund.

It is suggested method to be called every 2 seconds at most after the refund was initiated and until the final status is received.

Request parameters

Parameter name Type Max. Length Description
ReferenceID string 200 Your own unique reference ID
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
CheckReferenceID string 255 PayWiser PG reference ID as returned from InitPOSPayment
CheckCustomerReferenceID string 255 Your own reference ID, as specified with InitPOSPayment

Either CheckReferenceID or CheckCustomerReferenceID must be specified.

Response

Parameter name Description
CallerReferenceID Caller reference ID
PGReferenceID PayWiser reference ID
PaymentStatus Payment status code
PaymentStatusDescription Payment status description
CardScheme Mastercard
Visa
CardType Debit
Credit
TerminalIP IP of the payment terminal (card reader)
TerminalPort port of the payment terminal (card reader)
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Pos_refund_status_1",
    "CheckReferenceID":"fea00af2-9d6c-4bc3-b0b7-7aa00ef3147d"
}

Sample response

copy
{
    "PGReferenceID": "bdd07725-7a9e-4eb2-8d19-337d10f856dc",
    "CallerReferenceID": "Pos_refund_status_1",
    "PaymentStatus": 1,
    "PaymentStatusDescription": "POS refund initiated",
    "StatusCode": 0,
    "StatusDescription": "Ok"
}

List Payment Transactions

copy
/ListPOSPayments

Returns a list of all payment transactions initiated in a specified day.

Request parameters

Key name Type Max. Length Description
ReferenceID string 200 Your own reference ID.
We recommend that you use unique reference IDs.
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
Date string 255 Date in format YYYY-MM-DD

Response

Parameter name Description
PGReferenceID PayWiser reference ID
CallerReferenceID Caller reference ID
StatementText as specified in request of InitPOSPayment
Amount as specified in request of InitPOSPayment
Currency as specified in request of InitPOSPayment
TerminalID as specified in request of InitPOSPayment
CallbackMethod as specified in request of InitPOSPayment
CallbackURL as specified in request of InitPOSPayment
PaymentStatus Payment status code
PaymentStatusDescription Payment status description
CardScheme Mastercard
Visa
CardType Debit
Credit
TerminalIP IP of the payment terminal (card reader)
TerminalPort port of the payment terminal (card reader)
PaymentActualAmount actual payment amount (if succeeded)
PaymentActualCurrency actual payment currency (if succeeded)
TransactionType 1 – POS payment
2 – POS refund
TransactionDateTime Timestamp of transaction
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Pos_payment_list_1",
    "Date":"2019-08-07"
}

Sample response

copy
{
    "Payments": [
        {
            "PGReferenceID": "04d3cf48-0edb-4eca-8de9-0f538a4871a6",
            "ReferenceID": "test_payment_init_6",
            "StatementText": "Statement1",
            "Amount": 110,
            "Currency": null,
            "TerminalID": "ECR_TST1",
            "CallbackMethod": 0,
            "CallbackURL": null,
            "PaymentStatus": 1,
            "PaymentStatusDescription": "POS payment initiated",
            "CardScheme": null,
            "CardType": null,
            "TerminalIP": null,
            "TerminalPort": null,
            "PaymentActualAmount": null,
            "PaymentActualCurrency": null,
            "TransactionType": 1,
            "TransactionDateTime": "2019-08-07T12:31:50.8287027Z"
        },
        {
            "PGReferenceID": "6e830eb2-0ae1-4c83-8bc0-fb13405c685b",
            "ReferenceID": "test_payment_init_6",
            "StatementText": "Statement2",
            "Amount": 120,
            "Currency": null,
            "TerminalID": "ECR_TST1",
            "CallbackMethod": 1,
            "CallbackURL": null,
            "PaymentStatus": 2,
            "PaymentStatusDescription": "POS payment succeeded",
            "CardScheme": "Mastercard",
            "CardType": "Credit",
            "TerminalIP": null,
            "TerminalPort": null,
            "PaymentActualAmount": 120,
            "PaymentActualCurrency": "EUR",
            "TransactionType": 1,
            "TransactionDateTime": "2019-08-07T15:54:52.1773403Z"
        }
    ],
    "PGReferenceID": "23475100-2d32-49ff-b848-273c448dbbb2",
    "CallerReferenceID": " Pos_payment_list_1",
    "StatusCode": 0,
    "StatusDescription": "OK"
}

List Refund Transactions

copy
/ListPOSRefunds

Returns a list of all refund transactions initiated in a specified day.

Request parameters

Key name Type Max. Length Description
ReferenceID string 200 Your own reference ID.
We recommend that you use unique reference IDs.
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
Date string 255 Date in format YYYY-MM-DD

Response

Parameter name Description
PGReferenceID PayWiser reference ID
CallerReferenceID Caller reference ID
StatementText as specified in request of InitPOSPayment
Amount as specified in request of InitPOSPayment
Currency as specified in request of InitPOSPayment
TerminalID as specified in request of InitPOSPayment
CallbackMethod as specified in request of InitPOSPayment
CallbackURL as specified in request of InitPOSPayment
PaymentStatus Payment status code
PaymentStatusDescription Payment status description
CardScheme Mastercard
Visa
CardType Debit
Credit
TerminalIP IP of the payment terminal (card reader)
TerminalPort port of the payment terminal (card reader)
PaymentActualAmount actual payment amount (if succeeded)
PaymentActualCurrency actual payment currency (if succeeded)
TransactionType 1 – POS payment
2 – POS refund
TransactionDateTime timestamp of transaction
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Pos_refund_list_1",
    "Date":"2019-08-07"
}

Sample response

copy
{
    "Payments": [
        {
            "PGReferenceID": "04d3cf48-0edb-4eca-8de9-0f538a4871a6",
            "ReferenceID": "test_refund_init_1",
            "StatementText": "Statement1",
            "Amount": 110,
            "Currency": null,
            "TerminalID": "ECR_TST1",
            "CallbackMethod": 0,
            "CallbackURL": null,
            "PaymentStatus": 1,
            "PaymentStatusDescription": "POS refund initiated",
            "CardScheme": null,
            "CardType": null,
            "TerminalIP": null,
            "TerminalPort": null,
            "PaymentActualAmount": null,
            "PaymentActualCurrency": null,
            "TransactionType": 1,
            "TransactionDateTime": "2019-08-07T12:31:50.8287027Z"
        },
        {
            "PGReferenceID": "6e830eb2-0ae1-4c83-8bc0-fb13405c685b",
            "ReferenceID": "test_refund_init_2",
            "StatementText": "Statement2",
            "Amount": 120,
            "Currency": null,
            "TerminalID": "ECR_TST1",
            "CallbackMethod": 1,
            "CallbackURL": null,
            "PaymentStatus": 2,
            "PaymentStatusDescription": "POS refund succeeded",
            "CardScheme": "Mastercard",
            "CardType": "Credit",
            "TerminalIP": null,
            "TerminalPort": null,
            "PaymentActualAmount": 120,
            "PaymentActualCurrency": "EUR",
            "TransactionType": 1,
            "TransactionDateTime": "2019-08-07T15:54:52.1773403Z"
        }
    ],
    "PGReferenceID": "23475100-2d32-49ff-b848-273c448dbbb2",
    "CallerReferenceID": " Pos_refund_list_1",
    "StatusCode": 0,
    "StatusDescription": "OK"
}

Repeat printing of the transaction slip (for the cardholder)

copy
/PrintTransactionSlip

Repeats printing of the last slip of the last transaction (either payment or refund) that took place. This method can be used in cases when there was an issue with printing slip (printer malfunction, out of paper etc).
Slip will be printed automatically and no callback will be received.

Request parameters

Key name Type Max. Length Description
ReferenceID string 200 Your own reference ID.
We recommend that you use unique reference IDs.
Checked with RegEx ^[A-Za-z0-9_-]{1,200}$
TerminalID string 255 PayWiser MiniPOS ID of the terminal on which payment should be initiated

Response

Parameter name Description
PGReferenceID PayWiser reference ID
CallerReferenceID Caller reference ID
StatusCode Status code
StatusDescription Status description

Sample request

copy
{
    "ReferenceID":"Pos_print_receipt_1",
    "TerminalID":"ECR_TST1"
}

Sample response

copy
{
    "PGReferenceID": "8da5bea7-19c7-466b-bed8-7734d37c96e0",
    "CallerReferenceID": "Pos_print_receipt_1",
    "StatusCode": 0,
    "StatusDescription": "OK"
}