Developer API

Overview

Add the ability to collect credit card payments from your mobile app by integrating with Swipe. We have support for iPhone, iPad, and iPod devices.

Setting Up Your App

In order for Swipe to call back into your app, you'll need to register a BundleURL in your Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.companyname.DemoApp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com-companyname-demoapp</string>
    </array>
  </dict>
</array>


If you don't need Swipe to call back, you can skip this step.

Crafting the Request

The request is simply a set of query string parameters appended to our URL handler. Be sure to properly encode the query string parameters.

URL handler: com-appninjas-iswipe://charge/1.0.0/

The parameters we accept include:

• returnUrl - your app's URL handler that you set up previously (e.g. com-companyname-demoapp://action/)
• returnAppName - name of the app the returnUrl will open (required if returnUrl is set)
• fm - if set to 1, the FileMaker-compatible response format will be used
• amount - amount of the transaction (e.g. 10.00, 0.99)
• email - customer's email address for receipt
• firstName - billing first name
• lastName - billing last name
• address - billing street address
• city - billing city
• state - billing state or province (e.g. OH, BC)
• zip - billing zip or postal code
• phone - biling phone number
• country - billing country code (e.g. US)
• invoiceNumber - merchant-assigned invoice number
• description - description of goods or service

Here's a sample request. Please take note of the correct encoding of the parameters:

com-appninjas-iswipe://charge/1.0.0/?amount=10.99&email=john%40example.com&returnURL=com-companyname-demoapp%3A%2F%2Faction%2F&returnAppName=DemoApp

Making the Request

After crafting the request into NSURL* url, you can call into our app using the following code:

UIApplication* app = [UIApplication sharedApplication];

if( [app respondsToSelector:@selector(canOpenURL:)] && ![app canOpenURL:url] )
{
    // handle case when Swipe is not installed
}

[[UIApplication sharedApplication] openURL:url];


Handling the Response

If you provided us with a returnUrl, we will call back into your app with the transaction details. The results of the transaction will be provided via query string parameters. These parameters will begin with ifcc_.

In your UIApplicationDelegate, you'll need to override application:didFinishLaunchingWithOptions: method:

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    NSURL* launchURL = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
    if ( nil != launchURL )
    {
        // handle url
    }
}


Here's the list of parameters that will be included in the response:

• ifcc_responseType - approved, cancelled, declined, or error
• ifcc_amount - amount charged (e.g. 10.99)
• ifcc_cardType - Visa, MasterCard, Amex, Discover, Maestro, Solo, or Unknown
• ifcc_redactedCardNumber - redacted card number (e.g. XXXXXXXXXXXX1111)

Here's a sample response:

com-companyname-demoapp://action/?ifcc_responseType=approved&ifcc_amount=10.99&ifcc_redactedCardNumber=XXXXXXXXXXXX1111&ifcc_cardType=Visa

When the fm=1 parameter is included in the original request, the response is modified by including a dollar-sign ($) before each query value so that they can be accessed by FileMaker Go scripts. For instance, instead of ifcc_responseType=success, $ifcc_responseType=success.