Guides
Dashboard ↗

Setting up your environment

Suggest Edits

Setting up the SDKs

ProcessOut provides SDKs for web and mobile app clients and also for servers. Each of these performs a
separate task but what they all have in common is a main ProcessOut object that you use to access the
API features. The sections below show you the "boilerplate" setup code that you will use repeatedly as you develop a project.

Public and private keys for a project

Throughout our example code, you will see strings like proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x and key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB passed as parameters during initialization.

The first string is an example of a project public key that you use to identify your ProcessOut project (you can think of it as the project's "username"). This is required for both client and server code.
The second string is a corresponding project private key that you use only on the server side to authenticate requests made to your ProcessOut project (you can think of it as the project's "password").

To obtain the public key for your project, go to Dashboard › Developer API › API setup
and copy the text from the Production public key textbox. Create a corresponding private key using the Create new private key button on the same page.

Authenticating in sandbox

To test your code in the sandbox, you must use public and private keys that are slightly different from the
production keys. The sandbox public key is the same as the production key but with the prefix test- added (so proj_gAO1Uu0ysZ... becomes test-proj_gAO1Uu0ysZ...). The private key for production won't work at all in the sandbox and so you must generate a separate key for testing. To add a new sandbox private key, go to the Dashboard and enable the Sandbox mode switch at the bottom of the navigation bar. If you now go to Dashboard › Developer API › API setup as before, you will see a list of sandbox private keys.

Clicking the Create new private key button will now create the sandbox key you need for testing.

Web client

Start by loading the processout.js library in your web page. 

<script src="https://js.processout.com/processout.js"></script>

Note: for security purposes, it is very important that you serve this file only from our content delivery network (CDN) as shown above. You should not keep a local copy of this file on your server.

The processout.js library has no dependencies on jQuery or any other library, so the <script> tag above is all you need to start using the ProcessOut payment platform.

Once this is loaded, you must create a ProcessOut object to access the API using your project public key:

var client = new ProcessOut.ProcessOut(
    "proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x"
);

iOS app client

The ProcessOut SDK (see documentation here) is available for iOS starting from v13.0. To integrate with CocoaPods, please add following statements to a Podfile:

pod 'ProcessOut'
pod 'ProcessOutUI' # Only if you are planning to use prebuilt UI 
pod 'ProcessOutCheckout3DS' # Should be added only if you are planning to use the 3DS2 SDK to handle 3DS payments.

All products are also available via Swift Package Manager.

When the dependency is added, initialize the SDK in your application. We suggest to do it in AppDelegate when application finishes launching to ensure that initialization is done only once.

If you are using ProcessOutUI please configure it in your application as well to avoid potential UI hangs. It is not mandatory to do so but highly recommended.

import ProcessOut
import ProcessOutUI

let configuration = ProcessOutConfiguration(
    projectId: "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    // Optional host app details
    application: .init(name: "Example", version: "1.0.0"),
    isDebug: true // Optional
)
ProcessOut.configure(configuration: configuration)
PricessOutUI.configure() // optional

It is also mandatory to notify the ProcessOut SDK when users return back to the application using scheme-based deep links. For example, if you are using a scene delegate, this may look like the following:

func scene(_ scene: UIScene, openURLContexts urlContexts: Set<UIOpenURLContext>) {
    guard let url = urlContexts.first?.url else {
        return  
    }
    // You can inspect the return value to understand whether link was handled
    // by the SDK or not.
    let isHandled = ProcessOut.shared.processDeepLink(url: url)  
    print(isHandled)  
}

Android app client

ProcessOut SDK supports Android 5.0 (API level 21) and above. Add preferred dependencies to your build.gradle configuration:

// ProcessOut API bindings and components to handle payment flows.
implementation("com.processout:processout-android:<version>")

// Integration with Checkout 3DS SDK.
implementation("com.processout:processout-android-checkout-3ds:<version>")

// Prebuilt customizable UI to handle payment flows.
implementation("com.processout:processout-android-ui:<version>")

Initialize the SDK in your Application class:

ProcessOut.configure(
    configuration = ProcessOutConfiguration(
        application = this,
        projectId = "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
        debug = true, // Optionally enable debug mode for logs.
        enableTelemetry = true, // Optionally send telemetry data to ProcessOut.
        // Optional host app details.
        applicationInformation = ApplicationInformation(
            name = "Example",
            version = "1.0.0"
        )
    )
)

Server

The server API supports 5 languages ( Node.js, Python, Ruby, PHP, and Go) and a REST API interface that you can access using a tool such as curl. For the language APIs, you must first install the appropriate library package from the command line (the curl REST API doesn't need this step):

# No setup required for curl

npm install processout

pip install processout

gem install processout

composer require processout/processout-php

go get gopkg.in/processout.v4  // godoc: https://godoc.org/gopkg.in/processout.v4

When the library package is installed, you can instantiate a ProcessOut object using the project's public and private keys:

curl -X GET https://api.processout.com/ \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB

var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

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

require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

import "github.com/processout/processout-go"

var client = processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB",
)

Note that the curl/REST interface does not remember your keys between calls, so you must pass them each time via the -u/--user option in the format shown.

Updated about 1 month ago

What’s Next