Checkout SDKs

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.

Get started with the SDK

Regardless of which SDK components you want, it starts with the same initialization process.

The Payrails SDK requires a secure context (HTTPS). If testing locally, ensure your development server uses HTTPS.

Include the SDK

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

JavaScript

npm install @payrails/web-sdk

iOS

// Package.swift: Swift Package Manager is the only supported install method
.package(url: "https://github.com/payrails/ios-sdk.git", from: "3.2.0")

React Native

npm install @payrails/react-native-sdk

Initialize the SDK

Use the init() method to initialize a Payrails client as shown below, with configuration. On the web, init() is asynchronous: it loads the SDK bundle and its styles, so await it.

JavaScript

import { Payrails } from "@payrails/web-sdk";
// CommonJS: const { Payrails } = require("@payrails/web-sdk");

const config = await fetch("https://give.me.SDK.config.com").then((r) => r.json());

const payrails = await Payrails.init(config, {
  events: {
    onClientInitialized: (execution) => {
      console.log("Payrails client initialized", execution?.id);
    },
  },
  returnInfo: {
    success: "https://yourapp.com/payment/success",
    cancel: "https://yourapp.com/payment/cancel",
    error: "https://yourapp.com/payment/error",
    pending: "https://yourapp.com/payment/pending",
  },
});

iOS

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

let payrails = try await Payrails.configure(
    with: configuration
)

