NAV Navbar
Logo

Mobile SDKs

Payload’s mobile SDKs provide a simple and secure embedded mobile interface for accepting payments and interacting with our API.

To get started, jump right to the Installation & Setup section.

Features

Supported Platforms


Android
>=21

iOS
>=10

Installation & Setup

Installation

Android

Add the following to build.gradle

dependencies {
    implementation 'co.payload:payload-android:1.1.7'
}


Manual Install

To include Payload’s Android SDK in your project, follow these steps:

  1. Download

Download the latest version from GitHub.

  1. Include in Project

Include the folder in your Android Studio project as a module.


iOS

CocoaPod Install

Manual Install

To include Payload’s iOS SDK in your project, follow these steps:

  1. If it doesn’t exist yet, create a Frameworks group by selecting New Group in Xcode.

  2. Drag and drop the Payload.framework plugin into this group.

  3. Under Build Settings, navigate to Framework search paths and add the search path $(PROEJECT_DIR)/Frameworks.

  4. Navigate to General section under targets.

  5. Under Embedded Binaries use the icon to add the Payload.framework.


Setup

import co.payload.pl;
import co.payload.android.Payload;

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        pl.api_key = "test_client_key_3bezxdVdCLpYP9yJ5odpg";
    }
}
import PayloadAPI

class ViewController: UIViewController {
    override func viewDidLoad() {
        Payload.api_key = "test_client_key_3bezxdVdCLpYP9yJ5odpg"
    }
}
// ViewController.h
#import <Payload/Payload-Swift.h>
// ViewController.m
@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    Payload.api_key = @"test_client_key_3bezxdVdCLpYP9yJ5odpg"
}

Once the SDK is installed, you can import the library and set the client key to be able to interact with your Payload account. Because these are client-side libraries, they require the client key, not the api key.

Your client key can be found from your dashboard under Settings > API Keys where you’ll find both a testing and a production key.


Making API Calls

Making Requests

You can make API calls using the the built-in asynchronous object APIs included in the SDK. Not all objects are available from the client-side libraries.

Select

Payload.all(pl.Customer.select(), new Payload.Callback<List<pl.Customer>>() {
    public void then(List<pl.Customer> custs) {
    }
});
Payload.all(Payload.Customer.select(), {(obj: Any) in
    let custs = obj as? [Payload.Customer]
    /* Do something with response */
})
[Payload all: [Customer select] :^(id obj) {
    NSArray *custs = obj;
    Customer *cust = [custs firstObject];
    /* Do something with response */
}];

Create

Payload.create(pl.Customer(){{
    set("email", "test@gmail.com");
    set("name", "Test Account");
}}, new Payload.Callback<pl.Customer>() {
    public void then(pl.Customer cust) {}
});
Payload.create(Payload.Customer([
    "email": "test@gmail.com",
    "name": "Test Account"
]), {(obj: Any) in
    let cust = obj as? Payload.Customer
    /* Do something with response */
})
[Payload create: [[Customer alloc] init:@{
    @"email": @"test@gmail.com",
    @"name": @"Test Account"
}] :^(id obj) {
    Customer *cust = obj;
}];

Update

Payload.update(cust.set("email", "test@gmail.com"),
    new Payload.Callback<pl.Customer>() {
        public void then(pl.Customer cust) {}
    });
cust.update([
    "email": "test@gmail.com"
], {(obj: Any) in
    let cust = obj as? Payload.Customer
    /* Do something with response */
})
[cust update:@{
    @"email": @"test@gmail.com"
} :^(id obj) {
    Customer *cust = obj;
    /* Do something with response */
}];

Delete

Payload.delete(cust, new Payload.Callback<pl.Customer>() {
    public void then(pl.Customer cust) {}
});
cust.delete({(obj: Any) in
    /* Do something with response */
})
[cust delete:^(id obj) {
    /* Do something with response */
}];

Integrated Checkout

Payload Checkout is a UI toolkit for integrating simple payment acceptance into your portal or platform. Below are a few of the built-in the benefits of accepting payments using the checkout toolkit.

Integrate

Open Checkout


public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        pl.api_key = "test_client_key_3bezxdVdCLpYP9yJ5odpg";

        Payload.checkout(new pl.Payment(){{
            set("amount", 10.0);
        }}).processed((pl.Payment pmt) -> {
            handleSuccess(pmt);
        }).error((Exception err) -> {
            handleError(err);
        });
    }
}
import UIKit
import PayloadAPI

