Kushki Android

The Kushki library for Android allows you to collect payments easily and safely in your Android mobile application.

TIP

We make it easier!
We make it easier! This library handles the complexity of secure payments so you can focus on your app experience.

⚙️ Install and configure

To use 3DS, add the following Maven repository and credentials to your app-level gradle file.

Installing the Kushki Android library is simple; add the following code to your project's build.gradle file, inside the dependencies section.

🛠️ Usage

After you finish installing, create an instance of Kushki. This will allow you to perform all the methods available in the SDK.

Configuration Parameters

Required

Property	Type	Description	Default	Possible Values
publicMerchantId	`String`	Kushki ID created for your merchant.	-	-
currency	`String`	Currency code.	`USD`	`USD`, `COP`, `CLP`, `UF`, `PEN`, `MXN`

Optional

Property	Type	Description	Default	Possible Values
environment	Enum	Value to define if you are in production or test environment	`KushkiEnvironment.production`	`KushkiEnvironment.production` , `KushkiEnvironment.testing`
regional	Boolean	Define if use a static IP to Kushki access	`false`	`true`,`false`

⚡ Examples

Find the methods available in our Android library along with examples.

One-Time Payment Examples

Security Note

The token delivered by Kushki only encrypts and sends information. If you want to store the card information for future purchases, go to the Recurring Charges section.

💳 Card

⏳ Card Async

🍏 Apple Pay

🏦 Transfer In

💵 Cash In

requestToken()

To request a card token, you can use this method

Required

Property	Type	Description
card	Object	The card data collected in a card object
totalAmount	Double	The amount you are going to collect

Optional

Property	Type	Description	Possible Values
context	Context	Context of the current state of the application/object. Required for 3DS and Sift implementations.
activity	Activity	An application component that provides a screen with which users can interact in order to do something. Required for 3DS implementations.

3DS

The requestToken method of the Kushki library on android does what is necessary so that merchants that have 3DS activated can verify transactions through this service.

It is necessary to validate that the specificationVersion is greater than 2.0. in implementations with 3DS.

Response

If the 3DS service is not active, a response similar to the following will be returned when consuming the requestToken method

{
     "token": "PmgVbd100000Pe5VEU098014S84wiTFR"
}

If the 3DS service is active, a response similar to the following will be returned when consuming the requestToken method

{
    "token": "PmgVbd100000Pe5VEU098014S84wiTFR",
    "secureService": "3dsecure",
    "secureId": "a80d6cef-90ad-44ca-a2ef-f244301d5e40",
    "security": {
        "acsURL": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
        "authenticationTransactionId": "o6YMk3mdEoAMVMImUpd0",
        "authRequired": true,
        "paReq": "eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlODIzYWVhMS1hMjM3LTRkNmQtYjlhNC0yY2JjZGZlYjI1YTYiLCJhY3NUcmFuc0lEIjoiY2Q4MThmNDAtOTc1NC00NmRjLTg1YzgtMWU5MDk2MjY1MmMzIiwiYWNzVWlUeXBlIjoiMDIiLCJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIjoiTiIsImNoYWxsZW5nZUluZm9IZWFkZXIiOiJQYXltZW50IFNlY3VyaXR5IiwiY2hhbGxlbmdlSW5mb0xhYmVsIjoiQ3JlZGVudGlhbCBTZWxlY3Rpb24iLCJjaGFsbGVuZ2VJbmZvVGV4dCI6IllvdXIgb25saW5lIHBheW1lbnQgaXMgYmVpbmcgc2VjdXJlZCB1c2luZyBDYXJkIE5ldHdvcmsuIFBsZWFzZSBzZWxlY3Qgd2hlcmUgeW91IHdvdWxkIGxpa2UgdG8gcmVjZWl2ZSB0aGUgY29kZSBmcm9tIFlvdXJCYW5rLiIsImNoYWxsZW5nZVNlbGVjdEluZm8iOlt7Im1vYmlsZSI6Ik1vYmlsZSAqKioqKioqKjMyMSJ9LHsiZW1haWwiOiJFbWFpbCAqKioqKioqKioqQGcqKioqLmNvbSJ9XSwiaXNzdWVySW1hZ2UiOnsibWVkaXVtIjoiaHR0cHM6Ly9tZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvc2NyZWVucy9pbWFnZXMvQW55QmFua181MTIucG5nIiwiaGlnaCI6Imh0dHBzOi8vbWVyY2hhbnRhY3NzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL01lcmNoYW50QUNTV2ViL3NjcmVlbnMvaW1hZ2VzL0FueUJhbmtfNTEyLnBuZyIsImV4dHJhSGlnaCI6Imh0dHBzOi8vbWVyY2hhbnRhY3NzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL01lcmNoYW50QUNTV2ViL3NjcmVlbnMvaW1hZ2VzL0FueUJhbmtfNTEyLnBuZyJ9LCJwc0ltYWdlIjp7Im1lZGl1bSI6Imh0dHBzOi8vbWVyY2hhbnRhY3NzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL01lcmNoYW50QUNTV2ViL3NjcmVlbnMvaW1hZ2VzL0NhcmRfTmV0d29yay5wbmciLCJoaWdoIjoiaHR0cHM6Ly9tZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvc2NyZWVucy9pbWFnZXMvQ2FyZF9OZXR3b3JrLnBuZyIsImV4dHJhSGlnaCI6Imh0dHBzOi8vbWVyY2hhbnRhY3NzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL01lcmNoYW50QUNTV2ViL3NjcmVlbnMvaW1hZ2VzL0NhcmRfTmV0d29yay5wbmcifSwic2RrVHJhbnNJRCI6IjJjZWI0NjUxLWUyYzAtNDZjOS04YzAxLWI2ODNjMTM3Nzc5MSIsInN1Ym1pdEF1dGhlbnRpY2F0aW9uTGFiZWwiOiJORVhUIiwiYWNzQ291bnRlckF0b1MiOiIwMDAiLCJleHBhbmRJbmZvTGFiZWwiOiJNb3JlIEluZm9ybWF0aW9uIiwiZXhwYW5kSW5mb1RleHQiOiJIZXJlIGlzIHRoZSBhZGRpdGlvbmFsIGluZm9ybWF0aW9uIHRoYXQgd2UgcHJvdmlkZS4iLCJ3aHlJbmZvTGFiZWwiOiJOZWVkIHNvbWUgaGVscD8iLCJ3aHlJbmZvVGV4dCI6IkhlcmUgaXMgdGhlIGhlbHAgdGhhdCB3ZSBwcm92aWRlLiJ9",
        "specificationVersion": "2.2.0"
    }
}