React Native

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

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

  return (
    <PayrailsProvider
      config={config}
      returnInfo={{
        success: 'https://yourapp.com/payment/success',
        error: 'https://yourapp.com/payment/error',
        cancel: 'https://yourapp.com/payment/cancel',
      }}
		>
      // 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 } 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").then((r) => r.json());

// 2. Initialize Payrails client
const payrails = await Payrails.init(config);

// 3. Create a Dropin: pass your appearance, translations and configs
const dropinConfig = {}; // sample dropin config
const dropin = payrails.dropin(dropinConfig);

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

// 5. Handle the result
payrails.on("success", (event) => console.log("Paid with", event.paymentMethodCode));
payrails.on("failed", (event) => console.log("Payment failed", event.data?.code));

Learn more

After the SDK is initialized, use the SDK features to customize the user experience:

custom field validation and errors
subscribe and react to events happening inside the form
customize the look with appearance rules
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:

Merchant 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. Moreover, if installments are enabled, the merchant client must also update the installment configuration along with the amount.

Example:

JavaScript

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").then((r) => r.json());

let executionId;

// 2. Initialize Payrails client
const payrails = await Payrails.init(config, {
  events: {
    onClientInitialized: (execution) => {
      executionId = execution?.id;
    },
  },
});

// 3. Initialize dropin
const dropinConfig = {}; // sample dropin config
const dropin = payrails.dropin(dropinConfig);

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

// 5. Update the SDK Client
payrails.update({
  value: "1",
  currency: "USD",
  installmentConfig: {
    defaultInstallment: 2,
    installmentCountry: 'US',
    installmentOptions: [],
  }
})

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.

Refresh Client Session

When the client session expires, the SDK fires the sessionExpired event. Return a fresh client init response from your handler, and the SDK starts a new session with it. Example:

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

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

// 2. Initialize Payrails client
const payrails = await Payrails.init(await getConfig());

// 3. Return a new client init response when the session expires
payrails.on("sessionExpired", async () => getConfig());

// 4. Initialize dropin
const dropinConfig = {}; // sample dropin config
const dropin = payrails.dropin(dropinConfig);

BIN lookup

Our SDK supports using our BIN lookup service to fetch card information. This feature is not enabled by default, so please reach out to your account manager to enable. Example:

JavaScript

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").then((r) => r.json());

// 2. Initialize Payrails client
const payrails = await Payrails.init(config);

// 3. Initialize dropin
const dropinConfig = {}; // sample dropin config
const dropin = payrails.dropin(dropinConfig);

// 4. Perform BIN lookup on the card number the shopper entered
const result = await payrails.binLookup();

In case complete BIN lookup is not enabled your environment, the API returns the first 8 digits of the PAN. If the BIN Lookup is enabled then the complete API response is returned.

// Sample BIN Lookup Response
{
  "bin": "411111",
  "network": "visa",
  "issuer": "JPMORGAN CHASE BANK, N.A.",
  "issuerCountry": {
    "code": "US",
    "name": "UNITED STATES",
    "iso3": "USA"
  },
  "type": "CREDIT"
}

Example on how to allow only credit cards

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").then((r) => r.json());

// 2. Initialize Payrails client
const payrails = await Payrails.init(config);

const dropin = payrails.dropin({});

// 3. Cancel the payment when the card isn't a credit card
payrails.on("buttonClicked", async (event) => {
  if (event.paymentMethodCode !== "card") return; // fires for every payment method

  const { type = "" } = (await payrails.binLookup()) ?? {};

  if (type !== "CREDIT") event.preventDefault();
});

Installment payments for cards in MX and BR

In certain countries or regions, it’s common for shoppers to pay for purchases in installments using credit cards. This allows them to receive their items right away while spreading the cost over multiple months. The installment payments are automatically charged to the shopper’s credit card every 30 days until the full balance is settled. Our SDK supports collecting installment plan information from the end-user and passing it through to downstream processors. Please contact us if you would like to enable this feature.

payrails.cardForm({
  installmentConfig: {
    defaultInstallment: 2,
  },
  translations: {
    labels: {
      paymentInstallments: "Payment Installments",
    },
  },
  appearance: {
    rules: {
      ".payrails-checkbox": { color: "red" },
      ".payrails-error": { display: "block" },
    },
    installments: {
      rules: {
        ".payrails-dropdown": {
          backgroundColor: "lightgray",
          color: "black",
          fontSize: "14px",
        },
      },
    },
  },
});

Accept Customer Address

With dropin it is possible to show address component to the end user. You can use it for collecting billing address which may be needed to tax purposes. Please contact us if you would like to enable this feature.

Example code for billing address config

const dropinConfig = {
  translations: {
    addressSelector: {
      labels: {
        countrySelector: "Select Country",
        postalCodeInput: "Zip Code",
      },
      placeholders: {
        postalCodeInput: "12345",
        countrySelector: "Country",
      },
    },
  },
  appearance: {
    cardForm: {
      address: {
        rules: {
          ".payrails-dropdown": { border: "1px solid #D3D3D3", borderRadius: "8px" },
          ".payrails-input": { padding: "8px" },
        },
      },
    },
  },
};

Performance optimizations

The web SDK loads its bundle when you call init(), and the secure card fields load when the card form mounts. To show the card form sooner, initialize the SDK and mount the card form early, hidden if necessary, before the shopper reaches the payment step.

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.
`pending`	`string`	URL to redirect to while the payment is pending.

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.

Report a Vulnerability

If you discover a potential security issue in this project, please get in touch with us at security@payrails.com.

Getting Started

Web SDK

iOS SDK

Android SDK

React Native SDK

Fraud SDK

Get started with the SDK

Include the SDK

Initialize the SDK

Example authorization flow

Example for web

Learn more

Payment amount update

Refresh Client Session

BIN lookup

Example on how to allow only credit cards

Installment payments for cards in MX and BR

Accept Customer Address

Example code for billing address config

Performance optimizations

Return Info

Content security policy

Report a Vulnerability

Get started with the SDK

Include the SDK

Initialize the SDK

Example authorization flow

Example for web

Learn more

Payment amount update

Refresh Client Session

BIN lookup

Example on how to allow only credit cards

Installment payments for cards in MX and BR

Config options for installments dropdown

Accept Customer Address

Example code for billing address config

Performance optimizations

Return Info

Content security policy

Report a Vulnerability