Toggle navigation

Documentation

Version 2.0.0

Connect your platform with the Paymentez API in minutes, using SDK, payment buttons or modules, from your Mobile or Web application.


Whether you’re creating a one-off charge or saving your customer’s card details for later, using card information with Paymentez is a two-step process:

  1. Securely collect payment information using tokenization
  2. Use the payment information in a charge request or save it for later

Client-side tokenization is the method Paymentez uses to collect card information directly from your customers in a secure manner. During this process, a token representing this information is returned to your server for use in a charge request (or to save the card details for later use).

Tokenization ensures that no sensitive card data ever needs to touch your server so your integration can operate in a PCI compliant way. If any card data were to pass through or be stored on your server, you would be responsible for any PCI DSS guidelines and audits that are required.

Javascript

Example with billing_address:

Installation

You will need to include the SDK dependency payment_sdk_stable.min.js into your webpage specifying "UTF-8" like charset.

<!-- PG JS SDK -->
<script src="https://cdn.paymentez.com/ccapi/sdk/payment_sdk_stable.min.js" charset="UTF-8"></script>

Usage

Generate tokenization reference

Our library allows to you implement the easiest way a form to tokenize cards with us. Our form is dynamic and response for each card, that's mean, you only implement this form for any card type that we support.

You can implement following the next steps: 1. Create an element to contain the dynamic form. 2. Instance the PaymentGateway with the required parameters. 3. Generate the tokenization reference with the required data. generate_tokenize 4. Define the event to execute the tokenize action.

You only need to create a container and declare when you need that it will be inserted with a dynamic form with all required validations to capture the sensitive data.

<!-- Container styling example -->
<style>
  #payment_example_div {
    max-width: 600px;
    min-width: 400px;
    margin: 10 auto;
  }

  #payment_example_div > * {
    margin: 10 auto;
  }

  .tok_btn:hover {
    cursor: pointer;
  }

  .tok_btn:disabled, #tok_btn[disabled] {
    opacity: .65;
    cursor: not-allowed;
  }

  .tok_btn {
    background: linear-gradient(to bottom, rgba(140, 197, 65, 1) 0%, rgba(20, 167, 81, 1) 100%); /* W3C, IE10+, FF16+, Chrome26+, Opera12+, Safari7+ */
    color: #fff;
    width: 80%;
    border: 1px solid rgba(46, 86, 153, 0.0980392);
    border-bottom-color: rgba(46, 86, 153, 0.4);
    border-top: 0;
    border-radius: 4px;
    font-size: 17px;
    text-shadow: rgba(46, 86, 153, 0.298039) 0px -1px 0px;
    line-height: 34px;
    -webkit-font-smoothing: antialiased;
    font-weight: bold;
    display: block;
  }

  #retry_btn {
    display: none;
  }
</style>

<!--1. Create an element to contain the dynamic form.-->
<div id='payment_example_div'>
  <div id='tokenize_example'></div>
  <div id="response"></div>
  <button id='tokenize_btn' class='tok_btn'>Save card</button>
  <button id='retry_btn' class='tok_btn' display='none'>Save new card</button>
</div>

<!-- In this example, the form loads with the page, you can custom with the event you need. -->
<script>
  // Execute immediately
  (function () {
    // === Variable to use ===
    let environment = 'stg';
    let application_code = 'APP-CODE-CLIENT';  // Provided by Payment Gateway
    let application_key = 'app_key_client';  // Provided by Payment Gateway
    let submitButton = document.querySelector('#tokenize_btn');
    let retryButton = document.querySelector('#retry_btn');
    let submitInitialText = submitButton.textContent;

    // Get the required additional data to tokenize card
    let get_tokenize_data = () => {
      let data = {
        locale: 'en',
        user: {
          id: String(Math.floor((new Date).getTime() / 1000)),
          email: 'jhon@doe.com',
        },
        configuration: {
          default_country: 'COL'
        },
      }
      return data
    }

    // === Required callbacks ===
    // Executed when was called 'tokenize' function but the form was not completed.
    let notCompletedFormCallback = message => {
      document.getElementById('response').innerHTML = `Not completed form: ${message}, Please fill required data`;
      submitButton.innerText = submitInitialText;
      submitButton.removeAttribute('disabled');
    }

    // Executed when was called 'tokenize' and the services response successfully.
    let responseCallback = response => {
      // Example of success tokenization.
      //   {
      //    "card": {
      //     "bin": "411111",
      //     "status": "valid",
      //     "token": "2508629432271853872",
      //     "message": "",
      //     "expiry_year": "2033",
      //     "expiry_month": "12",
      //     "transaction_reference": "RB-143809",
      //     "type": "vi",
      //     "number": "1111"
      //   }
      // }

      // Example of failed tokenization. The error format is always the same, only the value of type, help, description changes.
      // {
      //    "error": {
      //       "type": "Card already added: 2508629432271853872",
      //       "help": "If you want to update the card, first delete it",
      //       "description": "{}"
      //    }
      // }
      document.getElementById('response').innerHTML = JSON.stringify(response);
      retryButton.style.display = 'block';
      submitButton.style.display = 'none';
    }

    // 2. Instance the [PaymentGateway](#PaymentGateway-class) with the required parameters.
    let pg_sdk = new PaymentGateway(environment, application_code, application_key);

    // 3. Generate the tokenization form with the required data. [generate_tokenize](#generate_tokenize-function)
    // At this point it's when the form is rendered on page.
    pg_sdk.generate_tokenize(get_tokenize_data(), '#tokenize_example', responseCallback, notCompletedFormCallback);

    // 4. Define the event to execute the [tokenize](#tokenize-function) action.
    submitButton.addEventListener('click', event => {
      document.getElementById('response').innerHTML = '';
      submitButton.innerText = 'Card Processing...';
      submitButton.setAttribute('disabled', 'disabled');
      pg_sdk.tokenize();
      event.preventDefault();
    });
    // };

    // You can define a button to create a new form and save new card
    retryButton.addEventListener('click', event => {
      // re call function
      submitButton.innerText = submitInitialText;
      submitButton.removeAttribute('disabled');
      retryButton.style.display = 'none';
      submitButton.style.display = 'block';
      pg_sdk.generate_tokenize(get_tokenize_data(), '#tokenize_example', responseCallback, notCompletedFormCallback);
    });

  })();