PROPERTY	TYPE	DESCRIPTION
secureService	String	Service used to authenticate the transaction
secureId	String	The secureId you get from the token response
security	Object	The security object received from the token response
security.acsURL	String	URL of the challenge page of the issuer
security.authenticationTransactionId	String	ID of the transaction verified by the brands.
security.specificationVersion	String	3D Secure version. Must be greater than 2.0
security.paReq	String	This parameter contains zipped Based64-encoded data on the transaction. This parameter is received from the brands.
security.authRequired	Boolean	Identifies whether the 3DS challenge is required or not.

requestSecureValidation()

It is necessary to validate that the 3DS flow has been completed successfully and that the 3DS challenge has been successfully passed. To do this, the requestSecureValidation() method must be used, sending the secureId parameter obtained from the requestToken() method.

Response

The response object must have the following structure, to complete the valid 3DS flow.

{
    "code": "3DS000",
    "message": "ok"
}

Example

getBinInfo()

Returns an object with the information related to the credit card bin (first eight digits). For Chilean merchants, the response is helpful to decide whether to continue with the request of a card token (when cardType is CREDIT), or with the request of a card async token (when cardType is DEBIT):

Request

Required

Property	Type	Description
bin	String	The first eight digits of the credit card

Recurring Charges Examples

💳 Card Subscription

⏳ Async Subscription 🇨🇱

requestSubscriptionToken()

To request a recurring charge token.

Required Parameters

Property	Type	Description
`card`	`Object`	The card data collected in a card object.

Payouts Examples

💸 Cash Out 🇨🇴

requestCashOutToken()

To request a Cash Out token.

Required Parameters

Property	Type	Description	Possible Values
name	String	Name of the client
lastName	String	Last name of the client
documentType	String	Type of document that the client is using to pay.	`CC`, `NIT`, `CE`, `TI`, `PP`
identification	String	Document number that the client is using to pay
totalAmount	Number	The amount you are going to collect as a number
currency	String	Code of currency used	`COP`

🚦 Handling Responses

Once the execution finishes, you need to handle the Transaction object.

Successful Results

The onPostExecute method will receive a Transaction object. If the operation was successful, the token will be available by invoking the getToken method:

Failed Results & Exceptions

If the transaction was not successful, you can retrieve the error details directly from the object:

Error Code: Invoke transaction.getCode()

Description: Invoke transaction.getMessage()

Note: For any unexpected errors, the requestToken method will throw a managed exception of type KushkiException.

🎨 Sensory Branding

The Card Branding Animation gives users meaningful confirmation of their payment.

Apply this animation only when the user has selected a Mastercard or Visa card to make payment, and play it after a transaction is complete.

Visa

Mastercard

Gradle Setup

Add the following dependencies in your build.gradle file:

Define the view ViewVisaAnimation in the target activity.

Properties

