Difference between revisions of "IOS API Documentation"
(→API Introduction) |
(→Sample Usage) |
||
(48 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
=Download = | =Download = | ||
'''[http://cloud9paymentgateway.com/files/PDC/iOS/ iOS SDK Library & Sample Application]''' | '''[http://cloud9paymentgateway.com/files/PDC/iOS/ iOS SDK Library & Sample Application]''' | ||
+ | * <code>iPDCLib.framework</code> is the framework that can be used with your application. | ||
+ | * <code>iPDCApp</code> is the sample app | ||
+ | ** See <code>iPDCApp/ViewController.m</code> file for sample usage of the <code>iPDCLib.framework</code> | ||
+ | ** In the sample code, the framework is placed under <code>iPDCApp/iPDC.libframework</code> directory | ||
+ | ** Always use the latest version of iPDCLib.framework from our web site. | ||
+ | |||
+ | =JSON Protocol Reference= | ||
+ | The native iOS Payment Device Controller module facilitates payment operations via JSON Key-Value pairs. ' | ||
+ | <br>See '''[[JSON API Documentation]]''' for full functionality info. | ||
=Setup= | =Setup= | ||
==Installation== | ==Installation== | ||
+ | # Use the API & Sample Download Link above to download the package and unzip it to a local drive. | ||
# Add iPDCLib.framework to your project like other normal framework. | # Add iPDCLib.framework to your project like other normal framework. | ||
− | # Add "Supported external accessory protocols" to your app's info.plist with value "com.ingenico.easypayemv.spm-transaction" | + | |
− | # | + | ===Bluetooth Instructions(e.g. Ingenico ICMP model)=== |
+ | # Add "Supported external accessory protocols" to your app's <code>info.plist</code> with value <code>"com.ingenico.easypayemv.spm-transaction"</code> (there is a sample <code>info.plist</code> in the <code>iPDCApp</code>directory) | ||
+ | # Enable background communication. Add "Required background" to your app's info.plist with value "App communicates with an accessory" (there is a sample info.plist in the iPDCAPP.zip) | ||
+ | |||
+ | ===IP Based Communication Setup (e.g. Ingenico IPP320 === | ||
+ | For Ingenico IPP320, to find the Payment Terminal IP Address, restart it and hit F2 when you see the RBA version. | ||
+ | |||
+ | =Sample JSON Request= | ||
+ | <code>{ | ||
+ | "GMID": "2001003223", | ||
+ | "GTID": "GT3010020919", | ||
+ | "GMPW": "03", | ||
+ | "TransType": "Sale", | ||
+ | "Medium": "Credit", | ||
+ | "MainAmt": "100", | ||
+ | "NeedSwipeCard": "Y" | ||
+ | }</code> | ||
+ | |||
+ | =API Usage= | ||
+ | ==Basic Flow== | ||
+ | See '''iPDCApp/ViewController.m''' file and [[JSON API Documentation]] for reference | ||
+ | ;1. Initialize | ||
+ | :Call <code>initWithDelegate</code> | ||
+ | ;2. Set general parameters | ||
+ | :Call <code>setProperties</code>. | ||
+ | ;3. Process transactions | ||
+ | :Call <code>postTransactionToUrl:request:withTimeout</code> to process transactions. Repeat as many times as necessary. | ||
+ | ;4. Get transaction response | ||
+ | :<code>TransDataReceived</code> function will be called on payment engine response | ||
+ | |||
+ | ;5. (Optional) to get track data, use <code>performAction</code> request | ||
+ | :<code>ActionDataReceived</code> function will be called in response to additional info request via <code>performAction</code> call (e.g. Track Data) | ||
==API Introduction== | ==API Introduction== | ||
− | + | See '''iPDCApp/ViewController.m''' file and [[JSON API Documentation]] for reference. | |
Class iPDCManager is the main interface. | Class iPDCManager is the main interface. | ||
− | ;1. Protocol | + | ;1. Protocol <code>IPDCManagerNotify</code> includes four events: |
− | :-(void) deviceConnected; ==> | + | :-(void) deviceConnected; ==>triggered when pinpad connected |
− | :-(void) deviceDisconnected;==> | + | :-(void) deviceDisconnected;==>triggered when pinpad disconnected |
− | :-(void) TransDataReceived:(NSData*)data; ==>callback function for when postTransactionToUrl api is called. Param data is the transaction return data with JSON format. This format detail can be found in our JSON API Documentation. | + | :-(void) TransDataReceived:(NSData*)data; ==>callback function for when postTransactionToUrl api is called. Param data is the transaction return data with JSON format. This format detail can be found in our [[JSON API Documentation]]. |
− | :-(void) TrackDataReceived:(NSData*)data; ==>callback function for when readTrackData api is called. Param data is the track2 data with JSON format.This format's detail can be found in our JSON API Documentation. | + | :-(void) TrackDataReceived:(NSData*)data; ==>callback function for when readTrackData api is called. Param data is the track2 data with JSON format.This format's detail can be found in our [[JSON API Documentation]]. |
− | 2. initWithDelegate: Instantiate the '''iPDCManager''' class and set the '''IPDCManagerNotify''' delegate. | + | ;2. <code>initWithDelegate</code> |
− | 3. setProperties: Set the configurations in key-value format. | + | : Instantiate the '''iPDCManager''' class and set the '''IPDCManagerNotify''' delegate. |
− | + | ;3. <code>setProperties</code> | |
− | Prop_RushMode: enable rush mode or not,default value is "false",valid value is "false" and "true" | + | : Set the configurations in key-value format. |
− | Prop_UploadUrl: set where to upload the rush mode transactions ,NO default value. | + | :''Valid Keys'' |
− | Prop_CheckInterval: interval for checking rush mode transactions.default value is 60 | + | :<code>Prop_RushMode</code>: enable rush mode or not,default value is "false",valid value is "false" and "true" |
− | Prop_FailedThreshold: the max count of trying transactions before enter the rush mode,default value is 3 | + | :<code>Prop_UploadUrl</code>: set where to upload the rush mode transactions ,NO default value. |
− | Prop_QuickChip: enable quickchip,default value is "true",valid value is "false" and "true" | + | :<code>Prop_CheckInterval</code>: interval for checking rush mode transactions.default value is 60 |
− | Prop_PinpadIP: Pinpad's IP address for ethernet interface, NO default value. | + | :<code>Prop_FailedThreshold</code>: the max count of trying transactions before enter the rush mode,default value is 3 |
− | Prop_PinpadPort: Pinpad's port number for ethernet interface, default value is 12000 | + | :<code>Prop_QuickChip</code>: enable quickchip,default value is "true",valid value is "false" and "true" |
− | Prop_PinpadInterface: set which interface to use. valid value is "BT" and ETHERNET",NO default value,need to be set explicitly. | + | :<code>Prop_PinpadIP</code>: Pinpad's IP address for ethernet interface, NO default value. |
+ | :<code>Prop_PinpadPort</code>: Pinpad's port number for ethernet interface, default value is 12000 | ||
+ | :<code>Prop_PinpadInterface</code>: set which interface to use. valid value is "BT" and ETHERNET", '''NO default value,need to be set explicitly.''' | ||
+ | :'''NOTE:''' | ||
+ | * → <code>Prop_PinpadInterface</code> key must be explicitly set. This must be called in the main thread only once. | ||
+ | * → Search for <code>bSupportIPP320</code> variable in sample code to learn how to use Bluetooth or Ethernet for connecting to the payment terminal (ICMP is bluetooth, IPP320 is Ethernet. | ||
+ | * → '''For Bluetooth only:''' add "Supported external accessory protocols" to your app's <code>info.plist</code> with value <code>"com.ingenico.easypayemv.spm-transaction"</code> (there is a sample <code>info.plist</code> in the <code>iPDCApp</code>directory) | ||
− | |||
− | |||
− | |||
− | |||
− | + | ;4. <code>postTransactionToUrl:request:withTimeout</code> | |
− | + | :Process the transaction request. This will send the request to url via https protocol unless it is Store & Forward (Rush Mode). The request detail can be found in our [[JSON API Documentation]]. | |
+ | ;* 4a <code>TransDataReceived</code> function | ||
+ | : This function will receive JSON response from the POST above. For instance <code>ResponseCode</code>,<code>AuthCode</code>, <code>ErrorText</code>, etc Use [[JSON API Documentation]] for details. | ||
+ | ;5. <code>performAction</code> request. | ||
+ | : Use parameter {"TransType":"ReadTrackData"} to get track2 data for swipe id cards, in-house gift cards, etc. | ||
+ | ;* 5a<code>ActionDataReceived</code> function | ||
+ | : This function will be called with return data. You can use JSON parameters, such as <code>Track2</code> to retrieve useful data. | ||
=iPassthruManager (DEPRECATED)= | =iPassthruManager (DEPRECATED)= |
Latest revision as of 13:43, 2 November 2018
Cloud9 Payment Gateway Documentation. This site can also be reached at http://docs.cloud9paymentgateway.com
Contents
Download
iOS SDK Library & Sample Application
-
iPDCLib.framework
is the framework that can be used with your application. -
iPDCApp
is the sample app- See
iPDCApp/ViewController.m
file for sample usage of theiPDCLib.framework
- In the sample code, the framework is placed under
iPDCApp/iPDC.libframework
directory - Always use the latest version of iPDCLib.framework from our web site.
- See
JSON Protocol Reference
The native iOS Payment Device Controller module facilitates payment operations via JSON Key-Value pairs. '
See JSON API Documentation for full functionality info.
Setup
Installation
- Use the API & Sample Download Link above to download the package and unzip it to a local drive.
- Add iPDCLib.framework to your project like other normal framework.
Bluetooth Instructions(e.g. Ingenico ICMP model)
- Add "Supported external accessory protocols" to your app's
info.plist
with value"com.ingenico.easypayemv.spm-transaction"
(there is a sampleinfo.plist
in theiPDCApp
directory) - Enable background communication. Add "Required background" to your app's info.plist with value "App communicates with an accessory" (there is a sample info.plist in the iPDCAPP.zip)
IP Based Communication Setup (e.g. Ingenico IPP320
For Ingenico IPP320, to find the Payment Terminal IP Address, restart it and hit F2 when you see the RBA version.
Sample JSON Request
{
"GMID": "2001003223", "GTID": "GT3010020919", "GMPW": "03", "TransType": "Sale", "Medium": "Credit", "MainAmt": "100", "NeedSwipeCard": "Y" }
API Usage
Basic Flow
See iPDCApp/ViewController.m file and JSON API Documentation for reference
- 1. Initialize
- Call
initWithDelegate
- 2. Set general parameters
- Call
setProperties
. - 3. Process transactions
- Call
postTransactionToUrl:request:withTimeout
to process transactions. Repeat as many times as necessary. - 4. Get transaction response
TransDataReceived
function will be called on payment engine response
- 5. (Optional) to get track data, use
performAction
request ActionDataReceived
function will be called in response to additional info request viaperformAction
call (e.g. Track Data)
API Introduction
See iPDCApp/ViewController.m file and JSON API Documentation for reference.
Class iPDCManager is the main interface.
- 1. Protocol
IPDCManagerNotify
includes four events - -(void) deviceConnected; ==>triggered when pinpad connected
- -(void) deviceDisconnected;==>triggered when pinpad disconnected
- -(void) TransDataReceived:(NSData*)data; ==>callback function for when postTransactionToUrl api is called. Param data is the transaction return data with JSON format. This format detail can be found in our JSON API Documentation.
- -(void) TrackDataReceived:(NSData*)data; ==>callback function for when readTrackData api is called. Param data is the track2 data with JSON format.This format's detail can be found in our JSON API Documentation.
- 2.
initWithDelegate
- Instantiate the iPDCManager class and set the IPDCManagerNotify delegate.
- 3.
setProperties
- Set the configurations in key-value format.
- Valid Keys
Prop_RushMode
: enable rush mode or not,default value is "false",valid value is "false" and "true"Prop_UploadUrl
: set where to upload the rush mode transactions ,NO default value.Prop_CheckInterval
: interval for checking rush mode transactions.default value is 60Prop_FailedThreshold
: the max count of trying transactions before enter the rush mode,default value is 3Prop_QuickChip
: enable quickchip,default value is "true",valid value is "false" and "true"Prop_PinpadIP
: Pinpad's IP address for ethernet interface, NO default value.Prop_PinpadPort
: Pinpad's port number for ethernet interface, default value is 12000Prop_PinpadInterface
: set which interface to use. valid value is "BT" and ETHERNET", NO default value,need to be set explicitly.- NOTE:
- →
Prop_PinpadInterface
key must be explicitly set. This must be called in the main thread only once. - → Search for
bSupportIPP320
variable in sample code to learn how to use Bluetooth or Ethernet for connecting to the payment terminal (ICMP is bluetooth, IPP320 is Ethernet. - → For Bluetooth only: add "Supported external accessory protocols" to your app's
info.plist
with value"com.ingenico.easypayemv.spm-transaction"
(there is a sampleinfo.plist
in theiPDCApp
directory)
- 4.
postTransactionToUrl:request:withTimeout
- Process the transaction request. This will send the request to url via https protocol unless it is Store & Forward (Rush Mode). The request detail can be found in our JSON API Documentation.
- 4a
TransDataReceived
function
- 4a
- This function will receive JSON response from the POST above. For instance
ResponseCode
,AuthCode
,ErrorText
, etc Use JSON API Documentation for details. - 5.
performAction
request. - Use parameter {"TransType":"ReadTrackData"} to get track2 data for swipe id cards, in-house gift cards, etc.
- 5a
ActionDataReceived
function
- 5a
- This function will be called with return data. You can use JSON parameters, such as
Track2
to retrieve useful data.
iPassthruManager (DEPRECATED)
Passthru manager is an older version of Payment Device Controller Manager without Store & Forward. It is maintained for backward compatibility. Click on the following link for information on iPassthruManager
From the makers of Cloud9 Payment Processing Gateway and Creditline Credit Card Processing Software