Introduction to Virtual

The Virtual Payment Solution makes use of Adumo Online's hosted payment page. This is a popular solution mainly due to the ease of integration into the solution and the high level of Security that it provides to merchants.

The Virtual Solution also has the ability to be customized to such an extent that your client would feel as though they are on your website while making payment, ensuring peace-of-mind throughout the entire checkout process.

The Virtual solution offers the ability for a merchant to customise the logo, colours and details displayed on the payment page so that the cardholder does not feel that they are leaving the merchants website. The Virtual Payment Page is operating behind TLS (Transport Layer Security) security protocol and all information that is captured on the payment page is encrypted using 128-bit encryption ensuring that your client's credit card details are kept safe.

Virtual Features

• The merchant is not required to implement TLS, therefore saving costs.
• Both the merchants logo and details can be hosted on the payment page.
• CSS Editor allowing full payment page customization.
• Email confirmation can be sent to card holder for successful purchases.
• The Fraud Module can be configured to help reduce fraud.
• Failure and Success Pages can be configured to be displayed by Adumo Online.
• Additional detail such as shipping address and purchase items can be displayed on the payment page
• This is a quick and easy method which ensures less programming.
• Basic development skills are required.

Virtual Payment Process

One of the main benefits of utilising the Virtual Solution is the simplicity in which to integrate it into your online website. It requires less development work than other Adumo Online Solutions and security measures are already incorporated by Adumo Online.

Virtual allows the merchant to utilize the Adumo Online payment webpage. This means that your clients will be directed to Adumo Online's Payment Page where they will enter their credit card details in order for the transaction to be completed. The payment information which Adumo Online requires is posted to Adumo Online via a form POST. This POST can be done in any language that supports this method.

Illustration: Virtual Payment Process

Step 1 – Cardholder makes purchase from merchant's website.
Step 2 – Merchant creates form post to Virtual payment page.
Step 3 – Adumo Online processes the transaction to the merchant Bank.
Step 4 – The merchant bank processes the transaction and returns a successful or declined message.
Step 5 – Adumo Online returns this result and/or error code with error description back to the Merchant
Website address specified in the form POST.
Step 6 – If the functionality is set up (from the Adumo Online Web Console) Adumo Online will notify the card
holder via email of the transaction details and the merchant via email.

General Requirements for Using Virtual

• Website – You must have a website or shopping cart and have ability to load sample code or shopping cart code to the site.
• Internet Merchant Account – You are required to have an internet merchant account with a bank.
• Internet Connectivity – Internet connectivity is required to post the transaction.
• Internet Service Provider (ISP) – An ISP is required to host your site.
• Adumo Online issued Merchant ID and Application ID – Required parameters when sending your form post.

Internet Merchant Account

An Internet Merchant Account is required to accept credit card transactions over the internet. If you have an Internet Merchant Account you need to supply these details to Adumo Online before going Live. If you do not have an Internet Merchant Account, Adumo Online can assist you with your application to the acquirer (bank).

Note: An Internet Merchant Account is a different type of merchant account than what is used for card present / POS transactions. You will need to apply for an Internet Merchant Account even if you already accept credit card transactions from your store.

Security – Server Passwords

You need to apply security best business practice to ensure that confidential data and card detail are protected while either being stored in the database or while data is being transmitted. It is suggested that you encrypt key information issued to you by Adumo Online. This will be things like your User Access, JWT Token Secret and access tokens.

Note: To reduce fraud or potential incidents it is recommended to encrypt any passwords that give access to your server.

TLS

TLS (Transport Layer Security) is a security protocol that ensures that data being captured on Adumo Online's payment page cannot be read by encrypting the data using two encryption keys. The Virtual solution does not require a merchant to implement TLS protocol as this is handled by Adumo Online.

Integration

Form Post URL

The form post URL is the Adumo Online URL used to submit the form post to. Adumo Online provides the following URL for both Live and Test.

Test URL : https://staging-apiv3.adumoonline.com/product/payment/v1/initialisevirtualCopy URL to clipboard

Production URL : https://apiv3.adumoonline.com/product/payment/v1/initialisevirtualCopy URL to clipboard

Note: Mode has been deprecated and should always be 1. For testing please use the staging url.

Testing

View all ApplicationUIDs

For testing purposes, we have provided a MerchantUID and ApplicationUID's in multiple currencies.

