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

Github Repository

PaymentezJS is a library that allows developers to easily connect to the Paymentez CREDITCARDS API

View working example >

Installation

You will need to include jQuery and both paymentez.min.js and paymentez.min.css into your web page.

<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>

<link href="https://cdn.paymentez.com/js/1.0.1/paymentez.min.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.paymentez.com/js/1.0.1/paymentez.min.js"></script>

Usage

For working examples of using PaymentezJS, see the examples folder of this project.

Using the Paymentez Form

Any elements with the class paymentez-form will be automatically converted into a basic credit card input with the expiry date and CVC check.

The easiest way to get started with PaymentezForm is to insert the snippet of code:

<div class="paymentez-form" id="my-card" data-capture-name="true"></div>

To get a Card object from the PaymentezForm, you ask the form for its card.

var myCard = $('#my-card');
var cardToSave = myCard.PaymentezForm('card');
if(cardToSave == null){
  alert("Invalid Card Data");
}

If the returned Card is null, error states will show on the fields that need to be fixed.

Once you have a non-null Card object from the widget, you can call addCard.

Init library

You should initialize the library.

/**
  * Init library
  *
  * @param env_mode `prod`, `stg`, `dev`, `local` to change environment. Default is `stg`
  * @param paymentez_client_app_code provided by Paymentez.
  * @param paymentez_client_app_key provided by Paymentez.
  */
Paymentez.init('stg', 'PAYMENTEZ_CLIENT_APP_CODE', 'PAYMENTEZ_CLIENT_APP_KEY');

addCard

addCard converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.

/* Add Card converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.
 *
 * @param uid User identifier. This is the identifier you use inside your application; you will receive it in notifications.
 * @param email Email of the user initiating the purchase. Format: Valid e-mail format.
 * @param card the Card used to create this payment token
 * @param success_callback a callback to receive the token
 * @param failure_callback a callback to receive an error
 */
Paymentez.addCard(uid, email, cardToSave, successHandler, errorHandler);

var successHandler = function(cardResponse) {
  console.log(cardResponse.card);
  if(cardResponse.card.status === 'valid'){
    $('#messages').html('Card Successfully Added<br>'+
                  'status: ' + cardResponse.card.status + '<br>' +
                  "Card Token: " + cardResponse.card.token + "<br>" +
                  "transaction_reference: " + cardResponse.card.transaction_reference
                );    
  }else if(cardResponse.card.status === 'review'){
    $('#messages').html('Card Under Review<br>'+
                  'status: ' + cardResponse.card.status + '<br>' +
                  "Card Token: " + cardResponse.card.token + "<br>" +
                  "transaction_reference: " + cardResponse.card.transaction_reference
                ); 
  }else{
    $('#messages').html('Error<br>'+
                  'status: ' + cardResponse.card.status + '<br>' +
                  "message Token: " + cardResponse.card.message + "<br>"
                ); 
  }
  submitButton.removeAttr("disabled");
  submitButton.text(submitInitialText);
};

var errorHandler = function(err) {    
  console.log(err.error);
  $('#messages').html(err.error.type);    
  submitButton.removeAttr("disabled");
  submitButton.text(submitInitialText);
};

The third argument to addCard is a Card object. A Card contains the following fields:

  • number: card number as a string without any separators, e.g. '4242424242424242'.
  • holder_name: cardholder name.
  • expiry_month: integer representing the card's expiration month, e.g. 12.
  • expiry_year: integer representing the card's expiration year, e.g. 2013.
  • cvc: card security code as a string, e.g. '123'.

getSessionId

The Session ID is a parameter Paymentez use for fraud purposes. Call this method if you want to Collect your user's Device Information.

var session_id = Paymentez.getSessionId();

Once you have the Session ID, you can pass it to your server to charge the user.

PaymentezForm Complete Reference

Manual Insertion

If you wish to manually alter the fields used by PaymentezForm to add additional classes or set the input field placeholder, name or id. you can pre-populate the form fields as show below.

This could be helpful in case you want to Render the Form in another Language (by default the Form is Rendered in Spanish), or to reference some input by name or id.

For example if you want to render the form in English and add a custom class to the card-number

<div class="paymentez-form">
  <input class="card-number my-custom-class" name="card-number" placeholder="Card number">
  <input class="name" id="the-card-name-id" placeholder="Card Holders Name">
  <input class="expiry-month" name="expiry-month">
  <input class="expiry-year" name="expiry-year">
  <input class="cvc" name="cvc">
