In this section you will find all the information required to be able to integrate AddonPayments payments platform to your website. Accept payments with cards, wallets, and many local payment methods on your website and mobile app.

Give your shoppers the option to pay with their preferred payment method, all with a great payment user experience. With AddonPayments you can:

Dynamically offer payment methods based on transaction details such as country code, currency, or any other parameter you can define. Choose how to integrate based on your customization requirements. Store preferred shoppers payment methods to maximize conversion. Everything is ready to start accepting online payments but first,

AddonPayments offer different integrations which will enable you to achieve different payment user experiences.

Take into account the customisation details you want to achieve to choose wisely the best fitting path for you. Select an integration option to and we will tell you more about our PCI-compliant solution:

AddonPayments JavaScript

Seamless payments experience with maximum customization options

AddonPayments HostedPayments

Secure and out of the box User Interface ready to accept payments.

Plugin integrations

Use our plugins to accept payments on leading technology platforms such as:

• Prestashop
• Magento
• WooCommerce

Or you can refer to our AddonPayments API reference for full control on the User Interface and User Experience.

First of all its important to choose which integration type fits your purposes and after that we really recommend you to register to our platform to access the backoffice and Conection keys.

Onboarding

During the onboarding process, AddonPayments will send you credentials and whitelist your IP addresses and domains that you will use to communicate with the AddonPayments backend. You must provide EPG with the following information:

• IP Addresses - The IP addresses of the backend servers in your production environment.
• Domains - The domain names of your front end systems. AddonPayments supports multiple domains for your development, testing, and production environments.

The AddonPayments Hosted integration provides a hosted payment form and a set of REST API resources for accepting payments on your website, managing recurring payments and previous transactions, and running reports. This documentation describes how to set up and use the AddonPayments Hosted integration and defines the available REST API endpoints in detail. All requests to the AddonPayments APIs must be encrypted. See the Encryption for details. Because the payment form is hosted by AddonPayments, your business does not need to maintain PCI compliance or maintain up to date payment method definitions.

gdgfdgd

gfdg

Requesting a payment form requires you to build, encrypt, and send a POST request to the AddonPayments gateway. All requests to AddonPayments gateway must be encrypted for security. See the Encryption section for details.

The parameters required by AddonPayments change depending on the payment method your customer uses. See the AlternativePaymentMethods API docs for further detail. Use the sample code below to build a request string, encrypt the string, and submit it to the platform.

AddonPayments will validate the IP address that submits the request before attempting to decrypt and validate the payload.

Go to Request Payment Form for more information.

The Hosted Payment resource returns a URL for the payment form as a string in the response. Use an iFrame on your site to display the URL, or redirect your customer to the URL. The URL is returned as a string in the body of the response. The following URL is an example. The actual URL will be unique for your payment form:

https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/detokenizer/7586e75d-cdbb-415a-9267-f04dd6d7ff48

Remember to redirect your client to the url or to embed the url into an iFrame. The image below shows a basic, unformatted payment form:

When your customer submits the payment, AddonPayments processes the transaction and sends the transaction status to the statusURL you send in the request.

AddonPayments redirects your customer to the appropriate URL you sent in the request, depending on the transaction status.

Capture the transaction status and any other details you need to keep for your records or process transactions in the future.

Refer to the response payload, go to Response Fields section.

Once the payment has been completed, AddonPayments will redirect the custome to one of the final url fields that specified in the Request Payment Form section.

If you supplied values for the successURL, errorURL, cancelURL or awaitingURL parameters with your request, AddonPayments will redirect your customer to the appropriate site, based on the status of the transaction. This feature is useful for displaying customer-specific pages related to the response.

successURL

The URL of the site to display if the transaction is successful.

Hardly Recommended for Hosted Integration

errorURL

The URL of the site to display if the transaction fails or declines.

Hardly Recommended for Hosted Integration

cancelURL

The URL of the site to display if the customer cancels the transaction.

awaitingURL

the URL of the site to display when an external solution requires a asynchronous notification to confirm the status of the payment. For instance Bank payment.

AddonPayments allows customize the payment form sending some parameters in the Payment Form Request.

Go to Hosted Style Fields for more details.

Note: Remember to add these fields in the encryption parameters.

Custom CSS

AddonPayments makes it easy to customize the appearance of the payment form using a merchant’s CSS file. Mechant can create a CSS file that defines the look and feel for the different elements of the payment form and just need to report the cssURL parameter in the payment requests.

1. Send the CSS file to AddonPayments.
2. AddonPayments validates the CSS file for security and functionality. AddonPayments will work with you if your CSS file needs any modifications.
3. AddonPayments applies the styles to the payment form when you display it.

