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. 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 3-D Secure validation.
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.
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.
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.
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/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.
Private key¶
To use a virtual terminal, you need a private key in the PKCS container # 8. The key format must be in PCS PKCS # 8 format and in the unencrypted form with an RSA private key.
As a result, you will receive a key starting with —– BEGIN 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 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:
Browser Console¶
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
User Interface¶
The VT has control buttons, which are described in more detail below.
The virtual terminal has the function of using a private key through the user interface
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.
3.10.3. MOTO transactions¶
Creating and configuring a template¶
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.
Note
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¶
Deposit¶
Virtual terminal provides the possibility of processing deposit transactions (deposit). 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).
For details of card to card transfer, check (Sale Transactions).
Note
Below are the main parameters that must be filled in order to complete a transaction
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).
Note
Below are the main parameters that must be filled in order to complete a transaction
D2C (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).
Note
Below are the main parameters that must be filled in order to complete a transaction
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.
Note
Below are the main parameters that must be filled in order to complete a transaction