MerchantID: 9BA5008C-08EE-4286-A349-54AF91A621B0

JWT Secret: yglTxLCSMm7PEsfaMszAKf2LSRvM2qVW

3D Secure OTP/Password: Displayed on the ACS Page, otherwise try: '1234' or 'test123'

When going live, these will need to be replaced in your code by using the Adumo Online issued MerchantID and ApplicationID. You can retrieve your JWT Secret from the Merchant Portal.

Test Cards

Test Cards are used to perform test authorizations to Adumo Online. Test Cards will only work when using the test URL. Test Cards transactions will not go to the acquirer.

Test Card Types

• Visa
• MasterCard
• Amex
• Diner
• Maestro

Note: Test Cards will only work when posting to the test URL and specified ApplicationUID. Using a test card with an application other than the one it is listed with, will produce inconsistent results (e.g. Using a 3D Secure test card on the Non3D Secure application).

Note: The Frictionless cards are fully 3D Secure, but they do not display an ACS Page for the customer to complete

Non 3D Secure Test Cards (Application: 904A34AF-0CE9-42B1-9C98-B69E6329D154)

Visa Successful
Card Name	Joe Soap
Card Number	4111111111111111
Card Type	Visa
Expiry Date	Any date in future
CVV Number (last 3 digits on back of card)	any cvv
Visa Declined
Card Name	Joe Soap
Card Number	4242424242424242
Card Type	Visa
Expiry Date	Any date in future
CVV Number (last 3 digits on back of card)	any cvv
MasterCard Successful
Card Name	Joe Soap
Card Number	5100080000000000
Card Type	MasterCard
Expiry Date	Any date in future
CVV Number (last 3 digits on back of card)	any cvv
MasterCard Declined
Card Name	Joe Soap
Card Number	5404000000000001
Card Type	MasterCard
Expiry Date	Any date in future
CVV Number (last 3 digits on back of card)	any cvv
Amex Successful
Card Name	Joe Soap
Card Number	370000200000000
Card Type	AMEX
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv

Amex Declined
Card Name	Joe Soap
Card Number	374200000000004
Card Type	AMEX
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv
Diners Successful
Card Name	Joe Soap
Card Number	36135005437019
Card Type	Diners
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv
Diners Declined
Card Name	Joe Soap
Card Number	36135182434011
Card Type	Diners
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv
Maestro Successful
Card Name	Joe Soap
Card Number	5641821111166669
Card Type	Maestro
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv
Maestro Declined
Card Name	Joe Soap
Card Number	6759411100000008
Card Type	Maestro
Expiry Date	Any date in future
CVV Number(last 3 digits on back of card)	any cvv

Test CVV

As additional account security, every credit card comes with a special three or four digit code generally known as a CVV2 or CVV number. Cardholders will be requested to enter this when processing an online payment. An identity thief who has come across credit card information illegally will not have access to the CVV number if they do not have physical access of the card.

Go Live Checklist

Overview

Use the Go Live Check List to make sure that you have completed all necessary tasks before going live. Please ensure that the following criteria have been met:

Configuration

1. Virtual Form Post have been embedded onto your website

2. Merchant Payment Page have been configured in Adumo Online Portal

3. Merchant ID and Application ID of the “Merchant” (NOT test Merchant ID and Application ID) is being used in your message type.

Testing

1. Test a Successful Transaction using our Virtual Test Cards

2. Test a Decline transaction using our Virtual Test Cards

3. Test transactions are visible in Adumo Online Portal

Go Live

1. Merchant received Go Live email from Adumo Online. This email will contain the merchants Customer ID and Merchant ID .
   (If not, have merchant contact support@adumoonline.com)

2. Ensure that you are using the Live URL.

3. Perform Live transaction with Live card

Integration Support

Merchants

If you are a merchant that has signed up with Adumo Online's Virtual solution, you will have access to Adumo Online's Integration Help Desk for telephonic and email support. Telephonic support is available 8am to 5pm GMT +2. Email support is 8am to 5pm GMT + 2 and connects directly to our help desk through our ticketing system.

Developers

If you are a developer that you will have access to Adumo Online's Integration Help Desk for email support. Email support is 8am to 5pm GMT + 2 and connects directly to our help desk through our ticketing system.

If you send an email you will immediately be emailed back a reference to track your integration query.

Email: support@adumoonline.com