</div>

Reading Values

PaymentezForm provides functionality allowing you to read the form field values directly with JavaScript. This can be useful if you wish to submit the values via Ajax.

Create a PaymentezForm element and give it a unique id (in this example my-card)

<div class="paymentez-form" id="my-card" data-capture-name="true"></div>

The javascript below demonstrates how to read each value of the form into local variables.

var myCard = $('#my-card');

var cardNumber = myCard.PaymentezForm('cardNumber');
var cardType = myCard.PaymentezForm('cardType');
var name = myCard.PaymentezForm('name');
var expiryMonth = myCard.PaymentezForm('expiryMonth');
var expiryYear = myCard.PaymentezForm('expiryYear');
var cvc = myCard.PaymentezForm('cvc');

Functions

To call a function on a PaymentezForm element, follow the pattern below. Replace the text 'function' with the name of the function you wish to call.

$('#my-card').PaymentezForm('function')

The functions available are listed below:

Function Description
card Get the card object
cardNumber Get the card number entered
cardType Get the type of the card number entered
name Get the name entered
expiryMonth Get the expiry month entered
expiryYear Get the expiry year entered
cvc Get the CVC entered

CardType Function

The cardType function will return one of the following strings based on the card number entered. If the card type cannot be determined an empty string will be given instead.

Card Type
AMEX
Diners
Diners - Carte Blanche
Discover
JCB
Mastercard
Visa
Visa Electron

Static functions

If you just want to perform simple operations without the PaymentezForm form, there are a number of static functions provided by the PaymentezForm library that are made available.

Card Type from Card Number

var cardNumber = '4242 4242 4242 4242'; // Spacing is not important
var cardType = PaymentezForm.cardTypeFromNumber(cardNumber);

Cleaning and Masking

// var formatMask = 'XXXX XXXX XXXX XXXX'; // You can manually define an input mask
// var formatMask = 'XX+X X XXXX XXXX XXXX'; // You can add characters other than spaces to the mask
var formatMask = PaymentezForm.CREDIT_CARD_NUMBER_VISA_MASK; // Or use a standard mask.
var cardNumber = '424 2424242 42   42 42';
var cardNumberWithoutSpaces = PaymentezForm.numbersOnlyString(cardNumber);
var formattedCardNumber = PaymentezForm.applyFormatMask(cardNumberWithoutSpaces, formatMask);
Masks
Variable Name Mask
PaymentezForm.CREDIT_CARD_NUMBER_DEFAULT_MASK XXXX XXXX XXXX XXXX
PaymentezForm.CREDIT_CARD_NUMBER_VISA_MASK XXXX XXXX XXXX XXXX
PaymentezForm.CREDIT_CARD_NUMBER_MASTERCARD_MASK XXXX XXXX XXXX XXXX
PaymentezForm.CREDIT_CARD_NUMBER_DISCOVER_MASK XXXX XXXX XXXX XXXX
PaymentezForm.CREDIT_CARD_NUMBER_JCB_MASK XXXX XXXX XXXX XXXX
PaymentezForm.CREDIT_CARD_NUMBER_AMEX_MASK XXXX XXXXXX XXXXX
PaymentezForm.CREDIT_CARD_NUMBER_DINERS_MASK XXXX XXXX XXXX XX

Card Expiry Validation

The expiry month can be in the range: 1 = January to 12 = December

var month = 3;
var year = 2019;
var valid = PaymentezForm.isExpiryValid(month, year);

The expiry month and year can be either and integer or a string.

var month = "3";
var year = "2019";
var valid = PaymentezForm.isExpiryValid(month, year);

The expiry year can be either 4 digits or 2 digits long.

var month = "3";
var year = "19";
var valid = PaymentezForm.isExpiryValid(month, year);

Android

Github Repository

Paymentez Android SDK is a library that allows developers to easily connect to the Paymentez CREDITCARDS API

Example

Installation

Android Studio (or Gradle)

Add this line to your app's build.gradle inside the dependencies section:

compile 'com.paymentez:paymentez-android:1.1'

ProGuard

If you're planning on optimizing your app with ProGuard, make sure that you exclude the Paymentez bindings. You can do this by adding the following to your app's proguard.cfg file:

-keep class com.paymentez.android.** { *; }

Usage

Using the CardMultilineWidget

You can add a widget to your apps that easily handles the UI states for collecting card data.

First, add the CardMultilineWidget to your layout.

