3.10. Virtual terminal

3.10.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 for 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. Besides that, VT is fully integrated with the recurrent payment screen, register subscriptions and process recurrent transactions. VT also allows to generate a link for the customer to submit cardholder data in the secure environment, and, if needed, pass 3D-Secure validation.
At the moment, 3 processing modes are supported:
a - MOTO transactions (credit cards and other payment methods);
b - SWIFT bank transfer;
c - China union pay;

The following operations are available:

• accepting payments from both new and previously registered customers;
• transfer of funds from card to card, both for new and previously registered customers;
• issuance of funds to the cards of both new and previously registered customers;
• transfer of funds from one bank account to another.

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

3.10.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.
In such a system, any person can encrypt a message using the receiver’s public key, but that encrypted message can only be decrypted with the receiver’s private key.

Robust authentication

The virtual terminal becomes personalized. A sender can combine a message with a private key to create a short digital signature on the message. Anyone with the corresponding public key can combine a message, a putative digital signature on it, and the known public key to verify whether the signature was valid, i.e. made by the owner of the corresponding private key.

Warning

Using the same key for different users is strictly not recommended.

General principles of asymmetric encryption

Asymmetric public key encryption is based on the following principles:

• You can generate a pair of very large numbers (public key and private key) so that, knowing the public key, it is impossible to calculate the private key within a reasonable time. In this case, the generation mechanism is well known.
• There are strong encryption methods that allow you to encrypt a message with a public key so that it can only be decrypted with a private key. The encryption mechanism is well known.
• The owner of two keys does not tell anyone the private key, but transfers the public key to counterparties or makes it publicly known.

If it is necessary to transmit an encrypted message to the owner of the keys, the sender must receive the public key. The sender encrypts his message with the recipient’s public key and sends it to the recipient (owner of the keys) through open channels. In this case, no one can decrypt the message except the owner of the private key.
As a result, you can securely encrypt messages. The private key is kept secret for everyone - even for message senders.

Web Crypto API

In order to use all the advantages of asymmetric encryption, Mozilla developed the Web Crypto API. Web Crypto API is an interface allowing a script to use cryptographic primitives in order to build systems using cryptography.
The interface allows access to the following primitives:

digest, the ability to compute a hash of an arbitrary block of data, in order to detect any change in it.
mac, the ability to compute a message authentication code.
sign and verify, the ability to digitally sign a document, and to verify a signature.
encrypt and decrypt, the ability to encode or decode a document.
import and export, the ability to import a key or export a key.
key generation, the ability to create a cryptographically secure key, or key pair, without the use of base key, but using the available entropy of the local system.
key wrapping and unwrapping, the ability to transmit, and to receive, a key from a third party, encoded using another key, without exposing the underlying key to JavaScript.
random, the ability to generate cryptographically reliable pseudo-random numbers.

For more information about Web Crypto API, please check https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API.

Generating 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/download/Win64OpenSSL-1_1_1d.exe , https://slproweb.com/download/Win32OpenSSL-1_1_1d.exe ), 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.

Private key

To use a virtual terminal, you need a private key in the PKCS container # 1. The key format must be in PCS PKCS # 1 format and in the unencrypted form with an RSA private key. To get it, use the following command.

openssl rsa -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

As a result, you will receive a key starting with —– BEGIN RSA PRIVATE KEY —–. For production purposes, you can use the key in any format supported by your software.

Warning

The private key must be kept secret from everyone.

Import a private key

Private key is imported into browsser’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.com/paynet-ui/ 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

3.10.3. MOTO transactions

Processing a transaction on VT

The virtual terminal allows transactions of the following types:

Sale (purchase)
Transfer (transfer from card to card)
Deposit to card transfer (transfer of money from account to card)
Payout (issuancee of money from account to account)

The Virtual terminal screen will automatically be configured for the appropriate transaction type. For all types of transactions fill the amount field and select the currency. The list of currencies is similar to list presented in the personal account header. All fields marked with an asterisk * are mandatory.

Creating and configuring a template

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.

Recuring ID

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.

Transaction specification

Sale

Virtual terminal provides the possibility of processing sale 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 sale 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 non3D and noCVV transactions. To process the transaction, no further customer authentication is required.
b) The bank account requires 3DSecure. The merchant creates a link to send to the customer. The customer passes 3DSecure 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 3DSecure check (if needed).
For details of card to card transfer, check (Sale Transactions).

Transfer

Virtual terminal provides the possibility of processing transfers transactions from card to card (p2p). 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.

For details of card to card transfer, check (Transfer V4).

Deposit to card transfer

Also virtual terminal provides the possibility of processing transfers transactions from account to card (d2p). 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.
For details of deposit to card transfer, check (Deposit to Card Transfer).

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.