Documentation

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

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

2. 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

   

3. Update the Build Settings with

   Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

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

4. 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"

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.

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

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