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:

We offer two separate environments:

https://posgatewaytest.paywiser.eu

https://gateway.paywiser.eu:8094

https://posgateway.paywiser.eu

https://gateway.paywiser.eu:8093

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

C# client:

• InitPOSPaymentWindowsClient.zip
• InitPOSPaymentWindowsCSharpSourceCode.zip

Android (Java) client:

• InitPOSPaymentAndroidClient.apk
• InitPOSPaymentAndroidSourceCode.zip

/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

Response

Sample request

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

Sample response

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

/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

Response

Sample request

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

Sample response

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

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:

• WebService_Sample.ashx.cs
• SignalR_Sample.cs

Callback data structure

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

Example:

{
    "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:

Transaction statuses

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

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:

• PHP
• Java
• JavaScript

For C# samples, please see: HMAC_MD5_Sample.cs

/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

Either CheckReferenceID or CheckCustomerReferenceID must be specified.

Response

Sample request

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

Sample response

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

/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

Either CheckReferenceID or CheckCustomerReferenceID must be specified.

Response

Sample request

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

Sample response

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

/ListPOSPayments

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

Request parameters

Response

Sample request

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

Sample response

{
    "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"
}

/ListPOSRefunds

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

Request parameters

Response

Sample request

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

Sample response

{
    "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"
}

/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

Response

Sample request

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

Sample response

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