3.11. Virtual terminal

3.11.1. Overview

Virtual terminal (VT) is a technological solution that allows to process transactions from merchant’s personal account on User Interface. This feature doesn’t require merchant’s API integration to Payneteasy. VT immediately provides a full-featured payment manager’s workplace. VT is used for remote processing of transactions without the presence of a customer, for example, if the customer places an order or pays for services while being in another city or country. VT is fully customized to meet the business needs. Flexible templates will help to minimize the work of filling all the customer details. Overview: The Virtual terminal supports recurring payments (by recurring ID). If the customer provided cardholder data to Payneteasy processing system before, and the merchant registered such payment to get recurring ID, future payments can be made with recurring ID instead of cardholder data. VT also allows to generate a link for the customer to submit cardholder data in the secure environment, and, if needed, pass 3-D Secure validation.

VT provides a secure way of processing transactions with support of asymmetric cryptography. Generate a pair of public and private keys, pass public key to Payneteasy support and upload the private key in Browser Console (Import private key to Browser Console) or User Interface (Import private key to User Interface).
The following operations are available:

• accepting payments from both new and previously registered customers (Deposit);
• transfer of funds from card to card, both for new and previously registered customers (C2C (Card to Card) Transfer);
• issuance of funds to the cards of both new and previously registered customers (D2C (Deposit to card) transfer);
• transfer of funds from one bank account to another (Payout).

The screen is located in Tools – Virtual terminal (VT).
../_images/enter.png

3.11.2. Asymmetric cryptography

The big advantage of the new virtual terminal is the use of an asymmetric cryptography system. Asymmetric cryptography, or public-key cryptography, is a cryptographic system that uses pairs of keys: public keys which may be disseminated widely, and private keys which are known only to the owner. The generation of such keys depends on cryptographic algorithms based on mathematical problems to produce one-way functions. Effective security only requires keeping the private key private; the public key can be openly distributed without compromising security.

The virtual terminal becomes personalized. The user signs transaction request with his private key and the system uses the public key to verify that request is made by the owner of the corresponding private key.

Generate a pair of public and private keys

You need a private and public key to use a virtual terminal. To generate it, go to https://www.openssl.org/ ( https://slproweb.com/products/Win32OpenSSL.html ), download the latest openssl version and run the following commands:

openssl genpkey -algorithm RSA -out private_key_pkcs_8.pem -pkeyopt rsa_keygen_bits:4096

openssl rsa -pubout -in private_key_pkcs_8.pem -out public_key.pem

Do not share your private key with anyone, you should be the only one who knows it. In contrast, your Public Key must be passed to Payneteasy for endpoint configuration. Please use different keys for production and for testing to avoid compromise.

PKCS #8 RSA unencrypted private key in PEM format starts with —– BEGIN PRIVATE KEY —– text. This key must be imported to Browser Console or User Interface. See details below.

Import private key to Browser Console

