Payrails SDKs provide 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 want, it starts with the same initialization process.

Including the SDK

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

npm install @payrails/web-SDK

#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/react-native-sdk

Initializing the SDK

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

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);

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

let payrailsClient = Payrails.init(config, {
  // optional, pass custom returnInfo to redirect to after authorization
  returnInfo?: {
    cancel?: string,
    success?: string,
    error?: string
  }
})

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

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 can interact directly with Payrails from your client.

Example authorization flow

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

To ensure your frontend can communicate securely with Payrails, you must first fetch configurations from your server-side application. See the 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();

// 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

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

erchant backend must call the lookup action on the execution used for that payment session.
Merchant client has to update the SDK with the 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. Initialize 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 a mismatch between the authorized amount, which is set on execution on the backend, and what's set on the SDK client, requests will be rejected with 401 HTTP error.

Performance optimizations

Preloading all card form assets before users reach the payment page is possible. This could improve the end-user experience, as secure fields will appear on the page instantly.
The browser will de-prioritize these assets and not slow down the page load, which will 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();

Return Info

You can pass custom return URLs to SDK configuration. This controls the redirect behavior after authorization. This is specifically useful for payment methods needing full-page redirection or 3DS processes.

Property	Type	Description
`cancel`	`string`	URL to redirect to if the customer canceled the flow.
`success`	`string`	URL to redirect to after a successful flow.
`error`	`string`	URL to redirect to after a failed flow.

Content security policy

If you have deployed a content security policy, please contact your account manager for the list of directives required by our SDKs.

Reporting a Vulnerability

If you discover a potential security issue in this project, please get in touch with us at [email protected].