class ViewController: UIViewController, PayloadPaymentDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Payload.api_key = "test_client_key_3bezxdVdCLpYP9yJ5odpg"

        Payload.Checkout(Payload.Payment([
            "amount": 10.0
        ]), delegate: self)
    }

}
#import <UIKit/UIKit.h>
#import <Payload/Payload-Swift.h>

@interface ViewController : UIViewController<PayloadPaymentDelegate>
@end
@interface ViewController ()
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.checkout = [[Checkout alloc] init:[[Payment alloc] init:@{
        @"amount": @10,
        @"processing_id": @"acct_3bfCMwa8OwUbYOvUQKTGi",
    }] delegate: self ];
}

@end

To open the Checkout UI, you must call Payload.Checkout with a Payload Payment object. The minimum required fields for the Payment object are amount and processing_id.

Once a payment request is submitted to beginTransaction, you can track the progress of a transaction by monitoring the payment events described below.

Watch for Events

You can wait for callback events from the Checkout plugin. The available events are processing, processed, declined, and error. For a detailed breakdown, see Processing Payments.


Close Checkout

public class MainActivity extends Activity {
    Payload.Checkout checkout;
    ...
    private void closeCheckout() {
        this.checkout.close()
    }
}
class ViewController: UIViewController, PayloadPaymentDelegate {
    Payload.Checkout checkout;
    ...
    func closeCheckout() {
        self.checkout.close()
    }
}
@interface ViewController ()
@property Checkout *checkout;
@end

@implementation ViewController

- (void)closeCheckout {
    [self.checkout close]
}

@end

By default, once a transaction has processed the Checkout will dismiss automatically. The user can also dismiss the Checkout plugin.

The Checkout plugin can be dismissed programatically using the ‘close’ method.


Theme

/* Android theme customization coming soon */

PayloadFormLabel.appearance().textColor = UIColor.blueColor();
PayloadCard.appearance().backgroundColor = UIColor.cyanColor();
PayloadCardContainer.appearance().backgroundColor = UIColor.lightGrayColor();
PayloadPayBtn.appearance().backgroundColor = UIColor.blueColor();
Class Name Description
PayloadFormLabel The labels above the inputs
PayloadTitle The title text on the keyed UI
PayloadCardContainer The card display container
PayloadCard The card display example
PayloadCardLabel The labels above the inputted text in the card display
PayloadCardTextField The inputted text in the card display
PayoadPayBtn The pay button at the bottom of the page

Processing Payments

Events

Processing

The processing event is triggered once the information has been keyed in and the payment request has now been submitted to Payload for processing.

Processed

The processed event is triggered if the requested payment was approved and successfully processed.

Declined

The declined event is triggered if a payment was unsuccessful. You can inspect the declined reason by reviewing the status_code and status_message attributes.

Error

The error event is triggered if an error occurs while attempting to process the payment request.

Error Description
UnknownRequestError An unknown network error occured
LostConnectivity Connectivity was lost and offline payments is disabled
RequestError A request error occured.
Inspect error_type, error_description, and details for information.

Payment Form

Use Payload.submit and Input to build and submit a simple and secure payment form in your app.

Add Inputs to Layout

<co.payload.android.Input
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:tag="pl:card"/>

Add any co.payload.android.Input fields used in collecting payment details into your layout. The android:tag attribute can be any payment or payment method field, prefixed with "pl:".


Submit the Form

Payload.submit(view, new pl.Payment(){{
    set("amount", 10.0);
}}).processed((pl.Payment pmt) -> {
    handleSuccess(pmt);
}).error((Exception err) -> {
    handleError(err);
});
/* iOS payment form coming soon */
/* iOS payment form coming soon */

To submit the form, create a button or trigger that will call the Payload.submit function. The Payload.submit accepts the view that contains the active inputs as the first parameter and a Payload.Payment object with additional transaction details for the request as a second paramater.


Google and Apple Pay

Payload.googlepay(view, new pl.Payment(){{
    set("amount", 10.0);
}}).processed((pl.Payment pmt) -> {
    handleSuccess(pmt);
}).error((Exception err) -> {
    handleError(err);
});
/* ApplePay support coming soon */
/* ApplePay support form coming soon */

To open Google Pay, create a button or trigger that will call the Payload.googlepay function. The Payload.googlepay accepts the view that contains the active inputs as the first parameter and a second paramater of a Payload.Payment object with additional transaction details for the request.

View the Google Pay Docs

View the Apple Pay Docs

Security

All supported card readers are certified on the Payload platform and our SDKs and APIs are certified & compliant with the PCI-DSS standard.

All supported devices utilize end-to-end encryption for all sensitive card information and all requests are transmitted directly from the host device to Payload’s secure PCI environment.

You can read more about the general security features of Payload in our Security & Compliance section.