Private key is imported into browser’s IndexedDB using a script associated with the currently opened page. This script only uses plain browser APIs (WebCrypt API, IndexedDB API) and does not use any external scripts to avoid the private key being compromised.
Import sequence is:
1. Open https://gate.payneteasy.eu/paynet-ui/login-step1 page in a browser(Do not login to the system).
2. Open the browser console. In Chrome, it is done with Ctrl+Shift+J. In Safari, it is done with Ctrl+Shift+I, Ctrl+Alt+C. For Mac - Cmd instead of Ctrl.
3. Replace the demo key below with your real private key in PEM format (it must have that —–BEGIN PRIVATE KEY—– prefix in the beginning).
var privateKeyPem = `-----BEGIN PRIVATE KEY-----\
     MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDJzUVnqQhDWF2H
     pxAMcyo7f+ucIEJS3AQHG0ET/dxJ0qssGymIjdzelJ3XI+oTq2y9TTimQjtujoeh
     6zl44WrXCbJLCUDWsNjlh7hmBorpU6tJVhw1466CAxkktPJHkMqJYF0efegIfOwU
     otTzwY4tGlN6iWK0aMJ5ZWhWpZDbgap72vrRXKfCN6/JeTUdsOI7PAeZw0me04jZ
     8Lova9FVIbVzOJaFGwSUroMvXevIB8rOD57c3VCLTxE3aGNMz+9DLl6GCm8WZ1US
     HmiHybqgvGLyQswBPFcVzFgd7BpgZs+JAzYDh8ZGANvjA5F9u0b6Ynb3Mpm3+9Rl
     CtvSxKwpAgMBAAECggEAZ6+hro5KIZggjleHRm5Rz7p9S33DtiE3rJMTT/tKmV+1
     9XaLU49YYcDIjMb2OV8GAwnPRpWXRcnT5J0grXxc0do4kpdRij3ZY63lT/6ilxoX
     Uxn8aq/udPy0iYizR5QcjJNHpSgZ9WqCPmQfuJLFw2TYaYh3f6yn54n0Hzj4gd9l
     tsol4xeTKQ47c/vUF7kHfD8IYzL8jv3a3++IqzCwJ3jIpTENsBYAgrkbYN9f9GHD
     BvX3sz6tgFaYU2R8YbDvA0Yq9tVPwYrPvbhwoht6PsjE/R0UK6yqnKPEADdzWvP8
     frXmmtJ35rAymqUWfpqx9RdZ0NMR7J8ut8C5365PJQKBgQD+UidVWut7d9qvhZKq
     +T5qtasH5qkD34idFl4Ay8xsSntqTrXr7q1Ff+FQY6R+f/8IzB4ZqgnV58+8AEMc
     gJzNmkf9L119SCQDxRV/TgW2eHrUrI9XS2AI5tmyzaGY1xL4fCQQMvqNAGERT6sS
     XJRt8WjuGmE4zeqxNB0XY7u1OwKBgQDLIlnksOrPw00lWUbXHSHwdfBzjYU97KVu
     GnOl5fsCmlKanqHUfd/4StnRXpl3l56hig8mYsHV5EcfUEX98PaSbTAy8Lk5y5E9
     ye2ENOgl/IyMgHPtT6spFKm7jRmpulqG4FVCGxQl3n6/nSmztA3S1zLZzi0guI0E
     oxXCbG796wKBgC8NSgOrr5eHRClnIAyL0nVxqPPsQ+bYi3Dsu3WQPwDmAtFXQKcm
     4F3UW/5AgSV6Ttf007jR0cIGglN5BPGYBeqwGZOJGNXd6/PambCU4c+xmKASUO7I
     njrnYu2Gx9f8KqFYbl+k3uAJauwF/lOGV1vD5zLuJICa8Enap2s1Y3wTAoGBAKrx
     QnLISyIB+XbXtVyrYHdJ2Mp1Ks6cye5pBi9y5RQgqCkEG62FLCh3XOvrTvysNEs+
     slccPoBv9UYtuGjmEanRhwEnQMiZPaWgu2dJWp8081X9dxEavS/5+oghSpphf3MH
     b9gMj5z6qvE3IfPfLs7iWCGgdquVgt6HG3Wc6J53AoGAc+ZYE8kMj2p9rtu1uJgX
     +VMbbdLEUqz3BPC9Tzq+eglUlYmwUK1xynKZfkEMcu5PncaBaNLU+GmYKKgw6wZS
     soEF1KvbBB4o6nZdlGo0BirOQ0ijHDWUvtuiaaWAQoQAhQwgqqV2IOC4UfkZ6ORf
     A/UW43A9wZq9kaEgb0YWOes=\
     -----END PRIVATE KEY-----`;

// Algorithm Object
var algorithmKeyGen = {
  name: "RSASSA-PKCS1-v1_5",
  // RsaHashedKeyGenParams
  modulusLength: 2048,
  publicExponent: new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
  hash: {
    name: "SHA-256"
  }
};

function parsePem(pemString, type) {
    const expectedPrefix = "-----BEGIN " + type + "-----";
    const expectedPosftix = "-----END " + type + "-----";

    pemString = pemString.trim();
    if (!pemString.startsWith(expectedPrefix)) {
        throw "Expected PEM to start with " + expectedPrefix;
    }
    if (!pemString.endsWith(expectedPosftix)) {
        throw "Expected PEM to end with " + expectedPosftix;
    }
    const base64 = pemString.substring(expectedPrefix.length, pemString.length - expectedPosftix.length).trim();
    return Uint8Array.from(atob(base64), c => c.charCodeAt(0))
}

function parsePrivateKeyPem(pem) {
    return parsePem(pem, 'PRIVATE KEY')
}

function storePrivateKey(privateKey) {
    var request = indexedDB.open("keys");

    request.onupgradeneeded = function() {
      // The database did not previously exist, so create object stores and indexes.
      var db = request.result;
      var store = db.createObjectStore("privateKeys", {keyPath: "name"});

      // Populate with initial data.
      store.put({name: "first", key: privateKey});
    };

    request.onsuccess = function() {
      db = request.result;
    };
}

