===================
Paymentez Android SDK is a library that allows developers to easily connect to the Paymentez CREDITCARDS API
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.5'
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.** { *; }
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.
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 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.
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.
The Card object allows you to validate user input before you send the information to Paymentez.
Checks that the number is formatted correctly and passes the Luhn check.
Checks whether or not the expiration date represents an actual month in the future.
Checks whether or not the supplied number could be a valid verification code.
Convenience method to validate card number, expiry date and CVC.
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.
Note: the app require an Android SDK and Gradle to build and run.
Before you can run the PaymentezStore application, you need to provide it with your Paymentez Credentials and a Sample Backend.
- If you don't have any Credentials yet, please ask your contact on Paymentez Team for it.
- 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_CODEandPAYMENTEZ_SERVER_APP_KEYfields under 'Env'. Click "Deploy for Free". - Open the project on Android Studio.
- Replace the
PAYMENTEZ_CLIENT_APP_CODEandPAYMENTEZ_CLIENT_APP_KEYconstants in Constants.java with your own Paymentez Client Credentials. - Replace the
BACKEND_URLvariable in the Constants.java file with the app URL Heroku provides you with (e.g. "https://my-example-app.herokuapp.com") - 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.