mobile: iOS/Swift integration

The easiest way to start accepting payments on iOS devices using ProcessOut is to use the ProcessOut iOS SDK. The SDK will take care of tokenizing your customers’ card numbers, so that you can send those generated tokens to your backend and process payments ↗.


Requirements

The ProcessOut iOS SDK is available on iOS 8.0+.

ProcessOut is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'ProcessOut'

and run in your terminal:

pod install

You’ll then be able to import ProcessOut in your code base and configure the SDK with your ProcessOut API credentials.

import UIKit
import ProcessOut

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, 
        didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        // You can find your project ID in your dashboard
        ProcessOut.Setup(projectId: "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", urlScheme: "your-app-url-scheme")
        // Your application code goes here
        return true
    }
}

Note that you will need to specify your app custom URL scheme in order to handle 3DS fallbacks when performing an authorization request.

Tokenize a card

Once all set up, you’ll be able to tokenize the card numbers. The returned token is a simple string.

let card = ProcessOut.Card(cardNumber: "4242424242424242", expMonth: 11, expYear: 19, cvc: nil, name: "NAME")
ProcessOut.Tokenize(card: card, metadata: [:], completion: {(token, error) -> Void in
    if error != nil {
        switch error! {
        case .BadRequest(let message, let code):
            print(message, code)
        case .InternalError:
            print("An internal error occured")
        case .MissingProjectId:
            print("Check your app delegate file")
        case .NetworkError:
            print("Request could not go through")
        }
    } else {
        // Send token to your backend to charge the customer
        print(token!)
    }
})

Alternative payment methods

First you’ll need to generate an invoice in your backend and retrieve that invoice ID in order to fetch all the active configurations available for that invoice. You’ll also need to provide this invoice with a specific return url of this form: yourapp://processout.return

curl -X POST https://api.processout.com/invoices \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    -d name="Awesome invoice" \
    -d amount="9.99" \
    -d currency=USD 
    -d return_url="yourapp://processout.return"
var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

client.newInvoice().create({
    name:     "Amazing item",
    amount:   "4.99",
    currency: "USD",
    return_url: "yourapp://processout.return"
}).then(function(invoice) {
    // invoice is our newly created resource

}, function(err) {
    // An error occured

});
import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

invoice = client.new_invoice().create({
    "name":     "Amazing item",
    "amount":   "4.99",
    "currency": "USD",
    "return_url": "yourapp://processout.return"
})
require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

invoice = client.invoice.create(
    name:     "Amazing item",
    amount:   "4.99",
    currency: "USD",
    return_url: "yourapp://processout.return"
)
<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

$invoice = $client->newInvoice()->create(array(
    "name"     => "Amazing item",
    "amount"   => "4.99",
    "currency" => "USD"
    "return_url" => "yourapp://processout.return"
));
import "gopkg.in/processout.v4"
client := processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

iv, err := client.NewInvoice().Create(processout.InvoiceCreateParameters{
    Invoice: &processout.Invoice{
        Name:     processout.String("Amazing item"),
        Amount:   processout.String("4.99"),
        Currency: processout.String("USD"),
        ReturnUrl: processout.String("yourapp://processout.return")
    },
})

ProcessOut also supports alternative payment methods with a redirection flow. First of all, make sure an alternative payment method has been activated on your account.

Then start by listing all the available alternative payment methods configurations:

ProcessOut.listAlternativeMethods { (gateways, error) in
    for gateway in gateways! {
        // Display the gateway to your users
    }
}

Then, you’ll be able to display your APM to your users using the getRedirectURL method of a gateway.

You’ll also need to handle your customers returning to your app in your app delegate. First of all, register your app URL scheme. Please note that your URL scheme should be of the form: yourapp://processout.return Then you’ll be able to handle web returns:

// This method handles opening native URLs (e.g., "yourapp://...")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let processoutResult = ProcessOut.handleURLCallback(url: url) {
        if processoutResult.success {
            switch processoutResult.type {
            case .APMAuthorization:
                let token = processoutResult.value
                // You can now send this token to your backend to complete the charge
                break
            case .ThreeDSResult:
                let invoiceId = processoutResult.value
                // Send the invoice ID to your backend to complete the charge
                break
            }
            case .ThreeDSFallbackVerification:
                ProcessOut.continueThreeDSVerification(invoiceId: processoutResult.invoideId, token: processoutResult.value, completion: {(invoiceId, error) in
                    // If no error, send the invoice ID to your backend to complete the charge
                })
                break
        }
    } else {
        // This was not a processout url – do whatever url handling your app
        // normally does, if any.
        return false
    }
    return false
}

There are two cases where your app could be opened from a return URL: 1- From an Alternative Payment Method authorization request in which case a APM token is returned 2- From a ThreeDS1 check in which case the invoice ID is returned (please note that even when performing a 3DS2 challenge, in some cases if the 3DS2 is not supported a fallback to 3DS1 will be performed.)

In either case you should send these information back to your backend to create the charge.

Next steps

You’re all set! You can now send the newly created token to your backend to:

If you’re currently setting up payments for your mobile application, you’re also most likely developping it for the Android platform as well. We have a very similar SDK available for Android devices, available here ↗. Feel free to check it out!