<com.paymentez.android.view.CardMultilineWidget
        android:id="@+id/card_multiline_widget"
        android:layout_alignParentTop="true"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>

You can customize the view with this tags:

app:shouldShowPostalCode="true"
app:shouldShowPaymentezLogo="true"
app:shouldShowCardHolderName="true"
app:shouldShowScanCard="true"

In order to use any of this tags, you'll need to enable the app XML namespace somewhere in the layout.

xmlns:app="http://schemas.android.com/apk/res-auto"

To get a Card object from the CardMultilineWidget, you ask the widget for its card.

Card cardToSave = cardWidget.getCard();
if (cardToSave == null) {
    Alert.show(mContext,
        "Error",
        "Invalid Card Data");
    return;
}

If the returned Card is null, error states will show on the fields that need to be fixed.

Once you have a non-null Card object from the widget, you can call addCard.

Init library

You should initialize the library on your Application or in your first Activity.

import android.support.v7.app.ActionBarActivity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;
import com.paymentez.android.Paymentez;
import com.paymentez.examplestore.utils.Constants;

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);      
      setContentView(R.layout.activity_main);

      /**
       * Init library
       *
       * @param test_mode false to use production environment
       * @param paymentez_client_app_code provided by Paymentez.
       * @param paymentez_client_app_key provided by Paymentez.
       */
      Paymentez.setEnvironment(Constants.PAYMENTEZ_IS_TEST_MODE, Constants.PAYMENTEZ_CLIENT_APP_CODE, Constants.PAYMENTEZ_CLIENT_APP_KEY);


       // In case you have your own Fraud Risk Merchant Id
       //Paymentez.setRiskMerchantId(1000);
       // Note: for most of the devs, that's not necessary.
    }
}

addCard

addCard converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.

Paymentez.addCard(mContext, uid, email, cardToSave, new TokenCallback() {

    public void onSuccess(Card card) {

        if(card != null){
            if(card.getStatus().equals("valid")){
                Alert.show(mContext,
                        "Card Successfully Added",
                        "status: " + card.getStatus() + "\n" +
                                "Card Token: " + card.getToken() + "\n" +
                                "transaction_reference: " + card.getTransactionReference());

            } else if (card.getStatus().equals("review")) {
                Alert.show(mContext,
                        "Card Under Review",
                        "status: " + card.getStatus() + "\n" +
                                "Card Token: " + card.getToken() + "\n" +
                                "transaction_reference: " + card.getTransactionReference());

            } else {
                Alert.show(mContext,
                        "Error",
                        "status: " + card.getStatus() + "\n" +
                                "message: " + card.getMessage());
            }


        }

        //TODO: Create charge or Save Token to your backend
    }

    public void onError(PaymentezError error) {        
        Alert.show(mContext,
                "Error",
                "Type: " + error.getType() + "\n" +
                        "Help: " + error.getHelp() + "\n" +
                        "Description: " + error.getDescription());

        //TODO: Handle error
    }

});

The first argument to addCard is mContext (Context). + mContext. Context of the Current Activity

The second argument to addCard is uid (String). + uid Customer identifier. This is the identifier you use inside your application; you will receive it in notifications.

The third argument to addCard is email (String). + email Email of the customer

The fourth argument to addCard is a Card object. A Card contains the following fields:

  • number: card number as a string without any separators, e.g. '4242424242424242'.
  • holderName: cardholder name.
  • expMonth: integer representing the card's expiration month, e.g. 12.
  • expYear: integer representing the card's expiration year, e.g. 2013.
  • cvc: card security code as a string, e.g. '123'.
  • type:

The fifth argument tokenCallback is a callback you provide to handle responses from Paymentez. It should send the token to your server for processing onSuccess, and notify the user onError.

Here's a sample implementation of the token callback:

Paymentez.addCard(
    mContext, uid, email, cardToSave,
    new TokenCallback() {
        public void onSuccess(Card card) {
            // Send token to your own web service
            MyServer.chargeToken(card.getToken());
        }
        public void onError(PaymentezError error) {
            Toast.makeText(getContext(),
                error.getDescription(),
                Toast.LENGTH_LONG).show();
        }
    }
);

addCard is an asynchronous call – it returns immediately and invokes the callback on the UI thread when it receives a response from Paymentez's servers.

getSessionId

The Session ID is a parameter Paymentez use for fraud purposes. Call this method if you want to Collect your user's Device Information.

String session_id = Paymentez.getSessionId(mContext);

