Kushki Android

La librería de Kushki para Android te permite recibir pagos de forma fácil y segura en tu aplicación móvil Android.

TIP

¡Te lo hacemos fácil!
Esta librería se encarga de la complejidad de los pagos seguros para que tú te concentres en la experiencia de tu app.

⚙️ Instalación y configuración

Para usar 3DS, agrega el siguiente repositorio de Maven y sus credenciales al archivo gradle de tu app

Instalar la librería de Kushki para Android es simple: agrega el siguiente código al archivo build.gradle de tu proyecto, dentro de la sección dependencies.

🛠️ Uso

Cuando termines la instalación, crea una instancia de Kushki. Con ella podrás usar todos los métodos disponibles en el SDK.

Parámetros de configuración

Requerido

Propiedad	Tipo	Descripción	Por defecto	Valores posibles
publicMerchantId	`String`	ID de Kushki creado para tu comercio.	-	-
currency	`String`	Código de moneda.	`USD`	`USD`, `COP`, `CLP`, `UF`, `PEN`, `MXN`

Opcional

Propiedad	Tipo	Descripción	Por defecto	Valores posibles
environment	`Enum`	Valor para definir si estás en ambiente de producción o de pruebas.	`KushkiEnvironment.PRODUCTION`	`KushkiEnvironment.PRODUCTION`, `KushkiEnvironment.TESTING`
regional	`Boolean`	Define si se usa una IP estática para acceder a Kushki.	`false`	`true`, `false`

⚡ Examples

Encuentra los métodos disponibles en nuestra librería de Android, con ejemplos.

Ejemplos de pago único

Nota de seguridad

El token que entrega Kushki solo cifra y envía información. Si quieres guardar los datos de la tarjeta para compras futuras, ve a la sección Ejemplos de cargos recurrentes.

💳 Card

⏳ Card Async

🍏 Apple Pay

🏦 Transfer In

💵 Cash In

requestToken()

Para solicitar un token de tarjeta, puedes usar este método

Requerido

Propiedad	Tipo	Descripción
card	Object	Los datos de la tarjeta recogidos en un objeto card
totalAmount	Double	El monto que vas a cobrar

Opcional

Propiedad	Tipo	Descripción	Valores posibles
context	Context	Contexto del estado actual de la aplicación u objeto. Obligatorio en implementaciones con 3DS y Sift.
activity	Activity	Componente de la aplicación que provee una pantalla con la que los usuarios pueden interactuar para hacer algo. Obligatorio en implementaciones con 3DS.

3DS

El método requestToken de la librería de Kushki para Android hace lo necesario para que los comercios que tienen 3DS activo puedan verificar transacciones a través de este servicio.

En implementaciones con 3DS es necesario validar que specificationVersion sea mayor que 2.0.

Respuesta

Si el servicio de 3DS no está activo, al consumir el método requestToken se devolverá una respuesta similar a la siguiente

{
     "token": "PmgVbd100000Pe5VEU098014S84wiTFR"
}

Si el servicio de 3DS está activo, al consumir el método requestToken se devolverá una respuesta similar a la siguiente

{
    "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"
    }
}

PROPIEDAD	TIPO	DESCRIPCIÓN
secureService	String	Servicio usado para autenticar la transacción
secureId	String	El secureId que obtienes en la respuesta del token
security	Object	El objeto security que llega en la respuesta del token
security.acsURL	String	URL de la página de challenge del emisor
security.authenticationTransactionId	String	ID de la transacción verificada por las franquicias.
security.specificationVersion	String	Versión de 3D Secure. Debe ser mayor que 2.0
security.paReq	String	Este parámetro contiene información de la transacción comprimida y codificada en Base64. Lo entregan las franquicias.
security.authRequired	Boolean	Indica si el challenge de 3DS es obligatorio o no.

requestSecureValidation()

Es necesario validar que el flujo de 3DS se completó con éxito y que el challenge de 3DS se superó correctamente. Para eso usa el método requestSecureValidation() y envía el parámetro secureId que obtuviste del método requestToken().

Respuesta

El objeto de respuesta debe tener la siguiente estructura para dar por completado el flujo de 3DS.

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

Ejemplo

getBinInfo()

