iOS SDK Integration

Integration guide for the SmartOTP iOS SDK, distributed as CakeOTP.xcframework.

WARNING

This page documents the iOS SDK's parameters, results and error codes. Ask CAKE Support for the header files or a sample project for exact method signatures before implementing.

Install

1. Open your Xcode project.
2. Drag CakeOTP.xcframework into the project.
3. Tick Copy items if needed, Create groups, and Add to targets.
4. Select your project target.
5. Under Frameworks, Libraries, and Embedded Content, set the framework to Embed & Sign.
6. Import CakeOTP in your code.

Configure

Param	Type	Required	Default	Description
hostName	String	No	Generated by the SDK	The API host name.
isShowLog	Bool	No	false	Print SDK logs.
Timeout interval	Int	No	30	HTTP request timeout in seconds.

Custom headers are added by initialising a RestEntity object and calling its add function — available both directly and through the update-configurations function.

Overriding the base URL

Every API service accepts an overrideBaseUrl parameter.

WARNING

Passing null or an empty string for overrideBaseUrl does not fall back to hostName — the request fails with Unknown host name. Omit the parameter rather than passing an empty value.

Activate

Param	Type	Required	Default	Description
otp	String	Yes	—	The OTP sent by the server after your backend called Register.
vpBankUserId	String	No	Generated by the SDK	The user id.
vpBankDeviceId	String	No	Generated by the SDK	The device id.
vpBankPartnerId	String	No	Generated by the SDK	The partner id.
deviceOS	String	No	iOS	Device OS for tracking.
pushToken	String	No	—	Push token, if used.
appVersion	String	No	—	App version, if used.
token	String	No	—	The registration token from Register.
registrationId	String	No	—	The registration id from Register.

Returns: ActivateSOTPModel, or a CakeErrorModel carrying code and message.

The otp parameter is the activation_key from the Register response.

Code	Description
3	Parameter invalid
103	Thông tin Partner không chính xác — Partner details are incorrect.
124	OTP không hợp lệ — Invalid OTP.
125	OTP hết hạn sử dụng — OTP expired.
129	Token không hợp lệ — Invalid token.

INFO

The iOS parameters are named vpBankUserId, vpBankDeviceId and vpBankPartnerId. These are generic user, device and partner identifiers despite the tenant-specific naming — pass your own values regardless of which partner you are.

PIN and Storage

Store

Param	Type	Required	Default	Description
pin	String	Yes	—	The user's PIN, 4 or 6 digits.
vpBankUserId	String	No	Generated by the SDK	The user id.

Stores the Soft OTP secret in local storage inside the SDK, encrypted with the PIN.

Check

Param	Type	Required	Default	Description
pin	String	Yes	—	The user's PIN, 4 or 6 digits.

Returns: Bool. Must be called only after storing the Soft OTP successfully.

Clear

Clears the currently stored PIN.

Change PIN

Param	Type	Required	Default	Description
oldPin	String	Yes	—	The current PIN. Pass an empty string when there is no stored PIN.
newPin	String	Yes	—	The new PIN, checked against the two most recent PINs.

Returns: ChangePinResult

Field	Type	Description
success	ChangePinResult	The PIN was changed.
invalidOldPin	ChangePinResult	The old PIN is not valid.
sameOldAndNewPin	ChangePinResult	The new PIN is identical to the old one.
samePreviousPins	ChangePinResult	The new PIN matches one of the stored previous PINs.
unknownFailure	ChangePinResult	An unidentified error.

iOS distinguishes five outcomes where Android reports three — sameOldAndNewPin and samePreviousPins both surface as UNKNOWN_FAILURE on Android.

Generate OTP

Basic

Takes no parameters. Returns: String? — the generated basic Soft OTP.

Advance

Param	Type	Required	Default	Description
challengeKey	String	Yes	—	The challenge key from Create Transaction, hashed from user_id, device_id, registration_id, app_id, transaction_id, transaction_amount and unique_id with the server's private key.

Returns: String? — the generated advance Soft OTP.

Get Status

Returns: status as a String, or a CakeErrorModel.

One of NON_ACTIVATED, ACTIVATED, TEMPORARY_BLOCKED, NOT_CURRENT_USER, NOT_REGISTERED — see Mobile SDK Overview § Status Values.

Code	Description
103	Thông tin Partner không chính xác — Partner details are incorrect.

Sync Time

Returns the server's current timestamp as SyncTimeData, or a CakeErrorModel.

Code	Description
103	Thông tin Partner không chính xác — Partner details are incorrect.
129	Token không hợp lệ — Invalid token.
190108	Tài khoản chưa hoạt động — Account not activated.
190302	OTP không chính xác — Incorrect OTP.

Retire

Deactivates the user's currently active Soft OTP.

Returns: Bool, or a CakeErrorModel.

Code	Description
3	Parameter invalid
103	Thông tin Partner không chính xác — Partner details are incorrect.
129	Token không hợp lệ — Invalid token.

Latest Transaction

Takes no parameters. Returns: LatestTransactionResponseModel, or a CakeErrorModel.

Equivalent to Get Latest Transaction.

Accessors

Field	Type	Description
Get current username	String?	The registered username.
Get current registration_id	String?	The registered registration id.
Get current user id	String?	The registered user id.
Get serial id	String?	The serial id from the server.
Save serial id	—	Stores a serial id you supply yourself.
Get time	GetTimeResponseModel	The server timestamp, via the GetTime API.
Get period	Int?	The TOTP period.
Get remaining validity time	Int	Seconds left on the current OTP. Returns -1 on error.
Check is SOTP registered	Bool	Whether this device has registered SmartOTP.

INFO

getRemainingValidityTime returns -1 on error on iOS, while Android returns an empty value. Check for -1 explicitly rather than treating any falsy result as zero.

Implementation Notes

What	Description
Method signatures	Not listed here. Exact names, argument labels and completion-handler shapes come with the header files from CAKE Support.
RestEntity	Referenced for custom headers with no type definition given.
Error messages	Shown here with Vietnamese diacritics. The SDK may return them without diacritics (Thong tin Partner khong chinh xac) — match on the code, not the text.

Next Steps

• Mobile SDK Overview — concepts shared with Android
• Android SDK Integration — the equivalent guide with full code
• Error Codes — the full error tables