API Reference

IOS SDK

Purpose

This document covers the usage of Valor PayTech customized EMV and Contactless certified SDK
which can be integrated with the client iOS mobile apps.

Objectives

  1. Explain the iOS SDK architecture
  2. List the data to be passed on the SDK
  3. API usage

SDK Architecture

The Manufacturer provides the RCKT devices and firmware to communicate with the RCKT devices.
The Valor team develops an iOS mobile app to use the RCKT device, the app will be used for the
certification purpose. The US payment processors will be certifying the RCKT devices using the
internal app. Once the certification is completed, SDK will be created with exposed APIs.
The exposed APIs will take inputs about the merchant and communicate with the Valor gateway which
in turn will communicate with the US processor for transactions.

Pre-Requisite Data

The Client App must provide the below data from Valor to process their payment transactions:

  • EPI
  • Merchant Profile
  • Processor
  • Transaction Server Domain
  • Transaction Server Port

Functional flow

The sequence of the API calling is provided below, and this is a high-level flow.

  • Fetch RCKT devices
  • RCKT connection
  • RCKT Disconnection
  • Download RKI
  • Check Connection status
  • Load Configuration
  • Read Card info
  • Perform transaction
  • Fetch Transaction
  • PIN Input
  • Get Device Info
  • Clear Reversal

Fetch RCKT devices

Retrieve the list of available RCKT devices.

getDevicelist() -> [VPSDKDeviceInfo]?

RCKT connection

Connect to the RCKT device using this method and return the connection status.

connectDevice(name: String, completion: @escaping (_ message: String?, _ status: Bool) -> ())

RCKT Disconnection

Disconnect the Bluetooth connection using this method.

disconnect()

Download RKI

The following method is used to download RKI into the RCKT device.

RKIload(isLive: Bool, keyGroup: String?, rkiUrl: String?, rkiPort: String?, completionHandler:
@escaping ValorSDK.RKIModelResponse)

If you are using a development RCKT device, set the isLive parameter to false. The keyGroup, rkiUrl,
and rkiPort parameters are optional.

If you are using a live RCKT device, set the isLive parameter to true. The keyGroup, rkiUrl, and rkiPort
parameters are mandatory.

Check Connection status

This method is used to check whether the Bluetooth connection status is connected or not

isConnected() -> Bool

Load Configuration

Use this method to load the AID, CAPK, and terminal parameters into the RCKT device.

loadconfig(block: @escaping (_ message: String?, _ status: Bool, _ statusCode:
ValorSDK.VPSDKLoadConfigStatusCode) -> ())

Read Card info

retrieve the card information

consume(requestParam: VPRCKTRequestParam, PaymentCompletionHandler: @escaping
ConsumeCompletionHandler)

Perform transaction

This method is used to perform transactions such as Sale, Void, Auth, and Refund.

performTransaction(request: VPTxnRequestParam, connectionInfo: VPConnectionInfo,  
completionHandler: @escaping (_ response: VPTxnResponse?, _ isCompleted: Bool, \_ msg: String) ->  
())  
Sample Sale Request (Card Not Present)  
let txnServerHost = "valor-dev-nlb-f83b42c8a84549b8.elb.us-east-1.amazonaws.com"  
let txnServerPort = "7890"  
let connection = VPConnectionInfo(txnServerHost: txnServerHost, txnServerPort:  
txnServerPort)  
connection.connectionTimeout = 60

let amount = VPAmount(amount: Int32(amount.getamount() \* 100))  
let txnRequestinfo = VPTxnRequestParam(amount: amount, tranMode: .Credit, tranCode:  
.Sale, epiId: epi)  
let cnp = VPManualCard()  
cnp.cardNo = "411111111111111111"  
cnp.cvv = "999"  
cnp.cardHolderName = "KarthiK"  
cnp.expiryDate = "2512"  
cnp.cardHolderZip = "85284"  
cnp.cardHolderAddress = "8320"  
txnRequestinfo.cnpInfo = cnp

VPSDK.shared.performTransaction(request: txnRequestinfo, connectionInfo: connection) {  
response, isCompleted, msg in  
}

Fetch Transaction

Fetch the transaction list using the transaction number and the last four digits of the PAN. You can
also perform follow-up transactions such as Tip Adjust, Ticket, and Void.

Sample Request for Fetch Transaction:

let txnServerHost = "valor-dev-nlb-f83b42c8a84549b8.elb.us-east-1.amazonaws.com"
let txnServerPort = "7890"
let connection = VPConnectionInfo(txnServerHost: txnServerHost, txnServerPort:
txnServerPort)
connection.connectionTimeout = 60

let amount = VPAmount(amount: Int32(amount.getamount() * 100))
let txnRequestinfo = VPTxnRequestParam(amount: amount, tranMode: .Credit, tranCode:
.Sale, epiId: epi)

let fetchinfo = VPFetchRequest()
fetchinfo.tranNo = "1"
fetchinfo.last4digitspan = "1111"
txnRequestinfo.fetchRequest = fetchinfo
VPSDK.shared.performTransaction(request: txnRequestinfo, connectionInfo: connection) {
response, isCompleted, msg in
}

PIN Input

If you want to obtain PIN input from the user, use this method. It also returns the PIN block and KSN
value.

startPinInput(pan: String?, _processorIndex: String?, message: String, pinInputTimeout: Int32,
block: @escaping (_ message: String?, _ status: Bool, _ pinBlock: Data?, _ ksn: Data?) -> ())

Get Device Info

To retrieve the following information from the device: serial_no, device_name, app_version, rootfs,
kernel, linux_kernel, device_model, cls_kernel, emv_kernel, battery_percent, and battery_status.

getRequestDeviceInfo() -> VPSDKRequestDeviceInfo?

Clear Reversal

The transaction was sent to the switch, but the switch did not respond to the SDK. In such cases, the
SDK sends a reversal request to the switch until a response is received. If necessary, you can
manually clear the reversal request using this method.

resetReversalRequest()