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
16.2
Real Device Framework
Target this API Framework when building for real device such as iPhone or iPad
Simulated Device Framework
Target this API Framework when building for Simulated iOS/iPadOS device such as Simulated iPhone or Simulated iPad
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)