Native iOS SDK
Device Supported
Connection Type | Card Type | |
---|---|---|
iDynamo6 | Lightning iAP 2 | MSR, Contact, Contactless |
kDynamo | Lightning iAP 2 | MSR, Contact, Contactless |
Xcode Build Version
12.5.1
Dependency
What it is | Location | |
---|---|---|
MagTek libMTSCRA | MagTek's device SDK | https://www.magtek.com/Content/SoftwarePackages/99510 111.zip |
Minimum Targeted iOS Version
iOS 13.0
Getting Started
In order to access External Accessory, you need to add the following to info.plist
Type | Value | |
---|---|---|
UISupportedExternalAccessoryProtocols | Array or String | com.magtek.idynamo |
NSBluetoothAlwaysUsageDescription | String | Allow usage of Bluetooth LE for other Bluetooth LE devices |
NSBluetoothPeripheralUsageDescription | String | Allow usage of Bluetooth LE for other Bluetooth LE devices |
Error Code
List of possible error codes
Code | Description |
---|---|
-1 | Generic Error/Unknown |
1 | No Internet Connection |
1001 | Device battery too low for normal operation. |
1002 | Device is busy, can't respond. |
3000 | Unknown EMV error |
3001 | EMV Transaction already started. |
3002 | No active EMV session |
Delegate callback
On Result
EventArg
property | type | description |
---|---|---|
version | String | Data structure can change in the future, version will keep the current data structure according the the number.` |
event | Event | Event object |
eventData | String | Event data from processing result |
Event
property | type | description |
---|---|---|
domain | EventDomain | EMVTransaction , TokenizedTransaction , DeviceConfiguration , DeviceInformation , CardPresentProcessing , ManualEntryProcessing , PhysicalDeviceConnection , DeviceCommunication , DeviceState |
type | EventType | EMVDisplayMessage , EMVTransactionStatus , ProcessingResult , ReaderConnection |
func onEvent(event: EventArg) {
do {
let jsonEncoder = JSONEncoder()
jsonEncoder.outputFormatting = .prettyPrinted
let jsonData = try jsonEncoder.encode(event.event)
let json = String(data: jsonData, encoding: String.Encoding.utf8)
if(event.event?.type == .EMVTransactionStatus)
{
let emvTransactionStatus = try JSONDecoder().decode(MagTekEMVStatus.self,
from: event.eventData!.data(using:.utf8)!)
if(emvTransactionStatus.currentProgressIndicator ==
.StartEmulatingContactlessLED)
{
DispatchQueue.main.async {
let led = LedControl(frame: CGRect(x: 10, y: 180, width:
self.view.frame.width - 20, height: 50))
self.view.addSubview(led) //Add EMV led control
}
}
}
//This is how to deserialize the json payload.
let transactionResponse:TransactionResponse = try
JSONDecoder().decode(TransactionResponse.self, from:
event.eventData!.data(using:.utf8)!)
}
catch {
print(error)
}
}
On Error
Error
property | type | description |
---|---|---|
errorDomain | EventDomain | EMVTransaction , TokenizedTransaction , DeviceConfiguration , DeviceInformation , CardPresentProcessing , ManualEntryProcessing , PhysicalDeviceConnection , DeviceCommunication , DeviceState |
errorCode | Int | See Error Code for list. |
recoverySuggestion | String | If available recoverySuggestion will suggest how to overcome the error. |
errorDescription | String | Cause of error |
func onError(error: Error) {
do {
let jsonEncoder = JSONEncoder()
jsonEncoder.outputFormatting = .withoutEscapingSlashes
let jsonData = try jsonEncoder.encode(error)
let json = String(data: jsonData, encoding: String.Encoding.utf8)
}
catch {
}
}
Device Configuration
EmergepayDeviceConfig
Allows reconfiguration of device.
Every time firmware is updated, EMV tags and CAPK will need to be updated. Total run time will be around 9 minutes.
Device LED Color:
- Blue – Device is in boot loader mode, EMV transactions will not work until device finish loading firmware.
- Green – Device is in normal main firmware and ready for to start transaction.
parameter | type | required | description |
---|---|---|---|
configType | ConfigType | yes | EMVTags , EMVCAPK , Firmware |
var emergepayConfig:EmergepayDeviceConfig = EmergepayDeviceConfig();
_ = emergepayConfig.start(configType: .EMVCAPK)
Card Present Transaction
Credit Sale
EmergepayCardPresent
Main card present class
property | type | required | description |
---|---|---|---|
deviceType | DeviceType | yes | RealDevice or SimulatedMagTekDevice |
environment | EmergepayEnvironment | yes | Production or SandBox |
delegate | EmergepayAPIDelegate | yes | Controller delegate for onError and onEvent |
version | String | yes | Data structure can change in the future, version will keep the current data structure according the the number. |
TransactionData
Transactional data that will be use by emergepay back end
parameter | type | required | description |
---|---|---|---|
transactionType | String | yes | "CreditReturn", "CreditSale", "CreditAuth" |
amount | String | yes | Minimum 4 character amount to charge, ex: 0.99 |
tipAmount | String | yes | Minimum 4 character amount to charge, ex: 0.99 |
transactionReference | String | yes | Can be any string to describe the transaction |
externalTransactionId | String | yes | V4 UUID |
cashierId | String | yes | Can be any string to describe the cashier/register |
EMVOptions
EMV options to pass to reader
parameter | type | required | description |
---|---|---|---|
transactionTime | String | yes | EMV time during for a transaction. Range from 0-255 seconds. 0 means emv transaction will not time out. |
cardType | CardInputType | yes | Swipe , Contact , SwipeContact , Contactless , ContactContactless , SwipeContactContactless |
amount | String | no | EMV transaction amount, this value should match transactionData amount , it will be used to populate EMV tag 9F02 |
Status
The return object of function call
This status is not the processing payload but rather the return code for startTransaction to see whether startTransaction completed successfully or not
parameter | type | description |
---|---|---|
result | Bool | Whether the operation started successfully or not. |
resultMessage | String | If there is an error, the message will provide a description |
recoverySuggestion | String | A description of what will need to be corrected |
let auth = MerchantCredential(token: "", oid: "")
var gpCard:EmergepayCardPresent! = nil;
gpCard = EmergepayCardPresent(authentication: auth, deviceType: .RealDevice);
gpCard.environment = .SandBox;
gpCard.delegate = self;
gpCard.version = "1.0"
_ = gpCard.subscribeToEvent(event: .EMVTransactionStatus, eventValue: .EMVStatusAll)
let transactionData = TransactionData()
transactionData.transactionType = "CreditSale"
transactionData.amount = "1.99"
transactionData.tipAmount = "1.00"
transactionData.transactionReference = "123456"
transactionData.externalTransactionId = "514504e4-1bb8-470f-819b-cf2aacc5282e"
let emvOptions = EMVOptions(transactionTime: "30", cardType: .SwipeContactContactless,
amount: "1.99");
let result = gpCard.startTransaction( emvOptions: emvOptions, transactionData:
transactionData)
Cancel Transaction
Cancels the current EMV transaction, this can only be done before card is inserted/tapped
gpCard.cancelTransaction()
Manual Entry Transactions
EmergepayManualEntry
property | type | required | description |
---|---|---|---|
endPoint | String | yes | End point set up in Dashboard to let EmergepayAPI know when transaction is complete. |
environment | EmergepayEnvironment | yes | Production or SandBox |
delegate | EmergepayAPIDelegate | yes | Controller delegate for onError and onEvent |
version | String | yes | Data structure can change in the future, version will keep the current data structure according the the number. |
Credit Sale
CreditSaleConfig
property | type | required | description |
---|---|---|---|
baseAmount | String | yes | Minimum 4 character amount to charge, ex: "1.99" |
externalTransactionId | String | yes | V4 UUID |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Any string representing Register ID or Employee ID |
tipAmount | String | no | Minimum 4 character amount to charge, ex: "1.99" |
return object is Status
let creditSaleConfig = CreditSaleConfig(baseAmount: "1.99",
externalTransactionId: "514504e4-1bb8-
470f-819b-cf2aacc5282e",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1",
tipAmount: "1.00")
let gp = EmergepayManualEntry(authentication: auth);
gp.environment = .SandBox
gp.delegate = self;
gp.version = "1.0"
gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
let result = gp.creditSale(controller: self, config: creditSaleConfig)
Credit Auth
CreditAuthConfig
property | type | required | description |
---|---|---|---|
baseAmount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Any string representing Register ID or Employee ID |
tipAmount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
Return object is Status
let creditAuthConfig = CreditAuthConfig(baseAmount: "1.99",
externalTransactionId: "514504e4-1bb8-
470f-819b-cf2aacc5282e",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1",
tipAmount: "1.00")
let gp = EmergepayManualEntry(authentication: auth);
gp.environment = .SandBox
gp.delegate = self;
gp.version = "1.0"
gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
let result = gp.creditAuth(controller: self, config: creditAuthConfig)
Credit Return
CreditReturnConfig
property | type | required | description |
---|---|---|---|
baseAmount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Any string representing Register ID or Employee ID |
Return object is Status
let creditReturnConfig = CreditReturnConfig(baseAmount: "1.99",
externalTransactionId: "514504e4-1bb8-
470f-819b-cf2aacc5282e",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1")
let gp = EmergepayManualEntry(authentication: auth);
gp.environment = .SandBox
gp.delegate = self;
gp.version = "1.0"
gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
let result = gp.creditReturn(controller: self, config: creditReturnConfig)
Credit Save Card
CreditSaveCardConfig
property | type | required | description |
---|---|---|---|
externalTransactionId | String | yes | V4 UUID |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Any string representing Register ID or Employee ID |
Return object is Status
let creditSaveCardConfig = CreditSaveCardConfig(externalTransactionId: "514504e4-1bb8-
470f-819b-cf2aacc5282e",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1")
let gp = EmergepayManualEntry(authentication: auth);
gp.environment = .SandBox
gp.delegate = self;
gp.version = "1.0"
gp.endPoint = "http://ios.test.gravitypayments.com/transactions/complete";
let result = gp.creditSaveCard(controller: self, config: CreditSaveCardConfig)
Retrieve Transaction
parameter | type | required | description |
---|---|---|---|
transactionId | String | yes | V4 UUID |
Return object is Status
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
gp.retreiveTransaction(transactionID: "514504e4-1bb8-470f-819b-cf2aacc5282e")
Void Transaction
parameter | type | required | description |
---|---|---|---|
uniqueTransId | String | yes | Unique transaction ID Generated by emergepay |
externalTransactionID | String | yes | V4 UUID |
cashierId | String | no | Register ID or Employee ID |
Return object is Status
let gp = EmergepayAPI.init(authentication: auth)
gp.delegate = self;
gp.voidTransaction(uniqueTransId: "d5601f6158cc4c76b8ed378837edb9a3-
00000000000000000000000000000000", externalTransactionID:
"514504e4-1bb8-470f-819b-cf2aacc5282e",
cashierId:"1")
Adjust Transaction
AdjustmentConfig
property | type | required | description |
---|---|---|---|
uniqueTransId | String | yes | Unique token generated by emergepay |
externalTransactionId | String | no | V4 UUID |
adjustmentType | String | no | Only AuthAdjust is supported |
amount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
tipAmount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
transactionReference | String | no | Can be any string to describe the transaction |
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
let adjustmentConfig = AdjustmentConfig(uniqueTransId:
"c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
externalTransactionId: "514504e4-1bb8-470f-
819b-cf2aacc5282e",
adjustmentType: "AuthAdjust",
amount: "9.99",
tipAmount: "2.00",
cashierId: "1",
transactionReference: "Order 12345")
gp.adjustment(config: adjustmentConfig)
Tokenized Payment
TokenizePaymentConfig
property | type | required | description |
---|---|---|---|
amount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
uniqueTransId | String | yes | Unique token generated by emergepay |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Register ID or Employee ID |
tipAmount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
let tokenConfig = TokenizePaymentConfig(amount: "1.99",
externalTransactionId: "514504e4-1bb8-
470f-819b-cf2aacc5282e",
uniqueTransId:
"c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
billingName: "First and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1",
tipAmount: "1.00")
gp.tokenizedPayment(config: tokenConfig)
Tokenized Auth
TokenizedAuthConfig
property | type | required | description |
---|---|---|---|
amount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
uniqueTransId | String | yes | Unique token generated by emergepay |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Register ID or Employee ID |
tipAmount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
let tokenConfig = TokenizedAuthConfig(amount: "1.99",
externalTransactionId: "60837d13-594e-
4e04-829a-96a05e81ec4a",
uniqueTransId:
"c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1",
tipAmount: "1.00")
gp.tokenizedAuthorization(config: tokenConfig)
Tokenized Refund
TokenizedRefundConfig
property | type | required | description |
---|---|---|---|
amount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
uniqueTransId | String | yes | Unique token generated by emergepay |
billingName | String | no | Name on card |
billingAddress | String | no | Address on card |
billingPostalCode | String | no | Zip code for billing information on card |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Register ID or Employee ID |
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
let tokenConfig = TokenizedRefundConfig(amount: "1.99",
externalTransactionId: "60837d13-594e-
4e04-829a-96a05e81ec4a",
uniqueTransId:
"c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
billingName: "Fist and Last",
billingAddress: "1234 Any St",
billingPostalCode: "00000",
transactionReference: "Order 12345",
cashierId: "1")
gp.tokenizedRefund(config: tokenConfig)
Tokenized Force
TokenizedForceConfig
property | type | required | description |
---|---|---|---|
amount | String | yes | Minimum 4 character amount to charge, ex: 1.99 |
externalTransactionId | String | yes | V4 UUID |
uniqueTransId | String | yes | Unique token generated by emergepay |
transactionReference | String | no | Can be any string to describe the transaction |
cashierId | String | no | Register ID or Employee ID |
tipAmount | String | no | Minimum 4 character amount to charge, ex: 1.99 |
let gp = EmergepayAPI(authentication: auth)
gp.delegate = self;
let tokenConfig = TokenizedForceConfig(amount: "1.99",
externalTransactionId: "60837d13-594e-
4e04-829a-96a05e81ec4a",
uniqueTransId:
"c15156989dbc404aa35b990fad67ca90-58afe32181424d859736b6f5c8045f0b",
transactionReference: "Order 12345",
cashierId: "1")
gp.tokenizedForce(config: tokenConfig)