</script>

PaymentGateway Class

Contain all functionality to connect with the Payment Gateway and must be instanced with the following parameters:

Field Description Type Required
Environment Environment to operate (stg, prod) String X
Application Code Provided by the Payment Gateway String X
Application Key Provided by the Payment Gateway String X

Generate Tokenize function

Execute this function to generate the dynamic form, and insert within the specified container. Call with the following parameters:

Field Description Type Required
Tokenize data Object X
Container query selector Query selector by identify the html element String X
Response callback Callback to receive the token function X
Incomplete form callback Callback to execute when the tokenize is requested, but the form is incomplete function X

Tokenize function

Execute this function to request the tokenize, this function validate by default all data set by the client in the form. In case the data is incomplete or incorrect, the incomplete form callback will be invoked.

Tokenize Data

    let tokenize_data = {
      locale: 'en',
      user: {
        id: '117',
        email: 'jhon@doe.com',
      },
      configuration: {
        default_country: 'COL',
      }
    }
Field Description Type Required
locale Language to use (pt, es, en) String
user.id Customer identifier. This is the identifier you use inside your application String X
user.email Buyer email, with valid e-mail format String X
configuration.default_country Country in format ISO 3166-1 Alpha 3 String
configuration.icon_colour Icons color String
configuration.use_dropdowns Use dropdowns to set the card expiration date String
configuration.exclusive_types Define allowed card types String
configuration.invalid_card_type_message Define a custom message to show for invalid card types String
configuration.require_billing_address. Use billing address Boolean
configuration.require_cellphone. Use phone number Boolean


To see Checkout in action, click the button above, filling in the resulting form with:

  • Any random, syntactically valid email address (the more random, the better)
  • Any Phone Number, such as 777777777
  • Any Card Holder´s Name
  • One of Paymentez's test card numbers, such as 4111111111111111
  • Any three-digit CVC code
  • Any expiration date in the future

View working example >

Integration

The custom integration requires solid JavaScript skills.

When your page loads, you should create a handler object using paymentCheckout.modal(). You can then call open() on the handler in response to any event. If you need to abort the Checkout process—for example, when navigation occurs in a single-page application, call close() on the handler.

<!DOCTYPE html>
<html>
<head>
  <title>Example | Payment Checkout Js</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <script src="https://code.jquery.com/jquery-3.5.0.min.js"></script>
  <script src="https://cdn.paymentez.com/ccapi/sdk/payment_checkout_3.0.0.min.js"></script>
</head>
<body>
<button class="js-payment-checkout">Pay with Card</button>

<div id="response"></div>

<script>
  let paymentCheckout = new PaymentCheckout.modal({
    env_mode: "local", // `prod`, `stg`, `local` to change environment. Default is `stg`
    onOpen: function () {
      console.log("modal open");
    },
    onClose: function () {
      console.log("modal closed");
    },
    onResponse: function (response) { // The callback to invoke when the Checkout process is completed

      /*
        In Case of an error, this will be the response.
        response = {
          "error": {
            "type": "Server Error",
            "help": "Try Again Later",
            "description": "Sorry, there was a problem loading Checkout."
          }
        }
        When the User completes all the Flow in the Checkout, this will be the response.
        response = {
          "transaction":{
              "status": "success", // success or failure
              "id": "CB-81011", // transaction_id
              "status_detail": 3 // for the status detail please refer to: https://paymentez.github.io/api-doc/#status-details
          }
        }
      */
      console.log("modal response");
      document.getElementById("response").innerHTML = JSON.stringify(response);
    }
  });

  let btnOpenCheckout = document.querySelector('.js-payment-checkout');
  btnOpenCheckout.addEventListener('click', function () {
    paymentCheckout.open({
      reference: '8REV4qMyQP3w4xGmANU' // reference received for Payment Gateway
    });
  });

  window.addEventListener('popstate', function () {
    paymentCheckout.close();
  });
</script>
</body>
</html>

Configuration options

Change how Checkout looks and behaves using the following configuration options.

PaymentCheckout.modal