Devuelve un objeto con la información del bin de la tarjeta de crédito (los primeros ocho dígitos). Para los comercios de Chile, la respuesta sirve para decidir si continúas con la solicitud de un token de tarjeta (cuando cardType es CREDIT) o con la de un token de Card Async (cuando cardType es DEBIT):

Solicitud

Requerido

Propiedad	Tipo	Descripción
bin	String	Los primeros ocho dígitos de la tarjeta de crédito

Ejemplos de cargos recurrentes

💳 Card Subscription

⏳ Async Subscription 🇨🇱

requestSubscriptionToken()

To request a recurring charge token.

Requerido

Propiedad	Tipo	Descripción
`card`	`Object`	Los datos de la tarjeta recogidos en un objeto card.

Ejemplos de dispersiones

💸 Cash Out 🇨🇴

requestCashOutToken()

To request a Cash Out token.

Requerido

Propiedad	Tipo	Descripción	Valores posibles
name	String	Nombre del cliente
lastName	String	Apellido del cliente
documentType	String	Tipo de documento que el cliente usa para pagar.	`CC`, `NIT`, `CE`, `TI`, `PP`
documentNumber	String	Número de documento que el cliente usa para pagar
totalAmount	Number	El monto que vas a cobrar, como número
currency	String	Código de moneda usado	`COP`

Opcional

Propiedad	Tipo	Descripción
email	String	Correo electrónico del cliente
description	String	Una descripción del pago

🚦 Manejo de respuestas

Cuando termine la ejecución, tienes que manejar el objeto Transaction.

Resultados correctos

El método onPostExecute recibirá un objeto Transaction. Si la operación fue exitosa, el token estará disponible al invocar el método getToken:

Resultados con error y excepciones

Si la transacción no fue exitosa, puedes obtener los detalles del error directamente del objeto:

Código de error: Invoke transaction.getCode()

Descripción: Invoke transaction.getMessage()

Nota: Ante cualquier error inesperado, el método requestToken lanzará una excepción gestionada de tipo KushkiException.

🎨 Sensory Branding

La animación de marca de la tarjeta les da a los usuarios una confirmación clara de su pago.

Aplica esta animación solo cuando el usuario haya elegido una tarjeta Mastercard o Visa para pagar, y reprodúcela cuando la transacción se haya completado.

Visa

Mastercard

Agrega el siguiente repositorio de Maven al gradle de tu app:

Agrega las siguientes dependencias en tu archivo build.gradle:

Define la vista ViewVisaAnimation en la activity de destino.

    <com.kushkipagos.views.ViewVisaAnimation
        android:id="@+id/visa_animation"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerInParent="true"
        android:clipChildren="false"
        app:backdropColor="@color/blue"
        app:languageCode="SPANISH"
        app:soundEnabled="false"
        app:hapticEnabled="false"
        app:checkmarkMode="NONE"
        app:checkmarkText="SUCCESS"
        />

Propiedades

Propiedad	Tipo	Requerido	Descripción	Por defecto	Valores posibles
backdropColor	Android color	No	Define un color para el fondo de la animación. Consulta Android resource types para más información.	white
languageCode	enum	No	Define el idioma de la animación.	`ENGLISH`	`ENGLISH`, `SPANISH`, `PORTUGUESE`
soundEnabled	boolean	No	Activa o desactiva el sonido de la animación.	`true`	`true`, `false`
hapticEnabled	boolean	No	Activa o desactiva la vibración de la animación.	`true`	`true`, `false`
checkmarkMode	enum	No	Muestra el check de confirmación.	`CHECKMARK`	`CHECKMARK`, `CHECKMARK_WITH_TEXT`, `NONE`
checkmarkText	enum	No	Define el texto del check de confirmación.	`APPROVE`	`APPROVE`, `COMPLETE`, `SUCCESS`

Obtén visaAnimationView con el id definido en la activity:

También puedes definir propiedades personalizadas para la animación:

Finally, trigger the animation:

Propiedades

Propiedad	Tipo	Requerido	Descripción
fnOnFinishedAnimation	lambda	Sí	Lambda que se ejecuta cuando termina la animación.

Siguientes pasos

Recuerda que para continuar con el flujo de pago tienes que enviar a tu back-end el token recibido.

Para iniciar el proceso de cargo, ve a nuestras integraciones de backend: Kushki Libraries o Kushki API

📖 Resumen de referencia

