Simple SDK

Simple SDK is a lightweight JavaScript library designed to simplify payment integration for web applications. It provides a seamless way to handle payment configurations and interactions through a simple API.

Quick Start Example

Get started with Simple SDK in just 3 steps:

<!-- 1. Include the Simple script -->
<script src="https://cdn.jsdelivr.net/npm/@paysimple/simple-dev@1.0"></script>
 
<!-- 2. Add an email input -->
<input type="email" placeholder="Enter email" />
 
<!-- 3. Configure Simple -->
<script>
  window.applySimpleConfig({
    platformId: "your_platform_id",
    organizationTaxId: "your_organization_tax_id",
    amount: 10.99,
    onSuccess: (response) => console.log("Payment successful!", response),
  });
</script>

That’s it! Simple will automatically detect the email input and handle the payment flow.

Features

• 🚀 Zero Setup: Just include the script and you’re ready
• ✨ Simple Configuration: Quick setup with minimal configuration
• 🔒 Built-in Validation: Automatic validation of payment parameters
• 🎨 Visual Integration: Automatic payment icon injection for better UX
• 📅 Subscription Support: Handle one-time and recurring payments
• 🌐 Cross-browser Compatible: Works in all modern browsers
• ✉️ Smart Email Detection: Automatically detects and validates registered emails

Setup Guide

Option 1: CDN (Recommended)

Add Simple directly to your HTML using our CDN:

<script src="https://cdn.jsdelivr.net/npm/@paysimple/simple-dev@1.0"></script>

Option 2: NPM

If you’re using a build system, you can install via npm:

npm install @paysimple/simple-dev

pnpm add @paysimple/simple-dev

yarn add @paysimple/simple-dev

bun add @paysimple/simple-dev

Then import it in your application:

import "@paysimple/simple-dev";

Using Types

For the CDN, the TypeScript types can be installed via:

npm install @paysimple/simple-dev-types

pnpm add @paysimple/simple-dev-types

yarn add @paysimple/simple-dev-types

bun add @paysimple/simple-dev-types

If you are using the npm package, the TypeScript types are included automatically.

Usage

1. Email Input Setup

By default, Simple automatically detects and enhances type="email" input fields on your page. However, if you experience any of these scenarios:

• Simple detects unintended email fields
• You have multiple email fields but only want Simple on specific ones
• You want more control over which inputs trigger the Simple payment flow

You can disable the automatic detection and explicitly specify which inputs to enhance using the simple-email class:

<!-- Automatic detection (Default behavior) -->
<input type="email" placeholder="Enter email" />
 
<!-- Manual control: Use simple-email class -->
<input class="simple-email" placeholder="Enter email" />

Using the simple-email class will:

1. Disable automatic detection of email inputs on your page
2. Only enhance inputs that explicitly have the simple-email class
3. Give you full control over which inputs trigger the Simple payment flow

Choose this approach if you need more precise control over Simple’s behavior on your page.

2. Configure Simple

window.applySimpleConfig({
  platformId: "your_platform_id",
  organizationTaxId: "your_organization_tax_id",
  amount: 100, // Amount in dollars (e.g., 10.99)
  schedule: { ... }, // Optional subscription config
  onSuccess: (response) => {
    console.log("Payment successful!", response);
  },
});

Dynamic Updates

You can update any configuration field dynamically by calling applySimpleConfig with the new values:

// Example: Update amount based on user selection
const amountInput = document.querySelector("#amount");
amountInput.addEventListener("input", (e) =>
  window.applySimpleConfig({ amount: e.target.value }),
);

Calling applySimpleConfig() without arguments will clear all configurations and remove all Simple icons from the page.

Configuration Options

Subscription Configuration

For recurring payments, add a schedule object.

window.applySimpleConfig({
  // ... basic config
  schedule: {
    intervalType: "month", // "day" | "week" | "month" | "year"
    intervalCount: 1,
    startDate?: "2024-01-01", // Optional: When to start the subscription
    // Optional: Set total number of payments
    totalPayments?: 12,
    // --OR--
    // Optional: Set an end date
    endDate?: "2024-12-31",
  },
});

Schedule Options

Validation & Simple Icon

The Simple icon appears on your page when:

• All required configuration fields are valid
• The organization is registered with Simple

The icon will automatically:

• Hide if any validation errors occur
• Reappear once all errors are resolved

Response Schema

The onSuccess callback receives a JWT (JSON Web Token) that contains an encoded payload with the following structure when decoded:

interface PaymentResponse {
  id: string; // Transaction ID
  amount: number; // Amount in cents
  platformId: string; // Platform identifier
  organizationTaxId: string; // Organization tax ID
  name: string; // Customer name | `Simple Checkout` if not provided
  phoneNumber: string; // Customer phone number
  email: string; // Customenr email
  gatewayTransactionId: string; // Payment gateway transaction ID
  createdAt: string; // Transaction timestamp
 
  // Optional subscription details
  schedule?: {
    IntervalType: "day" | "week" | "month" | "year";
    TotalPayments?: number;
    IntervalCount: number;
    StartDate?: string;
    EndDate?: string;
  };
 
  // Customer address information
  address?: {
    name: string;
    street: string;
    streetLine2?: string;
    city: string;
    state: string;
    country: string;
    postalCode: string;
  };
 
  gatewayResponse: Record<string, any>; // Raw gateway response
 
  iat: number; // (jwt issued at)
  exp: number; // (jwt expiration)
}

Verifying the JWT

To ensure the authenticity of the payment response, you should verify the JWT using Simple’s public key:

1. Download the public key from docs.paysimple.io/jwt.key.pub
2. Use a JWT library to verify the token. Here’s an example using Node.js:

import fs from "fs";
import jwt from "jsonwebtoken";
 
const publicKey = fs.readFileSync("jwt.key.pub");
 
function verifyPaymentResponse(token) {
  try {
    return jwt.verify(token, publicKey, { algorithms: ["RS256"] });
  } catch (error) {
    console.error("Invalid token:", error);
    return null;
  }
}

Debugging

To view debug logs:

1. Open your browser’s developer tools (F12)
2. Go to Console settings
3. Enable “Verbose” log level
4. Look for logs prefixed with “Simple”

Live Example

See example here.

Support

For support, please contact luzy@paysimple.io.