var privateKeyArray = parsePrivateKeyPem(privateKeyPem);
var NON_EXTRACTABLE = false;
window.crypto.subtle.importKey("pkcs8", privateKeyArray, algorithmKeyGen, NON_EXTRACTABLE, ['sign'])
.then(function(privateKey) {
        storePrivateKey(privateKey);
        privateKeyPem = null;
        privateKeyArray = null;
    }
);
4. Copy this script content and paste it into your browser console.
5. The key has been imported in a non-extractable manner.

Warning

If you have integrated the private key into the browser, but could not make transactions. Please clear your browser’s cache and try again to integrate the private key.

Note

If you don’t want to use the proposed code or want to get more information about the Web Crypto API, you can visit the official site https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API

Import private key to User Interface

The virtual terminal has the function of using a private key through the user interface
../_images/add_private_key_1.png
To conduct a large number of test transactions, you can check the “Save key in the browser” box, and the private key will be automatically saved in the browser.
../_images/add_private_key_2.png

3.11.3. MOTO transactions

VT interface details

The VT has control buttons, which are described in more detail below.
icon - Adding a private key icon - Copy link
icon - Hide sealed fields icon - Show sealed fields
icon - Save template icon - Default template
icon - Unseal the field icon - Seal the field
icon - Clean all unsealed fields icon - Required fields

Template management

../_images/create_template_step_1.png ../_images/create_template_step_2.png ../_images/create_template_step_3.png
1) To simplify the work of the virtual terminal operator, data fields can be saved as a template. Using templates allows to work only with the individual attributes of the client.
2) After entering data on the right side of the page, you can save this data as a template by clicking save as a template. Next need to write the name of the template.
3) To edit, clone or delete, you need to click three dots near the template name and select the desired parameter.

Transaction specification

Deposit

Virtual terminal provides the possibility of processing deposit transactions (Sale). To initiate such transaction, cardholder data (card number, cvv, expiration date, holder name) must be provided.
Several payment scenarios can be done for deposit transactions:

1) Cardholder data (card number, cvv, expiration date, holder name) can be filled by merchant for the customer.
2) When a merchant has previously registered the customer cardholder data, it can be pulled up automatically by providing the recurring ID. In this case, there are two options:
a) The bank account is registered for non-3DS and noCVV transactions. To process the transaction, no further customer authentication is required.
b) The bank account requires 3-D Secure. The merchant creates a link to send to the customer. The customer passes 3-D Secure authentication on the form.
3) The merchant does not have customer cardholder data and he creates a special link. The customer will receive a link to a form in which he can fill in the cardholder data, and then pass the 3-D Secure check (if needed).
../_images/deposit.png

C2C (Card to Card) Transfer

Virtual terminal provides the possibility of processing transfers transactions from card to card (C2C). To initiate such transaction, cardholder data for both the sender (card number, cvv, expiration date, holder name) and the recipient (card number) must be provided.
Several scenarios are possible:
1) Transfer money from registered card to unknown card.
Sender data is retrieved using recurrent ID. The The merchant creates a special link for the sender of funds. The sender receives the link to a form in which he fills the destination card number.

Note

in this case the transaction must be processed through the noCVV channel.

2) Transfer money from unknown card to registered card.
Receiver data is retrieved using recurrent ID. The merchant creates a special link for the sender. The sender receives the link to a form in which he fills his card number, expiration date, holder name and CVV, then passes the 3DS check if needed.
3) Transfer money between known or registered cards.
The merchant fills the cardholder data or use recurring IDs for both sender and receiver of funds directly on VT.

Note

in this case the transaction must be processed through the noCVV channel.

../_images/transfer.png

D2C (Deposit to card) transfer

Also virtual terminal provides the possibility of processing transfers transactions from account to card (D2C). To initiate such transaction, cardholder data for the recipient (card number) must be provided.
Several scenarios are possible:
1) Transfer money to known card.
The merchant fills the cardholder data for receiver of funds directly on VT.
2) Transfer money to registered card.
Receiver data is retrieved using recurrent ID.
3) Transfer money to unknown card.
The seller creates a special link for the recipient of funds. The recipient receives the link to a form in which he fills the number of the destination card number.
../_images/d2c.png

Payout

Virtual terminal provides the possibility of processing payout transactions (payout). To initiate such transaction, account number or phone of the recipient must be provided.
Several scenarios are possible:
1) Payout money to account number or phone. The merchant fills the payment data for receiver of funds directly on VT.
a) Payout without additional fields.
b) To process the transaction, the bank require filling in additional fields. Additional fields are filled after selecting an endpoint.
2) The merchant does not have customer payment data and he creates a special link. The customer will receive a link to a form in which he can fill in the payment data and choose a bank.
../_images/payout.png