Payrails SDKs provide you with building blocks to create a checkout experience for your customers.

They exist for iOS, Android, web, and React Native. Regardless of the platform, they follow the same principles.

You can integrate with the SDK in three ways.

Drop-in: an all-in-one payment form to accept payments on your website.
Elements: modular payment UI components you can assemble to build a modular payment form.
Secure fields: secure input fields for PCI-compliant cardholder data collection.

The Drop-in contains one-to-many Elements (depending on how many active payment methods you have). Some Elements dealing with cardholder data collection include Secure Fields. All three options are included in our SDK.

Getting started with the SDK

Regardless of which SDK components you would like to use, it all starts with the same initialization process.

Including the SDK

You can install the SDK with your favorite package manager (e.g. npm):

#Mentioning the below source will pick the podspec from Payrails repo
#Otherwise you can add cocoapod trunk as the source
#source 'https://github.com/payrailsapi/payrails-iOS-spec.git'

pod 'Payrails'

// Add the Github package registry to your root project build.gradle file
def githubProperties = new Properties() githubProperties.load(new FileInputStream(file(“github.properties”)))
allprojects {
 repositories {
    ...
      maven {
        url "https://maven.pkg.github.com/payrailsapi/payrails-android-sdk"
        credentials
                {
                    username = githubProperties['gpr.usr'] ?: System.getenv("GPR_USER_NAME")
                    password = githubProperties['gpr.key'] ?: System.getenv("GPR_PAT")
                }
    }
}

npm install @payrails/web-SDK

npm install @payrails/react-native-sdk

Initializing the SDK

Use the init() method to initialize a Payrails client as shown below.

let config = Payrails.Configuration(
    data: <DATA>,
    options: Payrails.Options(
      env: Payrails.Env              // optional, if not specified default is PROD
    )
)

let payrailsClient = Payrails.init(config)

val config = Payrails.Configuration(
data = <data>,
options: Payrails.Options(
    env = Payrails.Env.DEV
)
val payrailsClient = Payrails.init(config)

import '@payrails/web-sdk/payrails-styles.css';
import Payrails from "@payrails/web-sdk";

const config = await fetch("https://give.me.SDK.config.com");
const options = {
    environment: "TEST", // or "PRODUCTION"
    events: {
      onClientInitialized: (execution: WorkflowExecution) => {
          console.log("Payrails client initialized", execution);
      }
    }
}

const payrailsClient = Payrails.init(config, options);

import { PayrailsProvider } from "@payrails/react-native-sdk";

const App = () => {
  const config = useFetch("https://give.me.sdk-config.com");

  return (
    <PayrailsProvider config={config}>
      // Other elements goes here.
    </PayrailsProvider>
  );
};

Your backend should call the Initialize a client SDK endpoint. You simply forward the response to SDK.

Once your SDK is initialized, it is now allowed to interact directly with Payrails from your client.

Example authorization flow

Here's a simple authorization flow with the surface covered by the SDK:

To make sure your frontend can communicate securely with Payrails, you must first fetch configurations from your server-side application. See detailed endpoint reference to Initialize a client SDK.

Example for web

<div id="dropin-container" />

import '@payrails/web-sdk/payrails-styles.css';
import { Payrails } from "@payrails/web-sdk";

// 1. call your server-side app to get SDK configs from there.
const config = await fetch("https://give.me.SDK.config.com");

// 2. Initialize Payrails client.
const payrailsClient = Payrails.init(config, { environment: "TEST" });

// 3. Create a Dropin container: pass your styles, translations, configs and events) 
const dropin = payrailsClient.dropin({
  styles: {
    cardForm: {
      border: "1px solid #eae8ee",
      padding: "10px 16px",
    },
    paymentButton: {
      borderRadius: "4px",
      color: "#1d1d1d",
    },
  },
  translations: {
    cards: {
      placeholder: "Card Number",
      label: "card_number",
    },
  },
  paymentMethodsConfiguration: {
    cards: {
      showCardHolderName,
      showExistingCards,
      showStoreInstrumentCheckbox,
    },
  },
  events: {
    onPaymentSuccess: () => {
      console.log('yay!');
    },
    onPaymentFailed: () => {
      console.log('nah :(');
    },
  },
});

// 4. Mount the Dropin to your DOM 
dropin.mount("#dropin-container");

Learn more

After the SDK is initialized, you can leverage the SDK features to customize the user experience:

custom field validation and errors
subscribe and react to events happening inside the form
customize the style with JSS
save your tokenized card and get a payment instrument for future references

Payment amount update

SDK supports the possibility to update the amount. To achieve that, 2 things have to be done:

Merchant backend has to call the lookup action on the execution which is used for that payment session.
Merchant client has to update the SDK with new amount.

Example:

import '@payrails/web-sdk/payrails-styles.css';
import { Payrails } from "@payrails/web-sdk";

// 1. call your server-side app to get SDK configs from there.
const config = await fetch("https://give.me.SDK.config.com");

let executionId;

// 2. Initialize Payrails client.
const payrailsClient = Payrails.init(config, {
	events: {
    onClientInitialized: async (workflow) => {
      executionId = workflow.executionResponse.id
    }
  }
});

// 3. Initialise dropin
const dropin = payrailsClient.dropin()

// 4. Update amount from the backend
await fetch(`https://do-lookup-with-new-amount-on-backend.com?executionId=${executionId}`)

// 5. Update the SDK Client
payrailsClient.update({
  value: "1"
  currency: "USD"
})

In case of mismatch between authorised amount which is set on execution on the backend and what's set on the SDK client, requests will be rejected with 401: Unauthorised HTTP error.

Performance optimizations

There's a possibility to preload all credit card form assets already before users reach the payment page. This could bring better end user experience, as secure fields will appear on the page instantly.
These assets will be de-prioritised by browser and will not slow down the page load, hence not hurt the user experience.
You can check how preload works on MDN

import { Payrails } from "@payrails/web-sdk";

// function will put a <link rel="preload">'s to <head> with required assets for credit card form
Payrails.preloadCardForm();

Content security policy

If you have deployed a content security policy please reach out to your account manager to get the list of directives required by our SDKs.

Reporting a Vulnerability

If you discover a potential security issue in this project, please reach out to us at [email protected].