JSON Web Token (JWT)

What is JSON Web Token?

"JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed."

You can read more here (https://jwt.io/introduction)

You must implement the JSON Web Token (JWT) in the request to us and validate the response token (_RESPONSE_TOKEN)

We strongly recommend the following validation on the response token:

1. Confirm the signature of the JWT token is valid

2. Confirm that the values in the JWT token match with the values for the order.

3. The values that must get validated are:

   mref (Merchant Reference)

   amount

   auid (Application UID)

   cuid (Merchant UID)

4. Use the result field in the JWT token as your success and failed indicator

Warning: Failure to put the recommended JTW token validations in place could lead to financial losses.

Example JWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtdWlkIjoiMzQ4OEJGNzItMDFFNi00REU1LUI2NjAtMUZFQTdGOUE0Q0NBIiwiY3VpZCI6IjM0ODhCRjcyLTAxRTYtNERFNS1CNjYwLTFGRUE3RjlBNENDQSIsImp0aSI6IjUyMjViZmQ1NDExMWFzZGNhM2EiLCJpYXQiOjE1NTI5MTMzOTgsImV4cCI6MTU1Mzk5OTc5OH0.d8uEgDew3SiUxpe-Kyp3NqZJgJo75FlRN5G3AXohk5Y

Request Example

{
"iss": "Dev Center",
"cuid": "9BA5008C-08EE-4286-A349-54AF91A621B0",
"auid": "4196B0B8-DB88-42E5-A06D-294A5E4DED87",
"amount": "12.00",
"mref": "DEV_xUQ58CeG",
"jti": "QXiY24ZQvuPkwvU6KlDokWIgeX387MlX+M3qF8OrhRY=",
"iat": 1621936758,
"exp": 1621937358,
"notificationURL": "https://webhook-example.yourdomain.com/adumo_online/response/webhook.php"
}

Decoded Response Example

{
"jti": "[B@51c83aae",
"iat": 1612528158,
"cuid": "BAAB2819-7286-49D3-8AD3-1212B3B40C2A",
"auid": "A50376D2-0CDF-46DF-BDDD-30F0B514D853",
"result": -1,
"transactionIndex": "5bb926df-68ed-4154-bf01-cd1e7f2278a5",
"mref": "DV_LNMnOi8bUn",
"amount": "0.02",
"mode": "1",
"tkn": "",
"puid": "e36bdd6e-c9c1-4aa6-a10d-8f0ce9b6d361",
"exp": 1612528758
}

JWT(Token field) can be programatically constructed as follows:

php Example using a standalone php library

require_once('jwt.php');

  $SecretKey = 'NFeCMY17FoaDkLe3azMchsNbLOpgkO2Wh58'; //Supplied by Adumo Online

  $payloadArray = array();
  $payloadArray['iss'] = $iss; //The identity of the party that issued the JWT. The claim holds a simple string, of which the value is at the discretion of the issuer
  $payloadArray['cuid'] = $MerchantID;
  $payloadArray['auid'] = $ApplicationID;
  $payloadArray['amount'] = $amount;
  $payloadArray['mref'] = $merchantReference;
  $payloadArray['jti'] = base64_encode(random_bytes (32));
  $payloadArray['iat'] = time() - 60;
  $payloadArray['exp'] = time() + 600;
  $payloadArray['notificationURL'] =  'https://webhook-example.yourdomain.com/adumo_online/response/webhook.php?order=OrderId_12345';

  //$Token will be used to populate the Token form field in the POST to our payment page
  $Token = JWT::encode($payloadArray, $SecretKey);

  //The response token can be decoded as follows
  $decodedData = JWT::decode($jwtToken, $SecretKey, array('HS256'));

The notificationURL in the JWT will send out a webhook to the provided url in adition to the ones that is configured in your merchant portal. This can be used to send out unique per transaction webhook ntification

You can download the above sample code here (Virtual Example with JWT.zip)

You can find more code examples here (https://jwt.io/#libraries-io)

HTML Sample

If you have in‐depth HTML knowledge or web development skills you can create more variables. The below examples could be applied if you have a web application or shopping cart. The Below HTML example shows how your form POST could look when extensive information is getting sent to Adumo Online:

The below code can be copied into your code for testing purposes. Please note however, that before going live, you will need to change the details in the above example.

Reference Submit Form Post