Once you have the Session ID, you can pass it to your server to charge the user.

Client-side validation helpers

The Card object allows you to validate user input before you send the information to Paymentez.

validateNumber

Checks that the number is formatted correctly and passes the Luhn check.

validateExpiryDate

Checks whether or not the expiration date represents an actual month in the future.

validateCVC

Checks whether or not the supplied number could be a valid verification code.

validateCard

Convenience method to validate card number, expiry date and CVC.

Example apps

There is an example app included in the repository:

  • PaymentezStore project is a full walk-through of building a shop activity, including connecting to a back end.

http://d20omjwo1khove.cloudfront.net/ccapi/paymentez-store-v1.0.apk

To build and run the example app, clone the repository and open the project.

Getting started with the Android example app

Note: the app require an Android SDK and Gradle to build and run.

Building and Running the PaymentezStore

Before you can run the PaymentezStore application, you need to provide it with your Paymentez Credentials and a Sample Backend.

  1. If you don't have any Credentials yet, please ask your contact on Paymentez Team for it.
  2. Head to https://github.com/paymentez/example-java-backend and click "Deploy to Heroku" (you may have to sign up for a Heroku account as part of this process). Provide your Paymentez Server Credentials PAYMENTEZ_SERVER_APP_CODE and PAYMENTEZ_SERVER_APP_KEY fields under 'Env'. Click "Deploy for Free".
  3. Open the project on Android Studio.
  4. Replace the PAYMENTEZ_CLIENT_APP_CODE and PAYMENTEZ_CLIENT_APP_KEY constants in Constants.java with your own Paymentez Client Credentials.
  5. Replace the BACKEND_URL variable in the Constants.java file with the app URL Heroku provides you with (e.g. "https://my-example-app.herokuapp.com")
  6. Run the Project.

Important Note: if you only have one APP_CODE, please asume that it's your PAYMENTEZ_SERVER_APP_CODE. So you need to ask your contact on Paymentez Team for your PAYMENTEZ_CLIENT_APP_CODE.

iOS

Github Repository


Requirements

  • iOS 9.0 or Later
  • Xcode 8

Framework Dependencies:

Accelerate AudioToolbox AVFoundation CoreGraphics CoreMedia CoreVideo Foundation MobileCoreServices OpenGLES QuartzCore Security UIKit CommonCrypto

Project Configuration -ObjC in other linker flags in target -lc++ in target other linker flags


INSTALLATION

Carthage

If you haven't already, install the latest version of Carthage

Add this to the Cartfile:

git "https://github.com/paymentez/paymentez-ios.git"

ObjC configuration

Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

In Build Phases -> Embed Frameworks Uncheck "Copy Only When Installing"

Manual Installation

PaymentezSDK is a dynamic framework (More Info) so you have to build each version for the desire target (simulator and device). To make the integration easy, you can follow these instructions in order to have just one Universal .framework file.

  1. Build the SDK and create .framework files
  • If you want build yourself the SDK or you are using a new/beta version of Xcode . Download the project from github and run the following script inside the root folder

    sh package.sh
    
    

    This will create a /build folder where there are all the necesary .framework (simulator, iphoneos and universal)

  • Or if you prefer you can download pre-compilled .framework files from Releases

  1. Drag the PaymentezSDK.framework (preferably Universal version) To your project and check "Copy Files if needed".

    In Target->General : Add PaymentezSDK.framework to Embeeded Libraries and Linked Frameworks and Libraries

    Example

  2. Update the Build Settings with

    Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

    In Build Phases -> Embed Frameworks Uncheck "Copy Only When Installing"

Example

  1. If you use the Universal version and you want to upload to the appstore. Add Run Script Phase: Target->Build Phases -> + ->New Run Script Phase. And paste the following. Make sure that this build phase is added after Embed Frameworks phase. bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PaymentezSDK.framework/install_dynamic.sh"

Example

Usage

Importing Swift

import PaymentezSDK

Setting up your app inside AppDelegate->didFinishLaunchingWithOptions. You should use the Paymentez Client Credentials (Just ADD enabled)

PaymentezSDKClient.setEnvironment("AbiColApp", secretKey: "2PmoFfjZJzjKTnuSYCFySMfHlOIBz7", testMode: true)

Show AddCard Widget

In order to create a widget you should create a PaymentezAddNativeController from the PaymentezSDKClient. Then add it to the UIView that will be the container of the add form. The min height should be 160 px