Parameter Required Description
env_mode yes prod, stg, local to change environment. Default is stg
onOpen no function() The callback to invoke when Checkout is opened
onClose no function() The callback to invoke when Checkout is closed
onResponse yes function(responseObject) The callback to invoke when the Checkout process is complete

responseObject

When the User completes all the Flow in the Checkout, this will be the response.

{  
   "transaction":{  
       "status":"success", // success or failure
        "id":"CB-81011", // transaction_id
        "status_detail":3 // for the status detail please refer to: https://paymentez.github.io/api-doc/#status-details
   }
}

In Case of an error, this will be the response.

{
  "error": {
    "type": "Server Error",
    "help": "Try Again Later",
    "description": "Sorry, there was a problem loading Checkout."
  }
}

PaymentCheckout.open

Parameter Required Description
reference yes Reference transaction. This is the identifier return for paymentez to call init reference, you need get reference for call.

HTTPS requirements

All submissions of payment info using Checkout are made via a secure HTTPS connection. However, in order to protect yourself from certain forms of man-in-the-middle attacks, you must serve the page containing the payment form over HTTPS as well. In short, the address of the page containing Checkout must start with https:// rather than just http://.

Supported browsers

Checkout strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

Prevent Checkout from being blocked

You can prevent Checkout's popup from being blocked by calling paymentCheckout.open when the user clicks on an element on the page. Do not call paymentCheckout.open in a callback. This design indicates to the browser that the user is explicitly requesting the popup. Otherwise, mobile devices and some versions of Internet Explorer will block the popup and prevent users from checking out.

What is 3DS2 and how it works

3D Secure 2 is the new generation of authentication technology introduced by EMVCo, a company which is collectively owned by American Express, Discover, JCB, MasterCard, UnionPay and Visa. This technology enable cardholders to authenticate themselves with their card issuer while making card-not-present (CNP) online purchases.

The new specification includes:

  •  Supports specific app-based purchases on mobile and other consumer devices
  •  Improves the consumer experience by enabling intelligent risk-based decisioning that encourages frictionless consumer authentication
  •  Delivers industry leading security features
  •  Specifies use of multiple options for step-up authentication, including one-time passcodes, as well as biometrics via out-of-band authentication
  • Enhances functionality that enables merchants to integrate the authentication process into their checkout experiences, for both app and browser-based implementations
  • Offers performance improvements for end-to-end message processing
  • Adds a non-payment message category to provide cardholder verification details to support various non-payment activities, such as adding a payment card to a digital wallet.

Unlike the previous version where shoppers are redirected to another site, in 3D Secure 2 the card issuer performs the authentication within your app or payment form. The issuing bank may verify the shopper’s identity using passive, biometric, and two-factor authentication approaches.

A transaction may go through a passive frictionless authentication flow or a challenge authentication flow where the issuer requires further interaction with a shopper.

Frictionless flow

In a frictionless flow, the acquirer, issuer, and card scheme exchanges all necessary information in the background through passive authentication using the shopper’s device fingerprint.

In your integration, you will need to get the 3D Secure 2 device fingerprint and if it is validated and approved by the issuer, the transaction is completed without further shopper interaction. (Steps 1-4 at the figure below)

Challenge flow

In the challenge flow the issuer requires additional shopper interaction for verification, either through biometrics, two-factor authentication, or similar methods.

In 3DS 2.0 the result of challenge is communicated through the DS. (Step 6 at the figure below) Thus, Merchant is informed about the authentication results via a separate channel, which is more secure.

Authentication only integration

We support 3D Secure 2 authentication for web and in-app transactions with your online payments integration.

It’s possible to perform  only the authentication.

In case of mobile, we have SDKs (Android and iOS) certificated by EMVCo, both SDKs will perform the challenge flow if needed:

For more information visit the API documentation for this case.

In a web-based integration, the flow is different:

For more information visit the API documentation for this case.

Payment with 3DS2 authentication

In this type of integration,  we will perform the authentication and proceed with the payment.

The payment could be done throw the different end points we provide, depending on the country or the type or integration. The possibles end points are: Add a card , Debit with token , Debit with credit card and Authorize

For the Add card flow, the authentication will be performed before adding  the card in our vault.

For the SDKs in Android or iOS, the flow is the following:

In a web-based integration, the flow is different:

A 3DS authentication flow starts with a payment request. Send a payment request from your server with the required 3D Secure 2 objects.

Handle the transaction based on the obtaining Status and Status detail. For example, if you received an Status Pending and Status detail 35, proceed to render the hidden iframe provided in the response,  and then submit the verify.

The possible responses after you submit the verify are:

  • Success: This means the authentication was frictionless and the payment has been authorised.
  • Pending: The issuer requires additional shopper interaction. Proceed to the challenge flow.
  • Failure: The authentication was refused or something went wrong. This response includes a refusal reason.

 

Wallet

Visa Checkout

Paymentez is a Visa Checkout partner.

Visa Checkout can enhance payment acceptance online by giving shoppers the convenience of storing payment information behind a single log in – that means they can pay without entering their shipping and account information every time.

For further information visit:

Instructions to use Visa Checkout with Paymentez

Master Pass

Simple, secure payments from one account.

