Kushki iOS 

WARNING

⚠️ Deprecated Library

La librería Kushki ya no recibe mantenimiento y no tendrá actualizaciones ni correcciones futuras.
Migra a las nuevas librerías según tu procesador:

kushki-ios-intel

kushki-ios-arm

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

⚙️ Instalación y configuración

Si aún no la tienes instalada, descarga la última versión de CocoaPods.

Incluye la librería en tu proyecto. Agrega a tu Podfile la línea que corresponda a tu procesador:

Para procesadores basados en Intel:

Para procesadores basados en Apple Silicon (M1/M2/M3):

Haz clic aquí para ver las instrucciones completas para simuladores y dispositivos ARM.

Ejecuta este comando en la Terminal:

Para actualizar a nuestra última versión:

🛠️ Uso

Después de instalarla, crea una instancia de Kushki para usar todos los métodos disponibles.

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	Define si estás en el 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

Aquí tienes los métodos disponibles en nuestra librería de iOS, 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 🇨🇱

🏦 Transfer In

💵 Cash In

requestToken()

Para solicitar un token con los datos de la tarjeta.

Parámetros obligatorios

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

Parámetros opcionales

Propiedad	Tipo	Descripción
`months`	`Integer`	Installments (Chile only). Min: 2, Max: 48.

3DS

El método requestToken de la librería de Kushki en iOS hace lo necesario para que los comercios con 3DS activado puedan verificar transacciones con ese servicio.

En las implementaciones con 3DS tienes que validar que specificationVersion sea mayor que 2.0.

Respuesta

Si el servicio 3DS no está activo, al consumir el método requestToken() recibirás una respuesta parecida a esta

{
     "token": "PmgVbd100000Pe5VEU098014S84wiTFR"
}

Si el servicio 3DS está activo, al consumir el método requestToken() recibirás una respuesta parecida a esta

{
    "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 que se usa para autenticar la transacción
secureId	String	El secureId que obtienes en la respuesta del token
security	Object	El objeto security que recibes 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 trae los datos de la transacción comprimidos y codificados en Base64. Lo entregan las franquicias.
security.authRequired	Boolean	Indica si el challenge de 3DS es obligatorio o no.

requestSecureValidation()

Tienes que validar que el flujo 3DS se completó correctamente y que se superó el challenge de 3DS. Para eso usa el método requestSecureValidation(), enviando el parámetro secureId que obtuviste del método requestToken().

Respuesta

El objeto de respuesta debe tener esta estructura para completar el flujo 3DS válido.

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

Ejemplo

getCardInfo()

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

Solicitud

Requerido

Propiedad	Tipo	Descripción
cardNumber	String	El número de la tarjeta de crédito de la que quieres la info

Ejemplos de cargos recurrentes

💳 Card Subscription

⏳ Async Subscription

requestSubscriptionToken()

To request a recurring charge token.

Parámetros obligatorios

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

Ejemplos de dispersiones

💸 Cash Out

requestCashOutToken()

Para solicitar un token de Cash Out puedes usar este método

Requerido

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

Opcional

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

🚦 Manejo de respuestas

Usa DispatchQueue.main.async para actualizar la UI según el resultado.

Resultados correctos

Usa la clase DispatchQueue con el método de instancia async para procesar el resultado del método requestToken o requestSubscriptionToken. Recibirás un objeto Transaction cuando termine la llamada a Kushki; si salió bien, el token estará disponible en su propiedad token.

Resultados con error

Si la transacción falla, el código de error y la descripción llegan en las propiedades code y message.

🎨 Branding sensorial de Visa/Mastercard

La animación de branding de la tarjeta le da al usuario 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 termine.

Visa

Mastercard

Animación de Visa

Llama a la función initVisaBrandingAnimation y envía una instancia de UIViewController como parámetro.

Propiedades

Propiedad	Tipo	Requerido	Descripción
uiViewController	UIViewController	Yes	Instance of UIViewController

Respuesta

Propiedad	Tipo	Descripción
result	boolean	Animation result.
err	Error	Error message.

Siguientes pasos

Recuerda que para seguir con el flujo de pago tienes que enviar a tus servidores el token que recibes, como se muestra en el código de ejemplo dentro de un alert.

Para terminar el proceso de pago, ve a nuestra referencia de la API

📖 Resumen de referencia

Pago único:

Crear un token de tarjeta

Obtener la información del bin

Crear un Card Async Token

Crear un token de Transfer In

Crear un token de Cash In

Cargos recurrentes:

Create a Card recurring charge token

Get an Async Card recurring charge

Dispersiones:

Create a Cash Out token

Pago único

Nombre	Parámetros	Devuelve	Descripción
requestToken()	`card`, `totalAmount`, `months`	Object	Devuelve un token de tarjeta
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
getCardInfo()	`cardNumber`	Object	Devuelve un objeto con la información del bin de la tarjeta de crédito
requestCardAsyncToken()	`totalAmount`, `returnUrl`, `email`, `description`	Object	Devuelve un card async token
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 luego sirve para iniciar una transacción de Cash In

Cargos recurrentes

Name	Parameters	Returns	Description
requestSubscriptionToken()	`card`	Object	Returns a recurring charge token
requestSubscriptionCardAsyncToken	`currency`, `email`, `cardNumber`, `callbackUrl`	Object	Returns an async card recurring charge token

Dispersiones

Nombre	Parámetros	Devuelve	Descripción
requestCashOutToken()	`totalAmount`, `currency`, `identification`, `documentType`, `name`, `lastName`, `email`, `description`	Object	Devuelve un `token` de Cash Out que luego sirve para iniciar una transacción de Cash Out

🚀 Aplicación de ejemplo

Puedes encontrar una aplicación de ejemplo en nuestro repositorio del proyecto iOS en GitHub.

¿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()#

getCardInfo()#

Ejemplos de cargos recurrentes#

requestSubscriptionToken()#

Ejemplos de dispersiones#

requestCashOutToken()#

🚦 Manejo de respuestas#

🎨 Branding sensorial de Visa/Mastercard#

Animación de Visa#

Propiedades#

Respuesta#

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()

getCardInfo()

Ejemplos de cargos recurrentes

requestSubscriptionToken()

Ejemplos de dispersiones

requestCashOutToken()

🚦 Manejo de respuestas

🎨 Branding sensorial de Visa/Mastercard

Animación de Visa

Propiedades

Respuesta

Siguientes pasos

📖 Resumen de referencia

Pago único

Cargos recurrentes

Dispersiones

🚀 Aplicación de ejemplo