The widget can scan with your phones camera the credit card data using card.io. Example

let paymentezAddVC = PaymentezSDKClient.createAddWidget()
self.addChildViewController(paymentezAddVC)
paymentezAddVC.view.frame = CGRect(x: 0, y: 0, width: self.view.bounds.width, height: self.addView.frame.size.height)
self.addView.translatesAutoresizingMaskIntoConstraints = true
self.addView.addSubview(paymentezAddVC.view)
paymentezAddVC.didMove(toParentViewController: self)

Objc

self.paymentezAddVC = [PaymentezSDKClient createAddWidget];
[self addChildViewController:self.paymentezAddVC];
self.paymentezAddVC.view.frame = CGRectMake(0, 0, self.view.bounds.size.width, self.addView.frame.size.height);
self.addView.translatesAutoresizingMaskIntoConstraints = YES;
[self.addView addSubview:self.paymentezAddVC.view];
[self.paymentezAddVC didMoveToParentViewController:self];

Retrive the valid credit card from the PaymentezAddNativeController (Widget):

if let validCard = paymentezAddVC.getValidCard() // CHECK IF THE CARD IS VALID, IF THERE IS A VALIDATION ERROR NIL VALUE WILL BE RETURNED
{
sender?.isEnabled = false
PaymentezSDKClient.createToken(validCard, uid: UserModel.uid, email: UserModel.email, callback: { (error, cardAdded) in

if cardAdded != nil // handle the card status
{
}
else if error != nil //handle the error
{
}
})
}

Objc

PaymentezCard *validCard = [self.paymentezAddVC getValidCard];
if (validCard != nil) // Check if it is avalid card
{

[PaymentezSDKClient add:validCard uid:USERMODEL_UID email:USERMODEL_EMAIL callback:^(PaymentezSDKError *error, PaymentezCard *cardAdded) {
[sender setEnabled:YES];
if(cardAdded != nil) // handle the card status
{

}
else  //handle the error
{

}
}];
}

Scan Card

If you want to do the scan yourself, using card.io

PaymentezSDKClient.scanCard(self) { (closed, number, expiry, cvv, card) in
if !closed // user did not closed the scan card dialog
{
if card != nil  // paymentezcard object to handle the data
{

}
})

-ObjC

[PaymentezSDKClient scanCard:self callback:^(BOOL userClosed, NSString *cardNumber, NSString *expiryDate, NSString *cvv, PaymentezCard *card) {

if (!userClosed) //user did not close the scan card dialog
{
if (card != nil) // Handle card
{

}

}
}];

Add Card (Only PCI Integrations)

For custom form integrations Fields required + cardNumber: card number as a string without any separators, e.g. 4111111111111111. + cardHolder: cardholder name. + expuryMonth: integer representing the card's expiration month, 01-12. + expiryYear: integer representing the card's expiration year, e.g. 2020. + cvc: card security code as a string, e.g. '123'.

let card = PaymentezCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")

if card != nil  // A valid card was created
{
PaymentezSDKClient.add(card, uid: "69123", email: "gsotelo@paymentez.com", callback: { (error, cardAdded) in

if cardAdded != nil
{
//the request was succesfully sent, you should check the cardAdded status
}

})
}
else
{
//handle invalid card
}

ObjC

PaymentezCard *validCard = [PaymentezCard createCardWithCardHolder:@"Gustavo Sotelo" cardNumber:@"4111111111111111" expiryMonth:10 expiryYear:2020 cvc:@"123"];
if (validCard != nil) // Check if it is avalid card
{

[PaymentezSDKClient add:validCard uid:USERMODEL_UID email:USERMODEL_EMAIL callback:^(PaymentezSDKError *error, PaymentezCard *cardAdded) {
[sender setEnabled:YES];
if(cardAdded != nil) // handle the card status
{

}
else  //handle the error
{

}
}];
}

Secure Session Id

Debit actions should be implemented in your own backend. For security reasons we provide a secure session id generation, for kount fraud systems. This will collect the device information in background

let sessionId = PaymentezSDKClient.getSecureSessionId()

Objc

NSString *sessionId = [PaymentezSDKClient getSecureSessionId];

Utils

Get Card Assets

let card = PaymentezCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")
if card != nil  // A valid card was created
{
let image = card.getCardTypeAsset()

}

Get Card Type

let card = PaymentezCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")
if card != nil  // A valid card was created
{
switch(card.cardType)
{
case .amex:
case .masterCard:
case .visa:
case .diners:
default:
//not supported action
}

}