No typing in your card number or shipping address. Sign up for Masterpass for faster checkout when shopping on a website, in an app, or at your favorite store using your secured payment details.

For further information visit:

Instructions to use Master Pass  with Paymentez

Bank Ticket

Users print out a receipt and go to a bank or point of sale to pay in cash. Approval takes up to 48 hours after payment.

Coming soon…

Bank Transfer

Users make a wire transfer from their bank account. Approval may take up to 72 hours.

For Colombia  we make bank transfers thru PSE. The steps are:

  1. First you need to consult the list of available  banks.
  2. Then generate bank transfer, in this step we return the bank URL.
  3. The payer must be redirected to the *bank URL* returned in above step.
  4. When the payer completes the transaction in the virtual office of his bank, he will be redirected to the url that was provided in the creation of the transaction response_url.
  5. Once the client returns to your platform, you must check the status of the transaction so that PSE closes the transaction and returns the final status. You will get the final status of the transaction in this last service and also through the webhook.

Cash Payment

Users generate a reference to pay in an institution, with which they have an agreement.

For Colombia  we generate cash payment reference which can be done in an institution with which there is an agreement (baloto, efecty, dimonex, puntored, redservi).

For Ecuador we generate cash payment reference (CIP), via PagoEfectivo. More information

The steps are:

  1. Generate a reference.
  2. Wait for the final customer to make the payment.

Tuya Cards

We have a parnership with Tuya, these is a quick start flow.

  • Add Card and Payment flow

  • Add Card, you must use our javascript then you will get a card.token, card.status, transaction.id and other information, if the client have clave temporal or clave with hard authentication the card.status will be pending( go to step 2) otherwise could be active so go to step 5.
  • If the card.status is pending the card.message should have a json with email or cell phone, then you should show one of the following messages to your client.

    Message with phone and email:

    Enviamos a tu número de celular {phone} y a tu correo electrónico {email} una clave temporal con una vigencia de un minuto, por favor ingrésala cuando la recibas. Si no es tu número de celular o correo electrónico debes actualizar tus datos personales en los centros de atención de tu entidad financiera.

    Message only with email:

    Enviamos a tu correo electrónico {email} una clave temporal con una vigencia de un minuto, por favor ingrésala cuando la recibas. Si no es tu correo electrónico debes actualizar tus datos personales en los centros de atención de tu entidad financiera.

    Message only with phone:

    Enviamos a tu número de celular {phone} una clave temporal con una vigencia de un minuto, por favor ingrésala cuando la recibas. Si no es tu número de celular debes actualizar tus datos personales en los centros de atención de tu entidad financiera.

  • Now the client must confirm the clave temporal,  so you need to implement the endpoint verify in order to activate the card.
  • On the response you will know if the card is ready for use.
  • Once the card is ready you can use it for debit method (here you will need the card.token from point 1).
  • Like step 2 depending of the card authentication you will get a status and status detail, use them to know if you need to verify the transaction or not.

Spreedly

Paymentez is one of the payment gateways Spreedly supports.

For more information visit:  Quit guide

Ones you’ve securely collected and tokenized your customer’s credit card using the Client-side tokenization you can charge the card. Unlike collection, which occurs in the browser, charge attempt are made from your server, normally using one of our client libraries.

Paymentez PHP SDK

Installation

Install via composer (not hosted in packagist yet)

composer require paymentez/sdk

 Usage

<?php

require 'vendor/autoload.php';

use Paymentez\Paymentez;

// First setup your credentials provided by paymentez
$applicationCode = "SOME_APP_CODE";
$applicationKey = "SOME_APP_KEY";

Paymentez::init($applicationCode, $applicationKey);

Once time are set your credentials, you can use available resources.

Resources availables:

  • Card
    • Available methods: getList, delete
  • Charge
    • Available methods: create, authorize, capture, verify, refund
  • Cash
    • Available methods: generateOrder

 Card

See full documentation of these features here.

List

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

Paymentez::init($applicationCode, $aplicationKey);

$card = Paymentez::card();

// Success response
$userId = "1";
$listOfUserCards = $card->getList($userId);

$totalSizeOfCardList = $listOfUserCards->result_size;
$listCards = $listOfUserCards->cards;

// Get all data of response
$response = $listOfUserCards->getData();

// Catch fail response
try {
    $listOfUserCards = $card->getList("someUID");
} catch (PaymentezErrorException $error) {
    // Details of exception
    echo $error->getMessage();
    // You can see the logs for complete information
}

Charges

See full documentation of these features here.

Create new charge

See full documentation about this here

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

// Card token
$cardToken = "myAwesomeTokenCard";

$charge = Paymentez::charge();

$userDetails = [
    'id' => "1", // Field required
    'email' => "cbenavides@paymentez.com" // Field required
];

$orderDetails = [
    'amount' => 100.00, // Field required
    'description' => "XXXXXX", // Field required
    'dev_reference' => "XXXXXX", // Field required
    'vat' => 0.00 // Field required 
];

try {
    $created = $charge->create($cardToken, $orderDetails, $userDetails);
} catch (PaymentezErrorException $error) {
    // See the console output for complete information
    // Access to HTTP code from paymentez service
    $code = $error->getCode();
    $message = $error->getMessage();
}

