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 payment_stable.min.js and payment_stable.min.css into your webpage specifying "UTF-8" like charset.

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

<link href="https://cdn.paymentez.com/ccapi/sdk/payment_stable.min.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.paymentez.com/ccapi/sdk/payment_stable.min.js" charset="UTF-8"></script>

Usage

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

Using the Paymentez Form

Any elements with the class payment-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 PaymentForm is to insert the snippet of code:

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

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

var myCard = $('#my-card');
var cardToSave = myCard.PaymentForm('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`, `local` to change environment. Default is `stg`
  * @param payment_client_app_code provided by Paymentez.
  * @param payment_client_app_key provided by Paymentez.
  */
Payment.init('stg', 'PAYMENT_CLIENT_APP_CODE', 'PAYMENT_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
 * @param payment_form Payment Form instance
 */
Payment.addCard(uid, email, cardToSave, successHandler, errorHandler, myCard);

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 = Payment.getSessionId();

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

PaymentForm Complete Reference

Manual Insertion

If you wish to manually alter the fields used by PaymentForm 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="payment-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>

Select Fields

You can determinate the fields to show on your form.

Field	Description
data-capture-name	Card Holder Name
data-capture-email	User Email
data-capture-cellphone	User Cellphone
data-icon-colour	Icons color
data-use-dropdowns	Use dropdowns to set the Card Expiration Date
data-exclusive-types	Define allowed card types
data-invalid-card-type-message	Define a custom message to show for invalid card types

The 'data-use-dropdowns' can solve an issue with the expiration mask in not so recent mobiles.

Integrate in the form is so simple like this

<div class="payment-form"
id="my-card"
data-capture-name="true"
data-capture-email="true"
data-capture-cellphone="true"
data-icon-colour="#569B29"
data-use-dropdowns="true">

Specific the card types

If you want specify the card types allowed in the form, like Exito or Alkosto. You can do something like next example. when a card type not allowed is seted, the form is reset, block the inputs and show a message, the default message is Tipo de tarjeta invalida para está operación.

<div class="payment-form"
id="my-card"
data-capture-name="true"
data-exclusive-types="ex,ak"
data-invalid-card-type-message="Tarjeta invalida. Por favor ingresa una tarjeta Exito / Alkosto."
>

Follow this link to see all card types allowed by Paymentez.

Reading Values

PaymentForm 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 PaymentForm element and give it a unique id (in this example my-card)

<div class="payment-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.PaymentForm('cardNumber');
var cardType = myCard.PaymentForm('cardType');
var name = myCard.PaymentForm('name');
var expiryMonth = myCard.PaymentForm('expiryMonth');
var expiryYear = myCard.PaymentForm('expiryYear');
var fiscalNumber = myCard.PaymentForm('fiscalNumber');
var validationOption = myCard.PaymentForm('validationOption');

Functions

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

$('#my-card').PaymentForm('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
fiscalNumber	Get the fiscal number
validationOption	Get the validation option

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
Exito

Static functions

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

Card Type from Card Number

var cardNumber = '4242 4242 4242 4242'; // Spacing is not important
var cardType = PaymentForm.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 = PaymentForm.CREDIT_CARD_NUMBER_VISA_MASK; // Or use a standard mask.
var cardNumber = '424 2424242 42   42 42';
var cardNumberWithoutSpaces = PaymentForm.numbersOnlyString(cardNumber);
var formattedCardNumber = PaymentForm.applyFormatMask(cardNumberWithoutSpaces, formatMask);

Masks

Variable Name	Mask
PaymentForm.CREDIT_CARD_NUMBER_DEFAULT_MASK	XXXX XXXX XXXX XXXX
PaymentForm.CREDIT_CARD_NUMBER_VISA_MASK	XXXX XXXX XXXX XXXX
PaymentForm.CREDIT_CARD_NUMBER_MASTERCARD_MASK	XXXX XXXX XXXX XXXX
PaymentForm.CREDIT_CARD_NUMBER_DISCOVER_MASK	XXXX XXXX XXXX XXXX
PaymentForm.CREDIT_CARD_NUMBER_JCB_MASK	XXXX XXXX XXXX XXXX
PaymentForm.CREDIT_CARD_NUMBER_AMEX_MASK	XXXX XXXXXX XXXXX
PaymentForm.CREDIT_CARD_NUMBER_DINERS_MASK	XXXX XXXX XXXX XX
PaymentForm.CREDIT_CARD_NUMBER_EXITO_MASK	XXXX XXXX XXXX XXXX

Card Expiry Validation

The expiry month can be in the range: 1 = January to 12 = December In the case of 'Exito' cards, they do not have an expiration date

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

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

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

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

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

Card Validations Options

There are three card validation options

Validation Option	Description
PaymentForm.AUTH_CVC	Card validation by cvc, the most common option
PaymentForm.AUTH_NIP	Card validation by nip (Available only by Exito cards)
PaymentForm.AUTH_OTP	Card validation by otp (Available only by Exito cards)

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 it in your root build.gradle at the end of repositories:

allprojects {
        repositories {
            ...
            maven { url 'https://jitpack.io' }
        }
    }

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

   implementation 'com.github.paymentez:paymentez-android:v1.3.3'

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.

https://cdn.paymentez.com/apps/paymentez-example-1-2-7.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

Version <= 1.4.x - iOS 9.0 or Later - Xcode 9

Version >= 1.5.x - iOS 9.0 or Later - Xcode 10

Framework Dependencies:

Accelerate AudioToolbox AVFoundation CoreGraphics CoreMedia CoreVideo Foundation MobileCoreServices OpenGLES QuartzCore Security UIKit CommonCrypto (Just for version 1.4)

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

---

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"

For Beta Versions:

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

ObjC configuration

Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

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

Manual Installation(Recommended)

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)

Types of implementation

There are 3 ways to present the Add Card Form:

1. As a Widget in a Custom View
2. As a Viewcontroller Pushed to your UINavigationController
3. As a ViewController presented in Modal

The AddCard Form includes: Card io scan, and card validation.

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 Paymentez Form. The min height should be 300 px, and whole screen as width (270px without paymentez logo)

Note: When you are using the Paymentez Form as Widget. The Client custom ViewController will be responsible for the layout and synchronization (aka Spinner or loading)

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

let paymentezAddVC = self.addPaymentezWidget(toView: self.addView, delegate: nil, uid:UserModel.uid, email:UserModel.email)

Objc

[self addPaymentezWidgetToView:self. addView delegate:self uid:@"myuid" email:@"myemail"];

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
{

}
}];
}

