Kushki iOS 

WARNING

⚠️ Deprecated Library
The Kushki library is no longer maintained and will not receive future updates or fixes.

Please upgrade to the new libraries based on your processor:

kushki-ios-intel

kushki-ios-arm

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

⚙️ Install and configure

If you haven't already installed it, get the latest version of CocoaPods.

Include the library in your project. Add the line corresponding to your processor to your Podfile:

For Intel based processors:

For Apple Silicon (M1/M2/M3) based processors:

Click here for complete instructions for simulators and ARM devices.

Run the following command in Terminal:

To update to our latest version:

🛠️ Usage

After installation, create an instance of Kushki to perform all available methods.

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 iOS 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 🇨🇱

🏦 Transfer In

💵 Cash In

requestToken()

To request a token using card details.

Required Parameters

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

Optional Parameters

Property	Type	Description
`months`	`Integer`	Installments (Chile only). Min: 2, Max: 48.

3DS

The requestToken method of the Kushki library on iOS 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

getCardInfo()

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
cardNumber	String	The credit card number to get the info

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
totalAmount	String	The amount you are going to collect as a string

Payouts Examples

💸 Cash Out

requestCashOutToken()

To request a Cash Out token, you can use this method

Required

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`

Optional

Property	Type	Description
email	String	Email address of the client
description	String	A description of the payment

🚦 Handling Responses

Use DispatchQueue.main.async to process the UI based on the result.

Successful Results

The DispatchQueue class with the async instance method to process the result of the requestToken or requestSubscriptionToken method. You will receive a Transaction object once the call to Kushki has completed; if it was successful, the token will be available in its token property.

Failed Results

If the transaction fails, the error code and description are available on the code and message properties.

🎨 Visa/Mastercard 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

Visa Animation

Call the initVisaBrandingAnimation function and send an instance of UIViewController as a parameter.

Properties

Property	Type	Required	Description
uiViewController	uiViewController	Yes	Instance of UIViewController

Response

Property	Type	Description
result	boolean	Animation result.
err	Error	Error message.

Next Steps

Remember that to continue with the payment flow you must send to your servers the token received as shown in the example code as an alert.

To finish the payment process, please go to our API Reference

📖 Reference Summary

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

Payouts:

Create a Cash Out token

One-time Payment

Name	Parameters	Returns	Description
requestToken()	`card`, `totalAmount`, `months`	Object	Returns a card 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
getCardInfo()	`cardNumber`	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`, `description`, `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
requestSubscriptionCardAsyncToken	`currency`, `email`, `cardNumber`, `callbackUrl`	Object	Returns an async card recurring charge token

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 iOS project repository.

Got a suggestion on this documentation? Contact Us.

⚙️ Install and configure#

🛠️ Usage#

Configuration Parameters#

One-Time Payment Examples#

requestToken()#

3DS#

requestSecureValidation()#

getCardInfo()#

Recurring Charges Examples#

requestSubscriptionToken()#

Payouts Examples#

requestCashOutToken()#

🚦 Handling Responses#

🎨 Visa/Mastercard Sensory Branding#

Visa Animation#

Properties#

Response#

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

getCardInfo()

Recurring Charges Examples

requestSubscriptionToken()

Payouts Examples

requestCashOutToken()

🚦 Handling Responses

🎨 Visa/Mastercard Sensory Branding

Visa Animation

Properties

Response

Next Steps

📖 Reference Summary

One-time Payment

Recurring Charges

Payouts

🚀 Example Application