// Get transaction status
$status = $created->transaction->status;
// Get transaction ID
$transactionId = $created->transaction->id;
// Get authorization code
$authCode = $created->transaction->authorization_code;

Authorize charge

See the full documentation here

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

// Card token
$cardToken = "myAwesomeTokenCard";

$charge = Paymentez::charge();

$userDetails = [
    'id' => "1", // Field required
    'email' => "cbenavides@paymentez.com" // Field required
];

$orderDetails = [
    'amount' => 100.00, // Field required
    'description' => "XXXXXX", // Field required
    'dev_reference' => "XXXXXX", // Field required
    'vat' => 0.00 // Field required 
];

try {
    $authorization = $charge->authorize($cardToken, $orderDetails, $userDetails);
} catch (PaymentezErrorException $error) {
    // See the console output for complete information
    // Access to HTTP code from paymentez service
    $code = $error->getCode();
    $message = $error->getMessage();
}

// Get transaction status
$status = $authorization->transaction->status;
// Get transaction ID
$transactionId = $authorization->transaction->id;
// Get authorization code
$authCode = $authorization->transaction->authorization_code;

Capture

See the full documentation here

Need make a authorization process

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

$charge = Paymentez::charge();

$authorization = $charge->authorize($cardToken, $orderDetails, $userDetails);
$transactionId = $authorization->transaction->id;

try {
    $capture = $charge->capture($transactionId);
} catch (PaymentezErrorException $error) {
    // See the console output for complete information
    // Access to HTTP code from paymentez service
    $code = $error->getCode();
    $message = $error->getMessage();
}

// Get transaction status
$status = $capture->transaction->status;

// Make a capture with different amount
$newAmountForCapture = 1000.46;
$capture = $charge->capture($transactionId, $newAmountForCapture);

Refund

See the full documentation here

Need make a create process

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

$charge = Paymentez::charge();

$created = $charge->create($cardToken, $orderDetails, $userDetails);
$transactionId = $created->transaction->id;

try {
    $refund = $charge->refund($transactionId);
} catch (PaymentezErrorException $error) {
    // See the console output for complete information
    // Access to HTTP code from paymentez service
    $code = $error->getCode();
    $message = $error->getMessage();
}

// Get status of refund
$status = $refund->status;
$detail = $refund->detail;

// Make a partial refund
$partialAmountToRefund = 10;
$refund = $charge->refund($transactionId, $partialAmountToRefund);

 Cash

Generate order

See the all available options in here

<?php

use Paymentez\Paymentez;
use Paymentez\Exceptions\PaymentezErrorException;

$cash = Paymentez::cash();

$carrierDetails = [
    'id' => 'oxxo', // Field required
    'extra_params' => [ // Depends of carrier, for oxxo is required
        'user' => [ // For oxxo is required
            'name' => "Juan",
            'last_name' => "Perez"
        ]
    ]
];

$userDetails = [
   'id' => "1", // Field required
   'email' => "randm@mail.com" // Field required
];

$orderDetails = [
    'dev_reference' => "XXXXXXX", // Field required 
    'amount' => 100, // Field required
    'expiration_days' => 1, // Field required
    'recurrent' => false, // Field required
    'description' => "XXXXXX" // Field required
];

try {
    $order = $cash->generateOrder($carrierDetails, 
    $userDetails, 
    $orderDetails);
} catch (PaymentezErrorException $error) {
    // See the console output for complete information
    // Access to HTTP code from paymentez service
    $code = $error->getCode();
    $message = $error->getMessage();
}

// Get reference code
$referenceCode = $order->transaction->reference;
// Get expiration date
$expirationData = $order->transaction->expiration_date;
// Get order status
$status = $order->transaction->status;

Run unit tests

composer run test

Magento 2

If already have your e-commerce platform on Magento 2 we have the module for using our payments solutions.

How to install the Paymentez module for Magento 2

This module is a solution that allows Magento users to easily process payments with Paymentez.

Download and Installation

1. Execute this command for install our package:

Install the latest version. composer require paymentez/payment-gateway

Install a specific version. composer require paymentez/payment-gateway:2.3.1

Once the installation finished, continue with the next commands in your bash terminal.

2. Update dependency injection:

php bin/magento setup:di:compile

3. Update modules registry:

php bin/magento setup:upgrade

Optional.- This command is optional for production environments:

php bin/magento setup:static-content:deploy

Now you can see the Paymentez settings in this path Stores > Configuration > Sales > Payment Methods on your Magento admin dashboard.

Maintenance

If you need update the plugin to latest version execute: composer update paymentez/payment-gateway or composer require paymentez/payment-gateway:2.3.1 for specific version.

Webhook Notifications and Order Updates

Every time a transaction changes their status you will get an HTTP POST request from Paymentez to your webhook.

The URL that will be used for the order updates via webhook is: https://magentodomain.com/rest/V2/webhook/paymentez

This URL will be configured on Paymentez.

The Magento 2 configuration should look like this:

Configuration for LinkToPay:

WooCommerce

Paymentez Payment Gateway Plugin for WooCommerce

This is a Wordpress plugin prepared to work as a payment gateway for another plugin called WooCommerce.

