Paynkolay Virtual POS: connecting your merchant account

The Paynkolay integration connects your business's Paynkolay merchant (virtual POS) account to Piyzi.

At this stage only the connection is set up: no payments are taken with the account you connect and no payment links are sent to your customers yet. Online card payment features will use this connection once they are added to Piyzi.

You set up the connection on the web panel only; this screen is not in the mobile app.

Before you start

• A Piyzi account with an active subscription.

• Being the business owner. Only the business owner can connect, test, update or remove the virtual POS account. Because this setting decides which account payments go to, staff whose role has Can set up integrations cannot do these either. Staff with Can view integrations can open the window and see the connection's status.

• A Paynkolay merchant account with a signed agreement and API access enabled. The account does not belong to Piyzi; the agreement, commission and settlements are between you and Paynkolay.

• The four details from your Paynkolay merchant panel (below).

The details you need

• sx (sales key): used to take payments.

• sx List (listing key): used to list and report transactions.

• sx İptal (cancellation and refund key): used for cancellations and refunds.

• Merchant Secret Key (secret key): used to sign requests; it is never sent to Paynkolay in plain text.

Connecting the account

1. 1

   Open the Paynkolay window

   Open My Business → Pi Store from the left menu and click the Paynkolay Virtual POS card under Payment Methods.

2. 2

   Enter the details

   Copy the four fields from your Paynkolay panel and paste them in; all four are required. The fields are hidden like passwords; click the eye icon on the right of a field to see what you typed.

3. 3

   Click Verify and connect

   Before saving anything, Piyzi sends Paynkolay three test requests that do not move any money: Merchant and secret key, Listing key (sx List) and Cancellation and refund key (sx İptal). If all three pass, the details are saved encrypted, a “Virtual POS connected.” notification appears and the card shows the Connected badge.

4. 4

   Check the result

   The window shows the Connected and Live environment badges, the Saved details section and the Last check section with the result of each check.

If even one check fails, nothing is saved. Above the fields you see which check failed and why, and the wrong field is marked in red; fix the field and try again. If you leave a field empty, the “Fill in all fields.” warning appears.

How are your details stored?

• The details are verified with Paynkolay before they are saved; details that fail verification are not saved.

• Saved details are encrypted and never shown on screen again. The Saved details section shows only the first and last four characters of the keys; no part of the secret key is shown.

• When you update the details you enter all four again; Piyzi does not bring the saved details back into the form.

• Connecting, updating, testing and removing are written to the Activity Logs with who did them; the keys themselves are not in the logs.

• In a support session the Piyzi support team cannot see or change the virtual POS details and cannot remove the connection.

Testing the connection

To check that the connected account still works, click Test connection at the bottom of the window. Piyzi sends the same three test requests with the saved details and writes the result to the Last check section. If the test passes, “The connection is working.” appears; if not, “The connection test failed. See the details in the window.” If you renewed the keys in your Paynkolay panel, the test fails; update the details.

Updating the details

1. 1

   Open the update form

   Click the ⋮ (More actions) button at the bottom of the window and choose Update details.

2. 2

   Enter the details again

   Enter the four details and click Verify and save. The saved details do not change until the new ones are verified; Cancel takes you back to the saved connection.

Removing the connection

1. 1

   Choose Remove

   Choose Remove connection from the ⋮ button at the bottom of the window.

2. 2

   Confirm

   Confirm the “Remove the connection?” question with Remove connection.

• The saved details are deleted from Piyzi; to reconnect you need to enter all four again.

• Your Paynkolay account is not touched.

• The card shows Not Connected.

Troubleshooting

• “The secret key is wrong or doesn't belong to this merchant.” The Merchant Secret Key was copied wrong or belongs to another merchant. When this check fails, the other two checks show “Not tried”.

• “No merchant was found for this key.” Check the sx field.

• “This key isn't authorised for this operation; it may have been copied from a different field.” A different key was pasted into the sx List or sx İptal field; copy the marked field again from the right field in the Paynkolay panel.

• “This key doesn't belong to the same merchant as the sales key, or it was copied incompletely.” The sx List or sx İptal key belongs to another merchant or was copied incompletely; copy the marked field again, in full, from the Paynkolay panel.

• “Paynkolay isn't responding right now.” Try again in a few minutes.

• “Paynkolay returned an unexpected response.” Check the details and try again; if the problem continues, let the Piyzi support team know.

• “Too many attempts. Try again in 15 minutes.” For security, a business can make at most 10 connection or test attempts in 15 minutes.

• Warning about the sales key: whether the key in the sx field is a sales key cannot be tried while connecting, because the attempt would start a real payment. If your listing and cancellation keys do not share the sales key's structure, the window shows a warning; check that you copied all three keys from the right fields in the Paynkolay panel.

• “The environment has changed”: the details were verified in a different Paynkolay environment. Test the connection; if it fails, enter the details again.

• “The saved details can't be read”: enter the details again with the Re-enter details button; if the problem continues, let the Piyzi support team know.

• “Virtual POS is unavailable right now”: a setting is missing on Piyzi's side; let the Piyzi support team know.

• There is no connect button in the window: only the business owner can connect the virtual POS, and it cannot be connected in a support session.