Pushed to your NavigationController

self.navigationController?.pushPaymentezViewController(delegate: self, uid: UserModel.uid, email: UserModel.email)

Objc

[self.navigationController pushPaymentezViewControllerWithDelegate:self uid:@"myuid" email:@"mymail@mail.com"]`;

Present as Modal

self.presentPaymentezViewController(delegate: self, uid: "myuid", email: "myemail@email.com")

Objc

[self presentPaymentezViewControllerWithDelegate:self uid:@"myuid" email:@"myemail@email.com"];

PaymentezCardAddedDelegate Protocol

If you present the Form as a viewcontroller (push and modal) you must implement the PaymetnezCardAddedDelegate Protocol in order to handle the states or actions inside the Viewcontroller. If you are using Widget implementation you can handle the actions as described above.

protocol PaymentezCardAddedDelegate
{
func cardAdded(_ error:PaymentezSDKError?, _ cardAdded:PaymentezCard?)
func viewClosed()
}

func cardAdded(_ error:PaymentezSDKError?, _ cardAdded:PaymentezCard?) is called whenever there is an error or a card is added.

func viewClosed() Whenever the modal is closed

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 (Just Amex, Mastercard, Visa, Diners)

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
}

}

Customize Look & Feel

You can customize widget colors sample

paymentezAddVC.baseFontColor = .white
paymentezAddVC.baseColor = .green
paymentezAddVC.backgroundColor = .white
paymentezAddVC.showLogo = false
paymentezAddVC.baseFont = UIFont(name: "Your Font", size: 12) ?? UIFont.systemFont(ofSize: 12)

The customizable elements of the form are the following:

• baseFontColor : The color of the font of the fields
• baseColor: Color of the lines and titles of the fields
• backgroundColor: Background color of the widget
• showLogo: Enable or disable Paymentez Logo
• baseFont: Font of the entire form
• nameTitle: String for the custom placeholder for the Name Field
• cardTitle: String for the custom placeholder for the Card Field
• invalidCardTitle String for the error message when a card number is invalid

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

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

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

3. Now the client must confirm the clave temporal,  so you need to implement the endpoint verify in order to activate the card.
4. On the response you will know if the card is ready for use.
5. Once the card is ready you can use it for debit method (here you will need the card.token from point 1).
6. 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

VTEX

We have the solution eCommerce VTEX + Paymentez implemented.

For further information visit: This manual

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 credit card payments.

Download and Installation

1. Execute this command for install our package:

Install the latest version. composer require paymentez/magento2

Install a specific version. composer require paymentez/magento2:1.2

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

2. Update modules registry:

php bin/magento setup:upgrade

3. Update dependency injection:

php bin/magento setup:di:compile

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/magento2

Fraud notifications via webhook

When Paymentez detect a possible fraud we use notifications through webhook for notify to Magento Admin for make an update the order state and status.

The webhook path by default is:

/V1/paymentez/notification/listener

So, the possible fraud notifications can be send to:

https://magentodomain.com/V1/paymentez/notification/listener

The module settings on admin dashboard looks like this

WooCommerce

Paymentez WooCommerce Plugin

 

1. Pre-requisitos

1.1. WordPress

La documentación necesaria para instalar y configurar WordPress se encuentra en la siguiente liga: Install WordPress. Todos los requisitos mínimos (PHP y MySQL) deben ser cumplidos para que el plugin desarrollado pueda funcionar correctamente.

1.2. WooCommerce

La documentación necesaria para instalar WooCommerce se encuentra en la siguiente liga: Install WooCommerce. Allí también se encuentra información necesaria para hacer troubleshooting relacionado con la instalación.

 

2. Repositorio en Git

El proyecto entero deberá estar comprimido en formato .zip para poder ser subido como un plugin de WordPress. Liga: Paymentez WooCommerce Plugin.

 

3. Instalación en WordPress

Este proyecto es un plugin de WordPress que se comunica con el plugin de WooCommerce dentro de WordPress, de tal manera que una vez instalado y activado se entabla la comunicación por medio de hooks y actions de WooCommerce y WordPress.

3.1 Instalación y activación por medio del WordPress Admin

Cuando ya tengamos el proyecto comprimido en formato .zip, procedemos a la instalación por medio del WordPress Admin.

1. El primer paso será hacer login dentro del WordPress Admin como administrador.
2. Estando en la pantalla principal del admin damos clic en la pestaña de Plugins.
3. Dentro de la pantalla de Plugins damos clic en Add New.
4. Dentro de la pantalla de Add Plugins damos clic en Upload Plugin.
5. Se desplegará la opción para subir nuestro plugin en formato .zip. Lo subimos y damos clic en el botón Install Now.
6. Seremos redireccionados a la pantalla de instalación del plugin.
7. Esperamos a obtener el mensaje Plugin Installed Successfully y damos clic en el botón de Activate Plugin.
8. Seremos redireccionados a la pantalla de Plugins dónde veremos nuestro plugin instalado y activado.

3.2 Creación y Eliminación de la Base de Datos

Por defecto, cuando se Activa y Desactiva el plugin, se crea y elimina la tabla correspondiente a la base de datos del proyecto. La tabla se creará en la base de datos que se configuró en la instalación de WordPress. El nombre de la tabla se compone por el prefijo de tablas configurado en la instalación de WordPress (por defecto wp_) y el nombre paymentez_plugin. La base de datos almacena los registros con detalle de todas las transacciones que se hagan en el comercio. Los datos mas relevantes que se almacenan son:

• orderId el cual es el identificador único de las transacciones en el comercio.
• Transaction Code el cual es el identificador único de las transacciones en Paymentez

3.3 Selección del Idioma

El idioma del plugin es seleccionado dinámicamente de acuerdo al idioma que esté configurado en WordPress. Los idiomas que están disponibles son:

• Español MXN
• Portuges BRA
• Inglés (Por defecto)

Es importante aclarar que si el idioma de WordPress es alguno que no está en la lista, se seleccionará inglés por defecto. Ésto no afecta al idioma del checkout el cual es independiente de WordPress.

 

4. Activación y Configuración del Plugin en WooCommerce

Después de haberse instalado nuestro plugin en WordPress debemos proceder a configurarlo en el Admin de WooCommerce. Éste se encuentra en la pestaña de WooCommerce del dashboard de WordPress. Luego damos clic en la opción de Settings y posteriormente en la pestaña de Payments.

4.1 Activación del Gateway

Para activar nuestro gateway dentro de nuestro comercio WooCommerce, necesitamos estár dentro de la pestaña WooCommerce->Settings->Payments y veremos nuestro plugin instalado y detectado. Para habilitarlo deberemos activar el botón Enabled. Ésta habilitación del plugin es distinta a la de WordPress la cual hicimos anteriormente.

4.2 Configuraciones del Gateway en el Admin de WooCommerce

Al habilitar nuestro plugin en el admin de WooCommerce, tendremos algunas opciones para configurar. Para hacerlo damos click al botón Manage que aparecerá al costado de nuestro plugin. Las opciones para configurar son las siguientes:

• Staging Environment: Cuando está habilitada, el plugin apuntará al servidor de pruebas de Paymentez.
• Title: Ésta opción configura el texto que verá el cliente en la ventana de checkout junto al logo de Paymentez.
• Customer Message: Ésta opción configura el mensaje que verá el cliente en la ventana del checkout cuando seleccione Paymentez como método de pago.
• Checkout Language: Ésta opción selecciona el idioma que se mostrará en la ventana del checkout. Las opciones disponibles son Español, Portugués e Inglés (por defecto).
• App Code Client: Identificador único en Paymentez.
• App Key Client: Clave utilizada para cifrar la comunicación con Paymentez.
• App Code Server: Identificador único en el servidor de Paymentez.
• App Key Server: Clave usada para la comunicación con el servidor de Paymentez.

 

5. Selección del Plugin en el Checkout de la Tienda

Cuando tengamos todo nuestro plugin activado y configurado en WooCommerce, lo veremos disponible para seleccionarse por los clientes en la página de Checkout de nuestro comercio. Sólo basta con seleccionarlo, llenar los Billing Details y dar click en el botón de Place Order. Dando click llegaremos a la ventana de Order-Pay o Pay For Order en el cual veremos un resumen de nuestro pedido. Se mostrará el botón de Purchase el cual abrirá el checkout de Paymentez.

 

6. Proceso Para hacer un Refund

1. El proceso de refund empezará en la ventana principal del dashboard de WordPress.
2. Seleccionamos la pestaña de WooCommerce y hacemos click en la opción Orders.
3. Seleccionamos el pedido que queremos reembolsar y se abrirá la ventana de Edit Order.
4. En el detalle del item encontraremos el botón de Refund, hacemos click y se desplegarán las opciones del refund.
5. Tecleamos la cantidad a reembolsar y damos click al botón de Refund Manually.
6. El estatus dentro de WooCommerce cambiará y también el estatus en Paymentez.