1.- Prerequisites

1.1.- XAMPP, LAMPP, MAMPP, Bitnami or any PHP development environment

  • XAMPP: https://www.apachefriends.org/download.html
  • LAMPP: https://www.apachefriends.org/download.html
  • MAMPP: https://www.mamp.info/en/mac/
  • Bitnami: https://bitnami.com/stack/wordpress

1.2.- Wordpress

If you already install the Bitnami option, this step can be omitted.

The documentation necessary to install and configure Wordpress is at the following link:

https://wordpress.org/support/article/how-to-install-wordpress/

All the minimum requirements (PHP and MySQL) must be fulfilled so that the developed plugin can work correctly.

1.3.- WooCommerce

The documentation needed to install WooCommerce is at the following link:

https://docs.woocommerce.com/document/installing-uninstalling-woocommerce/

There you will also find information necessary for troubleshooting related to the installation.

1.4.- WooCommerce Admin

The documentation needed to install WooCommerce is at the following link:

https://wordpress.org/plugins/woocommerce-admin/

There you will also find information necessary for troubleshooting related to the installation.

2.- Git Repository

You can download the current stable release from: https://github.com/paymentez/pg-woocommerce-plugin/releases

3.- Plugin Installation

The development works like a Wordpress plugin that connects to another Wordpress plugin, WooCommerce.

So when it is installed and activated, WooCommerce and Wordpress hooks and actions are used.

3.1 Installation and Activation Through Wordpress Admin

When we have the project compressed in .zip format, we proceed to the installation through Wordpress Admin.

  1. The first step will be to login into Wordpress Admin as administrator.

  2. Being in the main screen of the admin we click on the Plugins tab.

  3. Within the Plugins screen we click on Add New.

  4. Within the Add Plugins screen we click on Upload Plugin.

  5. The option to upload our plugin in .zip format will be displayed. We upload it and click on the Install Now button.

  6. We will be redirected to the plugin installation screen. We wait to get the message Plugin installed successfully and click on the Activate Plugin button.

  7. We will be redirected to the Plugins screen where we will see our plugin installed and activated.

3.2.- Languages

The language of the plugin is dynamically selected according to the language that is configured in Wordpress. The languages that are available are: - Spanish - Spanish MX - Spanish CO - Spanish PE - Spanish EC - Spanish LA - Portuguese - Portuguese BR

4. Activation and Configuration of the Plugin in WooCommerce

After having installed our plugin in Wordpress we must proceed to configure it in the WooCommerce admin.

This is found in the WooCommerce tab of the main WordPress admin. Then we click on the Settings option and later on the Payments tab.

4.1 Payment Gateway Activation

To activate our payment gateway within WooCommerce we need to be within WooCommerce -> Settings -> Payments and we will see our plugin installed and detected.

To enable it we must activate the Enabled button. This enablement is different from that of Wordpress which we did previously.

4.2 Gateway Settings in WooCommerce Admin

By enabling our plugin in the WooCommerce admin, we will have some options to configure. To do this we click on the Manage button that will appear on the side of our plugin.

The options to configure are the following:

  • Staging Environment: When enabled, the plugin will point to the Paymentez staging server.

  • Enable LinkToPay: If selected, LinkToPay(Bank transfer, cash) can be used to pay.

  • Title: This option configures the text that the customer will see in the checkout window next to the Paymentez logo.

  • Customer Message: This option configures the message that the customer will see in the checkout window when they select Paymentez as the payment method.

  • Checkout Language: This option selects the language that will be displayed in the checkout window. The available options are Spanish, Portuguese and English (by default).

  • Installments Type: Select the installments type that will be enabled on the payment screen (Only on card payment).

  • App Code Client: Unique identifier in Paymentez.

  • App Key Client: Key used to encrypt communication with Paymentez.

  • App Code Server: Unique identifier on the Paymentez server.

  • App Key Server: Key used for communication with the Paymentez server.

5.- Selecting the Plugin in the Store Checkout

When we have all our plugin activated and configured in WooCommerce, we will see it available to be selected by customers on the Checkout page of our store.

Just select it, fill in the Billing Details and click on the Place Order button.

By clicking we will arrive at the Order-Pay or Pay For Order window in which we will see a summary of our order. The Purchase button will be displayed which will open the payment checkout.

6. Process to make a Refund

The refund process will start in the main Wordpress admin window.

We select the WooCommerce tab and click on the Orders option.

We select the order that we want to refund and the Edit Order window will open.

In the item detail we will find the Refund button, we click and the refund options will be displayed.

We type the amount to be reimbursed and click the Refund via Paymentez button. The status within WooCommerce will change and so will the status on the gateway.

7. Webhook Configuration

The plugin includes the functionality of a webhook to receive the transaction updates that are made. This webhook receives transaction notifications and updates them in the WooCommerce admin and database.

To configure it, the merchant must provide its Paymentez commercial advisor with the address where the webhook is installed, it will be in the following format: https://{{URL-COMMERCE}}/wp-json/paymentez/webhook/v1/params.

VTEX

Tenemos implementada la solución eCommerce VTEX + Paymentez

Cómo configurar Paymentez v2