You can define separate CSS files for each product you offer. AddonPayments uses the merchantId and productId parameters that you send with the Direct Payment request to link the CSS file to the payment form.

You can use any class names or other values in your CSS files. AddonPayments will work with you to make sure that the styles are applied to the payment form correctly.

The request scenarios for merchants using the Host-To-Host API are the same than for those merchants using the checkout API. The difference between these merchants is that with the Direct Payment API, the customer is not redirected to a checkout page and no iframe is required, in other words, the merchant hosts the entire checkout process. The request and the response are done directly from server to server. There are also some additional parameters that the merchant will have to send when using this API such as the exact payment solution required along with the account details of the customer for this solution.

For example, if the merchant would like the customer to make a transaction using credit cards, the merchant would have to pass the customer’s credit card details as part of this request. AddonPayments would then make a direct request to the appropriate provider to process the transaction and would respond immediately to the merchant with the result as well as a token representing the card number . The same can be done with any other payment solution that does NOT require a customer redirect .

Remember some payment solutions DO require a redirect, in which case AddonPayments will respond with a URL. In this case the merchant will have to redirect the customer to the URL provided. AddonPayments will then take over and will send the result back to the merchant.

Follow the steps below to perform a basic transaction using the AddonPayments Host-To-Host integration. Each of these steps is described in detail in the corresponding sections of this documentation:

1. Website - Build a website with a form that collects payment and customer information.
2. Build, Encrypt, and Submit the Transaction Request - Once you have collected the required data from your customer, you must format and encrypt it. Send a POST request with the encrypted transaction data in the body of the request to the Direct Payment resource.
3. Handle the response - The response message from AddonPayments includes transaction status information and any details required to redirect your customer.

The merchant builds a website with a form for collecting your customer’s payment and identification details.

Depending on the payment solution, the parameters could be different. So EPG hardly recommend to check the Encryption Field page and contact with your account manager form more details.

For instance, a credit card transaction form must collect the following information:

• Amount
• Country
• Currency
• Card Number
• Cardholder Name
• Expiration Date
• CVN Number

The values for all required parameters should come from your backend systems. See the Direct Payment resource definition for more details.

All requests to the EPG API must be encrypted, following the encryption steps, click for more details, Encryption.

1. Concatenate the parameters into a single string with the following format:

param1=value1&param2=value2…&paramN=valueN

2. Hash your merchant password using the MD5 algorithm. You will set your merchant password with EPG when you set up your account.
3. Encrypt the parameter string using the AEScipher algorithm. Use your hashed merchant password as the key.
4. Hash the unencrypted parameter string using the SHA256 algorithm. This hashed value will serve as an integrity check after EPG decrypts the parameters.
5. Concatenate the encrypted parameter string, the integrity check value, and your hashed merchant password using the following format:

encrypted=ENCRYPTED_PARAMETER_VALUES&integrityCheck=INTEGRITY_CHECK_VALUE&merchantId=MERCHANT_ID

6. Submit the string to the endpoint in the request body.

Once you have the parameter string, submit it as POST request to the Direct Pay endpoint.

Sample code

The sample code below encrypts and posts the Direct Pay request:

ESTE EJEMPLO NO ES DE CBC, <<HAY QUE REEMPLAZARLO POR UNO DE CBC

  using System;
  using System.Collections.Generic;
  using System.Linq;
  using System.Text;
  using System.Threading.Tasks;
  using System.Security.Cryptography;
  using System.Net;
  using System.IO;
  using System.Web;



  namespace ConsoleApplication1
  {
      class Program
      {

          static void Main(string[] args)
          {
              string merchantId = "MERCHANT-ID";
              string key = "MERCHANT-PASSWORD";

              string data = "operationType=debit&merchantId="+merchantId+"&customerId=19&customerEmail=test.staging@mm.com&amount=20.0&description=debit&country=MT&currency=EUR&addressLine1=1, test Str&city=Sliema&postCode=12345&telephone=99999999&firstname=test&lastname=Staging&customerCountry=GB&merchantTransactionId=2015060110fds00163&productId=4354353&language=en&dob=31-12-1970";



              string encrypted = AesEncryption(data, key);
              string integrityCheck = sha256_hash(data);
              string URI = "https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/pay"; 



              string myParameters = "encrypted=" + UTF8Encoding(encrypted) + "&integrityCheck=" + integrityCheck + "&merchantId="+ "1073";

              string HtmlResult = "response";
              using (WebClient wc = new WebClient())
              {
                  wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
                  HtmlResult = wc.UploadString(URI, myParameters);
              }
              Console.Write(HtmlResult);
          }



          public static String UTF8Encoding(String data)
          {
              return System.Net.WebUtility.UrlEncode(data);
          }

          public static string GetSha256Hash(string data)
          {
              System.Security.Cryptography.SHA256Managed crypt = new System.Security.Cryptography.SHA256Managed();
              System.Text.StringBuilder hash = new System.Text.StringBuilder();
              byte[] crypto = crypt.ComputeHash(Encoding.UTF8.GetBytes(data));

              foreach (byte bit in crypto)
              {
                  hash.Append(bit.ToString("x2"));
              }

              return hash.ToString();
          }

          public static String sha256_hash(String value)
          {
              using (SHA256 hash = SHA256Managed.Create())
              {
                  return String.Join("", hash
                    .ComputeHash(Encoding.UTF8.GetBytes(value))
                    .Select(item => item.ToString("x2")));
              }
          }

          public static string AesEncryption(string data, string key)
          {
              AesManaged aes = new AesManaged();
              aes.Key = Encoding.UTF8.GetBytes(key);
              aes.Mode = CipherMode.ECB;
              aes.Padding = PaddingMode.PKCS7;
            //  aes.KeySize = 256;
             // aes.BlockSize = 128;
              //aes.IV = new byte[16];

              ICryptoTransform crypt = aes.CreateEncryptor();
              byte[] encBytes = Encoding.UTF8.GetBytes(data);
              byte[] resultBytes = crypt.TransformFinalBlock(encBytes, 0, encBytes.Length);

              return Convert.ToBase64String(resultBytes);
          }
      }
  }

AddonPayments will validate the IP address that submits the request before attempting to decrypt and validate the payload.

The Direct Pay resource sends a response to the URL defined by the statusURL parameter that you sent as part of the request. The response includes transaction status information and a cardNumberToken. Save the cardNumberToken and any additional customer details. You can use these values to submit future transactions to AddonPayments.

The sample below shows a response from the Direct Payment resource:

    <!-- this is a XML of a paypal transaction.. our responses are in xml and we need to add a creditcard transaction. I will provide one when we have that call if you want -->
    <payfrex-response>
      <message>string</message>
      <operations>
        <operation>
          <amount>12.34</amount>
          <currency>EUR</currency>
          <details/>
          <merchantTransactionId>481561</merchantTransactionId>
          <message>The operation was successfully processed.</message>
          <operationType>DEBIT</operationType>
          <optionalTransactionParams>Credit card payment</optionalTransactionParams>
          <EPGTransactionID>11245432gf</EPGTransactionID>
          <paySolTransactionId>3r523fd</paySolTransactionId>
          <paymentSolution>Paypal</paymentSolution>
          <status>SUCCESS</status>
        </operation>
      </operations>
      <optionalTransactionParams>Paypal transaction</optionalTransactionParams>
      <status>SUCCESS</status>
      <workFlowResponse>
        <id>3383</id>
        <name>PP Workflow</name>
        <version>3</version>
      </workFlowResponse>
    </payfrex-response>

Additional features of the Direct Payment resource are described in the Direct Payment Resource Overview section. The Direct Pay resource definition includes additional details.

1. Collect the values for the parameters required by the request. See the Endpoint Definitions for definitions of these parameters you must encrypt depending on the operation you intend to perform. Concatenate the parameters into a single string with the following format:

param1=value1&param2=value2…&paramN=valueN

2. Set your merchant password with EPG when you set up your account. Then, hash the password using md5 algorithm and provide the result to your Account Manager.

For example: https://www.md5online.org

3. Encrypt the parameter string

   • Encrypt using the AEScipher algorithm on mode CBC.
   • Generate an Initial Vector (a random byte array whose length must be 16) and use it with your hashed merchant password to encrypt.

4. Hash the unencrypted parameter string using the SHA256 algorithm. This hashed value will serve as an integrity check after EPG decrypts the parameters.

For example: https://codebeautify.org/sha256-hash-generator

5. Encode with UTF-8 and concatenate the encrypted parameter string, the integrity check value, and your hashed merchant password using the following format:

encrypted=ENCRYPTED_PARAMETER_VALUES&integrityCheck=INTEGRITY_CHECK_VALUE&merchantId=MERCHANT_ID

6. Set header parameters:

   • encryptionMode: CBC
   • iv: Initial Vector value, encoded on base64.
   • apiVersion: 3

7. Submit the string to the endpoint in the request body.

   • AddonPayments will validate the IP address that submits the request before attempting to decrypt and validate the payload.