Property	Type	Required	Description	Default	Possible values
backdropColor	Android color	No	Set a color for the animation background. See Android resource types for more information.	white
languageCode	enum	No	Define the language of animation.	`ENGLISH`	`ENGLISH`, `SPANISH`, `PORTUGUESE`
soundEnabled	boolean	No	Enable or disable animation sound.	`true`	`true`, `false`
hapticEnabled	boolean	No	Enable or disable animation haptics.	`true`	`true`, `false`
checkmarkMode	enum	No	Show check mark.	`CHECKMARK`	`CHECKMARK`, `CHECKMARK_WITH_TEXT`, `NONE`
checkmarkText	enum	No	Set check mark text.	`APPROVE`	`APPROVE`, `COMPLETE`, `SUCCESS`

Get visaAnimationView by the defined activity id:

Also you can define custom properties for the animation:

Finally, trigger the animation:

Properties

Property	Type	Required	Description
fnOnFinishedAnimation	lambda	Yes	Lambda to execute when animation finished.

Next Steps

Remember that to continue with the payment flow you must send to your back-end the token received.

To start the charge process, please go to our backend integrations: Kushki Libraries or Kushki API

📖 Reference Summary

Find the methods available in our Android library. You can perform the following operations:

One-time Payment:

Create a Card token

Get Bin Info

Create a Card Async Token

Create a Transfer In token

Create a Cash In token

Recurring Charges

Create a Card recurring charge token

Get an Async Card recurring charge

Get a list of banks available for Recurring Charges With Wire Transfer Debit

Create a Transfer recurring charge token

Start and answer a challenge to validate the account data in Transfer Recurring Charges

Payouts

Create a Cash Out token

One-time Payment

Name	Parameters	Returns	Description
requestToken()	`card`, `totalAmount`, `context`, `activity`	Object	Returns a token
requestSecureValidation()	On the first call: `secureService`, `secureServiceId`, `cityCode`, `stateCode`, `phone`, `expeditionDocumentDate`. On second call: `secureService`, `secureServiceId`, `questionnaireCode`, `answers` (JSON Object)	Object	On the first call, returns a questionnaire for the challenge. On second call, returns a code and a message with the results of the account verification
getBinInfo()	`bin`	Object	Returns an object with the information related to the credit card bin
requestCardAsyncToken()	`totalAmount`, `returnUrl`, `email`, `description`	Object	Returns a card async token
requestTransferToken()	`amount`, `callbackUrl`, `documentType`, `documentNumber`, `email`, `paymentDescription`, `userType`	Object	Returns a transfer in token
requestCashToken()	`totalAmount`, `currency`, `identification`, `documentType`, `name`, `lastName`, `email`, `description`	Object	Returns a cash in `token` that can later be used to initialize a cash in transaction

Recurring Charges

Name	Parameters	Returns	Description
requestSubscriptionToken()	`card`	Object	Returns a recurring charge token
requestCardSubscriptionAsyncToken	`currency`, `email`, `cardNumber`, `callbackUrl`	Object	Returns an async card recurring charge token
getBankList()		Object	Returns a list of banks available for transfer Recurring Charges
requestTransferSubscriptionToken()	`documentNumber`, `bankCode`, `name`, `lastName`, `accountNumber`, `documentType`, `accountType`, `email`, `currency`	Object	Returns a `token` along with a `secureId`, and `secureService`. The token can later be used to create a transfer recurring charge. Before that, you will need to confirm the account data by starting and answering a challenge with the secure validation method

Payouts

Name	Parameters	Returns	Description
requestCashOutToken()	`totalAmount`, `currency`, `identification`, `documentType`, `name`, `lastName`, `email`, `description`	Object	Returns a cash out `token` that can later be used to initialize a cash out transaction

🚀 Example Application

You can find an example application in our GitHub android project repository.

Got a suggestion on this documentation? Contact Us.

⚙️ Install and configure#

🛠️ Usage#

Configuration Parameters#

One-Time Payment Examples#

requestToken()#

3DS#

requestSecureValidation()#

getBinInfo()#

Recurring Charges Examples#

requestSubscriptionToken()#

Payouts Examples#

requestCashOutToken()#

🚦 Handling Responses#

🎨 Sensory Branding#

Properties#

Properties#

Next Steps#

📖 Reference Summary#

One-time Payment#

Recurring Charges#

Payouts#

🚀 Example Application#

⚙️ Install and configure

🛠️ Usage

Configuration Parameters

One-Time Payment Examples

requestToken()

3DS

requestSecureValidation()

getBinInfo()

Recurring Charges Examples

requestSubscriptionToken()

Payouts Examples

requestCashOutToken()

🚦 Handling Responses

🎨 Sensory Branding

Properties

Properties

Next Steps

📖 Reference Summary

One-time Payment

Recurring Charges

Payouts

🚀 Example Application