Para estas instrucciones se dará por hecho que el encargado de VTEX por parte del comercio, conoce bien el panel de administración.

Se deben de seguir los siguientes pasos:

  1. Entrar a la configuración del apartado de pagos.

  2. Seleccionar la pestaña de Gateway Affiliations y agregar una pulsando sobre el botón de más.

  3. Dentro de lista ordenada alfabéticamente de OTHERS, se debe buscar el conector con nombre PaymentezV2.

  4. Una vez seleccionado el conector, se debe configurar, donde Application Key es el Application Code proporcionado por Paymentez y el Application Token es el Application Key proporcionado por Paymentez. Se puede especificar ahí mismo, el ambiente al cual se desea apuntar, quedando Live/Production para ambiente de producción y Test para el ambiente de staging. Quedando de la siguiente manera:

  5. Una vez configurada la afiliación. Esta se puede asignar para el medio de pago que seleccione el administrador.

Cómo configurar Paymentez v2 para una franquicia ya establecida

Tomar en cuenta que al asignar la afiliación a una franquicia ya establecida, TODAS las transacciones con esa franquicia se procesarán con Paymentez.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Payment Conditions, agregar una nueva condición dando clic al botón de más.

  3. Seleccionar la franquicia que se desea procesar con Paymentez

  4. Una vez seleccionada la franquicia, se debe asignar un nombre a la condición y seleccionar la afiliación de Paymentezv2

  5. Sobre seleccionar pago completo o pago en cuotas, esto queda a decisión y conocimiento del administrador VTEX del comercio.

Cómo configurar Paymentez v2 para Cash

Tomar en cuenta que al asignar la afiliación a una franquicia ya establecida, TODAS las transacciones con esa franquicia se procesarán con Paymentez.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Payment Conditions, agregar una nueva condición dando clic al botón de más.

  3. Dentro de OTHER existe la opción Cash, seleccionar esta

  4. Seleccionar la afiliación configurada de Paymentez.
  5. Sobre asignar condiciones especiales para el pago queda a decisión y conocimiento del administrador VTEX del comercio.

Cómo configurar Paymentez v2 para PSE (Solo Colombia)

PSE es un medio de pago que no aparece dentro de las opciones existentes de VTEX, por esto es necesario crearlo a través de un Promissories.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Custom Payments, agregar una nueva condición dando clic a una casilla de Config.

  3. Dentro de la configuración, se debe asignar el nombre PSE (este nombre es completamente requerido ya que se usa para identificar el medio de pago por parte del conector). En tiempo de expiración, es requerido el 2, ya que de lado de Paymentez se dan dos días para que el cliente final pueda pagar. Los datos deben quedar como se muestra en la imagen.

  4. Seleccionar la afiliación configurada de Paymentez.

  5. Sobre asignar condiciones especiales para el pago queda a decisión y conocimiento del administrador VTEX del comercio.

Cómo configurar Paymentez v2 para LinkToPay

LinkToPay es un medio de pago que no aparece dentro de las opciones existentes de VTEX, por esto es necesario crearlo a través de un Promissories.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Custom Payments, agregar una nueva condición dando clic a una casilla de Config.

  3. Dentro de la configuración, se debe asignar el nombre LinkToPay (este nombre es completamente requerido ya que se usa para identificar el medio de pago por parte del conector). En tiempo de expiración, es requerido el 2, ya que de lado de Paymentez se dan dos días para que el cliente final pueda pagar. Los datos deben quedar como se muestra en la imagen.

  4. Seleccionar la afiliación configurada de Paymentez.

  5. Sobre asignar condiciones especiales para el pago queda a decisión y conocimiento del administrador VTEX del comercio.

Prestashop

Paymentez Payment Gateway Plugin for Prestashop

1. Prerequisites

1.1. XAMPP, LAMPP, MAMPP, Bitnami or any PHP development environment

  • XAMPP: https://www.apachefriends.org/download.html
  • LAMPP: https://www.apachefriends.org/download.html
  • MAMPP: https://www.mamp.info/en/mac/
  • Bitnami: https://bitnami.com/stack/prestashop

1.2. Prestashop

Warning, if you already install the Bitnami option this step can be omitted.

Prestashop is an e-commerce solution, it's developed on PHP. Now the last stable version is the 1.7.X. - Download: https://www.prestashop.com/en/download - Install Guide: https://www.prestashop.com/en/blog/how-to-install-prestashop

2. Git Repository

You can download the current stable release from: https://github.com/paymentez/pg_prestashop_plugin/releases

3. Plugin Installation on Prestashop

  1. First, we need to download the current stable release of Paymentez Prestashop plugin from the previous step.
  2. We need to unzip the file to get the pg_prestashop_plugin-2.0.0 folder.
  3. Now you rename the folder from pg_prestashop_plugin-2.0.0 to pg_prestashop_plugin.
  4. Compress on zip format the folder to get a file called pg_prestashop_plugin.zip.
  5. We need to log in to our Prestashop admin page.
  6. Now we click on Improve -> Modules -> Module Manager
  7. In the Module manager we click on the Upload a mudule button
  8. We click on select file, or we can Drop the Paymentez Prestashop plugin folder on .zip or .rar format.
  9. We will wait until the Installing module screen changes to Module installed!.
  10. Now we can click on Configure button displayed on the screen or in the Configure button displayed on the Payment section on the Module manager.
  11. Inside the Payment Gateway Configurations we need to configure or CLIENT/SERVER credentials provided by Paymentez, we can select the Checkout Language that will be displayed to the user, also we need to select an Environment, by default STG(Staging) is selected.
  12. Congrats! Now we have the Paymentez Prestashop plugin correctly configured.