Encuentra los métodos disponibles en nuestra librería de Android. Puedes hacer las siguientes operaciones:

Pago único:

Crear un token de tarjeta

Consultar la información del bin

Crear un token de Card Async

Crear un token de Transfer In

Crear un token de Cash In

Cargos recurrentes

Crear un token de cargo recurrente con tarjeta

Consultar un cargo recurrente de Card Async

Consultar la lista de bancos disponibles para cargos recurrentes con débito por transferencia

Crear un token de cargo recurrente por transferencia

Iniciar y responder un challenge para validar los datos de la cuenta en los cargos recurrentes por transferencia

Dispersiones

Create a Cash Out token

Pago único

Nombre	Parámetros	Devuelve	Descripción
requestToken()	`card`, `totalAmount`, `context`, `activity`	Object	Devuelve un token
requestSecureValidation()	En la primera llamada: `secureService`, `secureServiceId`, `cityCode`, `stateCode`, `phone`, `expeditionDocumentDate`. En la segunda llamada: `secureService`, `secureServiceId`, `questionnaireCode`, `answers` (objeto JSON)	Object	En la primera llamada devuelve un cuestionario para el challenge. En la segunda devuelve un código y un mensaje con el resultado de la verificación de la cuenta
getBinInfo()	`bin`	Object	Devuelve un objeto con la información del bin de la tarjeta de crédito
requestCardAsyncToken()	`totalAmount`, `returnUrl`, `email`, `description`	Object	Devuelve un token de Card Async
requestTransferToken()	`amount`, `callbackUrl`, `documentType`, `documentNumber`, `email`, `paymentDescription`, `userType`	Object	Devuelve un token de Transfer In
requestCashToken()	`totalAmount`, `currency`, `identification`, `documentType`, `name`, `lastName`, `email`, `description`	Object	Devuelve un `token` de Cash In que después puedes usar para inicializar una transacción de Cash In

Cargos recurrentes

Nombre	Parámetros	Devuelve	Descripción
requestSubscriptionToken()	`card`	Object	Devuelve un token de cargo recurrente
requestCardSubscriptionAsyncToken	`currency`, `email`, `cardNumber`, `callbackUrl`	Object	Devuelve un token de cargo recurrente de Card Async
getBankList()		Object	Devuelve la lista de bancos disponibles para cargos recurrentes por transferencia
requestTransferSubscriptionToken()	`documentNumber`, `bankCode`, `name`, `lastName`, `accountNumber`, `documentType`, `accountType`, `email`, `currency`	Object	Devuelve un `token` junto con un `secureId` y un `secureService`. Ese token se puede usar después para crear un cargo recurrente por transferencia. Antes tendrás que confirmar los datos de la cuenta iniciando y respondiendo un challenge con el método de validación segura

Dispersiones

Nombre	Parámetros	Devuelve	Descripción
requestCashOutToken()	`totalAmount`, `currency`, `documentNumber`, `documentType`, `name`, `lastName`, `email`, `description`	Object	Devuelve un `token` de Cash Out que después puedes usar para inicializar una transacción de Cash Out

🚀 Aplicación de ejemplo

Puedes encontrar una aplicación de ejemplo en nuestro GitHub android project repository.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

⚙️ Instalación y configuración#

🛠️ Uso#

Parámetros de configuración#

Ejemplos de pago único#

requestToken()#

3DS#

requestSecureValidation()#

getBinInfo()#

Ejemplos de cargos recurrentes#

requestSubscriptionToken()#

Ejemplos de dispersiones#

requestCashOutToken()#

🚦 Manejo de respuestas#

🎨 Sensory Branding#

Propiedades#

Propiedades#

Siguientes pasos#

📖 Resumen de referencia#

Pago único#

Cargos recurrentes#

Dispersiones#

🚀 Aplicación de ejemplo#

⚙️ Instalación y configuración

🛠️ Uso

Parámetros de configuración

Ejemplos de pago único

requestToken()

3DS

requestSecureValidation()

getBinInfo()

Ejemplos de cargos recurrentes

requestSubscriptionToken()

Ejemplos de dispersiones

requestCashOutToken()

🚦 Manejo de respuestas

🎨 Sensory Branding

Propiedades

Propiedades

Siguientes pasos

📖 Resumen de referencia

Pago único

Cargos recurrentes

Dispersiones

🚀 Aplicación de ejemplo