Building and Running the PaymentezSwift

Before you can run the PaymentezStore application, you need to provide it with your APP_CODE, APP_SECRET_KEY and a sample backend.

  1. If you haven't already and APP_CODE and APP_SECRET_KEY, please ask your contact on Paymentez Team for it.
  2. Replace the PAYMENTEZ_APP_CODE and PAYMENTEZ_APP_SECRET_KEY in your AppDelegate as shown in Usage section
  3. Head to https://github.com/paymentez/example-java-backend and click "Deploy to Heroku" (you may have to sign up for a Heroku account as part of this process). Provide your Paymentez Server Credentials APP_CODE and APP_SECRET_KEY fields under 'Env'. Click "Deploy for Free".
  4. Replace the BACKEND_URL variable in the MyBackendLib.swift (inside the variable myBackendUrl) with the app URL Heroku provides you with (e.g. "https://my-example-app.herokuapp.com")
  5. Replace the variables (uid and email) in UserModel.swift with your own user id reference

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


Paymentez has official libraries for different programming languages

Coming Soon…

  • 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 paymentezCheckout.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.

<script src="https://cdn.paymentez.com/checkout/1.0.1/paymentez-checkout.min.js"></script>

<button class="js-paymentez-checkout">Purchase</button>


<script>    
  var paymentezCheckout = new PaymentezCheckout.modal({
      client_app_code: 'PAYMENTEZ_CLIENT_APP_CODE', // Client Credentials Provied by Paymentez
      client_app_key: 'PAYMENTEZ_CLIENT_APP_KEY', // Client Credentials Provied by Paymentez
      locale: 'es', // User's preferred language (es, en, pt). English will be used by default.
      env_mode: 'stg', // `prod`, `stg`, `dev`, `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);            
      }
  });

  var btnOpenCheckout = document.querySelector('.js-paymentez-checkout');
  btnOpenCheckout.addEventListener('click', function(){
    // Open Checkout with further options:
    paymentezCheckout.open({
      user_id: '1234',
      user_email: 'test@paymentez.com', //optional        
      user_phone: '7777777777', //optional
      order_description: '1 Green Salad',
      order_amount: 1500,
      order_vat: 0,
      order_reference: '#234323411',
      //order_installments_type: 2, // optional: The installments type are only available for Equador. The valid values are: https://paymentez.github.io/api-doc/#installments-type
      //order_taxable_amount: 0, // optional: Only available for Datafast (Equador). The taxable amount, if it is zero, it is calculated on the total. Format: Decimal with two fraction digits.
      //order_tax_percentage: 10 // optional: Only available for Datafast (Equador). The tax percentage to be applied to this order.
    });
  });

  // Close Checkout on page navigation:
  window.addEventListener('popstate', function() {
    paymentezCheckout.close();
  });
</script>

Configuration options

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

PaymentezCheckout.modal

Parameter Required Description
client_app_code yes Client Credentials Provied by Paymentez
client_app_key yes Client Credentials Provied by Paymentez
env_mode yes prod, stg, dev, local to change environment. Default is stg
locale no User's preferred language (es, en, pt). English will be used by default.
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."
  }
}

PaymentezCheckout.open

Parameter Required Description
user_id yes Customer identifier. This is the identifier you use inside your application.
user_email no If you already know the email address of your user, you can provide it to Checkout to be prefilled.
user_phone no If you already know the phone of your user, you can provide it to Checkout to be prefilled.
order_description yes A description of the product or service being purchased.
order_amount yes The amount that's shown to the user. Format: Decimal with two fraction digits.
order_vat yes Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order_reference yes Merchant order reference. You will identify this purchase using this reference.
order_installments_type no The installments type are only available for Equador. The valid values are: https://paymentez.github.io/api-doc/#installments-type
order_taxable_amount no Only available for Datafast (Equador). The taxable amount, if it is zero, it is calculated on the total. Format: Decimal with two fraction digits.
order_tax_percentage no Only available for Datafast (Equador). The tax percentage to be applied to this order.

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.

If you have an issue with Checkout on a specific browser, please contact us so we can improve its support.

Prevent Checkout from being blocked

You can prevent Checkout's popup from being blocked by calling paymentezCheckout.open when the user clicks on an element on the page. Do not call paymentezCheckout.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.

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.

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.

Coming soon…

Spreedly

Paymentez is one of the payment gateways Spreedly supports.

For more information visit:  Quit guide

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.