4. Considerations and Comments

4.1. Refunds

  • The 2.0.0 plugin version does not support the Partial Refunds by Prestashop. However, the plugin supports Standard Refunds by Prestashop.
  • The Standard Refund can be interpreted as a partial refund on Paymentez side, a success refund operation depends on the configured payment network accepting partial refunds.

4.2. Webhook

  1. Login into the Prestashop Back-office.
  2. Navigate to Advance Parameters -> Web Services menu options to open the Web Services page.
  3. It will redirect to the Web Services page having the listing of available Webservices, and the configuration form to configure the service.
  4. We need to enable the field called Enable Prestashop webservice.
  5. Click on Save button.
  6. Click on the Add new web service key button to add new web service key to access only to the certain resources of the Prestashop store.
  7. We need to configure the Key, this is a unique key. You can enter it manually or click on the Generate button to generate a random key for the web service.
  8. We also configure the Key Description, you can provide the description regarding the key for better understanding.
  9. We will set the Status on Enable to provide a grant to access the data using the key.
  10. Finally, we need to configure the Permission field to provide the permission to access the data using the certain key. Here we need to search the resourde called paymentezwebhook and select the Add (POST) checkbox.
  11. The webhook its located on https://{mystoreurl}/api/paymentezwebhook?ws_key=KEY_GENERATED_ON_STEP_6.
  12. You need to give this URL to your Paymentez agent..

Instalación Impresora Bematech/Aldelo Versión 1.8

 

 

Prerrequisitos

  • Impresora Bematech Instalada MP4200TH con USB.
  • Windows 7, Windows 8, Windows Server 2003 R2 (32-Bit x86), Windows Server 2003 R2 x64 editions, Windows Server 2008 R2, Windows Server 2008 Service Pack 2, Windows Vista Service Pack 1, Windows XP Service Pack 3Tan solo es posible usar el motor de base de datos de Access de 32 bits en Windows XP Service Pack 3.

Instalación

1. – Dentro de la carpeta del zip  revisar si se encuentran los 2 archivos:

  • PaymentezSetup.msi
  • setup.exe

2.- Ejecutar setup.exe y seguir todos los pasos que se indican. Cuando pregunte permisos seleccione “Everyone”

3.- Al finalizar verá los accesos directos en Inicio-> Programas->Paymentez y en la carpeta Program Files->Microsoft->PaymentezSetup.

La instalación comprende de los siguientes archivos ejecutables

  • PaymentezConfig: Para crear la configuración inicial
  • PaymentezTray: Proceso que corre en background para levantar el monitor y conexiones
  • PaymentezService: El servicio que se conecta con la bd del POS
  • PaymentezMonitor: Monitor donde se observan las órdenes.
  • PaymentezVPN: Canal de comunicación entre middleware y este cliente.

4.- Como es una nueva instalación debemos de ejecutar PaymentezConfig (ó Configure). Aparecerá una ventana como esta:

Seleccionamos el modo de instalación. A continuación se presentan las opciones que se verán en cada uno de los modos

ALDELO:

Favor de ingresar con el teclado el id de middleware de la tienda y dar Enter. Una vez realizado esto se puede cerrar la ventana con Esc o con un segundo Enter.

 

PRINTER:

Al seleccionar Printer, deberán ingresar el id del store en middleware, el país, el puerto donde esta conectada la impresora y el tamaño de papel. Actualmente solo se soporta 2 tamaños 58mm y 76mm.

 

 

5.- Ir a Inicio->Buscar->Servicios . Seleccionar Paymentez Service, y con botón derecho del mouse se mostrará un menú con las siguientes opciones

Seleccionar start o iniciar.

6.- Ejecutar PaymentezTray. Este se ocultará en el tray que esta cerca de la hora y fecha. Como muestra la imagen.

 

7.- En PaymentezTray Dar click en abrir monitor. El tray debe quedar así:

Favor de checar que los datos de storeid estén correctos

Listo, las órdenes se mostrarán en esa pantalla

En middleware, en store con pos_server_url actualizar la url a esto http://middleware.paymentez.com:8446/prod_xxx/Paymentez/Service  donde xxx es el id de la tienda,  ejemplo si el id es 20,  La url final es  http://middleware.paymentez.com:8446/prod_20/Paymentez/Service

 

Desinstalación

1.- Abrir el Task Manager o Administrador de Tareas.

2.- En procesos, terminar los siguientes procesos (Sí es que están presentes). Es importante cerrarlos en este orden:

  1. PaymentezTray
  2. PaymentezVPN
  3. PaymentezMonitor
  4. PaymentezService

3.- Ir a Panel de Control -> Agregar/Quitar Programas. Buscar PaymentezSetup y darle desinstalar.