Truegate SDK Integration Guide

The Truegate SDK provides a lightweight, developer-friendly way to integrate Apple Pay and Card Payment forms into your website.
It handles all complex payment logic under the hood while giving you full control over layout, design, and event handling.

Table of Contents

1. Overview
2. Quick Start
3. Initialize the SDK
4. Listening to SDK Events
5. Apple Pay Integration
6. Card Payment Integration
7. Event Reference
8. SDK Configuration Options
9. API Reference

Overview

The Truegate SDK allows you to easily embed payment forms such as Card Payment and Apple Pay while keeping complete control over your page layout and design.
You simply load the SDK as a project dependency, or as a script into window, wait for it to be ready, create an SDK instance, and initialize payment methods on demand.

The SDK handles:

• Secure injection of payment elements
• Validation of input fields
• Unified event system for all payment integrations

Quick Start

1. Add the SDK script

Use official package from npm, and install it by running one of the following scripts.

# bun
bun add @truegate/sdk-core

# or yarn
yarn add @truegate/sdk-core

# or npm
npm i @truegate/sdk-core

If you don't use that SDK via npm, you can embed it via loading it into your DOM.

Include the SDK script directly in your HTML:

<script src="https://sdk.test.truegate.tech/sdk.js"></script>

Once the script is loaded, the SDK will be available globally as window.truegateSdk.

2. Wait until the SDK is ready*

* - that step is needed only if you loaded SDK via <script> tag. No event will be fired for npm package.

After the script is attached, listen for the SDK_READY event before using the SDK:

window.addEventListener('message', (event) => {
  if (event.data.scope === 'TRUEGATE_SDK'
    && event.data.type === 'SDK_READY') {
    console.log('Truegate SDK is ready!');
  }
});

Note: The SDK_READY event is fired only once.

3. Create an SDK instance

For npm packages use:

import { TruegateSdk } from '@truegate/sdk-core'

const sdk = new TruegateSdk({
  id: 'YOUR_INSTANCE_ID', // injected into all emitted events
  transactionId: '3fb558b0-0838-49fa-8fc0-50cb6937eef5', // obtained from your backend
  env: 'TEST', // optional: DEV | TEST | PROD (default: PROD)
});

For window loaded script use:

const sdk = new window.truegateSdk({
  id: 'YOUR_INSTANCE_ID', // injected into all emitted events
  transactionId: '3fb558b0-0838-49fa-8fc0-50cb6937eef5', // obtained from your backend
  env: 'TEST', // optional: DEV | TEST | PROD (default: PROD)
});

💡 The transactionId is obtained from /start API endpoint. The env parameter lets you switch environments without changing the script URL.
Some of SDK integrations work only in PROD mode.

4. Initialize the SDK

Before using any payment methods, call:

await sdk.init();

This initializes all supported payment integrations and emits the events below:

| Event | Description | |-------------------------|--------------------------------------| | INIT_PAYMENTS_LOADING | Initialization started | | INIT_PAYMENTS_SUCCESS | All methods initialized successfully | | INIT_PAYMENTS_ERROR | Initialization failed |

Listening to SDK Events

The SDK exposes a unified .on() method to subscribe to all events.

const off = sdk.on('INIT_PAYMENTS_SUCCESS', (payload) => {
  console.log('Payments initialized!', payload);
});

// Later you can unsubscribe:
off();

• Each call to .on() adds a new listener (multiple handlers per event are supported).
• The return value is an unsubscribe function (off()).
• Every event payload has the same base shape:

{
  id: string;            // the ID used when creating the instance
  scope: 'TRUEGATE_SDK'; // always constant
  channel: 'SDK' | 'APPLE_PAY' | 'CARD_PAYMENT'; // source of the event
  type: string;          // event type
  // ...additional fields depending on the event type
}

Apple Pay Integration

Before initializing Apple Pay, subscribe to its events to handle various states.

1. Subscribe to Apple Pay events

| Event | Channel | Description | |--------------------------|-----------|--------------------------------------------------------------------------------| | APPLE_PAY_DISABLED | SDK | Apple Pay is disabled for your account | | INIT_APPLE_PAY_LOADING | SDK | Apple Pay button is being injected | | INIT_APPLE_PAY_SUCCESS | SDK | Button injection succeeded | | INIT_APPLE_PAY_ERROR | SDK | Injection failed | | APPLE_PAY_READY | APPLE_PAY | Button ready and interactive | | APPLE_PAY_BUTTON_CLICK | APPLE_PAY | User clicked the button | | PAYMENT_ERROR | APPLE_PAY | Payment failed or status unknown | | PAYMENT_STATUS | APPLE_PAY | Current payment status, has additional details property in the event payload |

Example:

sdk.on('APPLE_PAY_READY', () => {
  console.log('Apple Pay is ready!');
});

2. Inject the Apple Pay button

Prepare a container element in your page:

<div id="apple-pay-button"></div>

Then initialize the button:

await sdk.initApplePay({
  id: 'apple-pay-button',
  buttonOptions: {
    HEIGHT: '48px', // optional (default: 64px)
  },
});

The SDK automatically injects and configures the Apple Pay button within the provided container.

Card Payment Integration

1. Subscribe to Card Payment events

SDK-level events (channel =SDK)

| Event | Description | |-----------------------------|-------------------------------------| | CARD_PAYMENT_DISABLED | Card Payment disabled in account | | INIT_CARD_PAYMENT_LOADING | Card Payment form is being injected | | INIT_CARD_PAYMENT_SUCCESS | Form injected successfully | | INIT_CARD_PAYMENT_ERROR | Injection failed |

Form-level events (channel =CARD_PAYMENT)

| Event | Description | |----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | CARD_PAYMENT_READY | Form is ready to use | | CARD_PAYMENT_SUBMIT | Submit triggered | | CARD_NUMBER_INPUT / CARD_EXPIRATION_INPUT / CARD_SECURITY_CODE_INPUT | Input event fired | | CARD_NUMBER_BLUR / CARD_EXPIRATION_BLUR / CARD_SECURITY_CODE_BLUR | Input lost focus | | CARD_NUMBER_VALIDATION_ERRORS / CARD_EXPIRATION_VALIDATION_ERRORS / CARD_SECURITY_CODE_VALIDATION_ERRORS | Field validation errors, check additional details property in the event payload | | CARD_NUMBER_VALIDATION_RESULT / CARD_EXPIRATION_VALIDATION_RESULT / CARD_SECURITY_CODE_VALIDATION_RESULT | Overall field validity, check details for the validation result | | CARD_NUMBER_COMPLETE / CARD_EXPIRATION_COMPLETE / CARD_SECURITY_CODE_COMPLETE | Field fully filled (not necessarily valid) | | CARD_NUMBER_PROVIDER | Detected card provider, check details |

Validation events fire both immediately after form initialization and during user input.

2. Initialize Card Payment

Prepare placeholders for each input field:

<div id="card-number"></div>
<div id="card-expiration"></div>
<div id="card-cvv"></div>

Then initialize:

const { submit } = await sdk.initCardPayment({
  cardNumberId: 'card-number',
  expirationId: 'card-expiration',
  securityCodeId: 'card-cvv',
  options: { // optional object, the full list of options is described below 
    FONT_NAME: 'ROBOTO', // all the properties are optional and have default values
    FONT_SIZE: '14px',
    COLOR: '#333',
    PLACEHOLDER_CARD_NUMBER: 'Card Number',
    PLACEHOLDER_EXPIRATION: 'MM / YY',
    PLACEHOLDER_SECURITY_CODE: 'CVC',
  },
});

The SDK automatically injects the corresponding iframes/inputs into these elements.

3. Submit Card Payment

Once all inputs are valid and complete, call:

await submit({ cardHolderName: 'John Doe' });

⚠️ Make sure there are no validation errors before submission. Use *_VALIDATION_ERRORS or *_VALIDATION_RESULT events to check field states.

4. Card Payment status events

After submission, Card Payment shares the same generic payment events as Apple Pay:

| Event | Channel | Description | |------------------|--------------|--------------------------------------------------------------------------------| | PAYMENT_ERROR | CARD_PAYMENT | Payment failed or status unknown | | PAYMENT_STATUS | CARD_PAYMENT | Current payment status, has additional details property in the event payload |

PayPal integration

Before initializing PayPal, subscribe to its events to handle various states.

1. Subscribe to PayPal events

| Event | Channel | Description | |------------------------|---------|--------------------------------------------------------------------------------| | PAY_PAL_DISABLED | SDK | PayPal is disabled for your account | | INIT_PAY_PAL_LOADING | SDK | PayPal button is being injected | | INIT_PAY_PAL_SUCCESS | SDK | Button injection succeeded | | INIT_PAY_PAL_ERROR | SDK | Injection failed | | PAY_PAL_READY | PAY_PAL | Button ready and interactive | | PAY_PAL_BUTTON_CLICK | PAY_PAL | User clicked the button | | PAYMENT_ERROR | PAY_PAL | Payment failed or status unknown | | PAYMENT_STATUS | PAY_PAL | Current payment status, has additional details property in the event payload |

2. Inject the PayPal button

Prepare a container element in your page:

<div id="pay-pal-button"></div>

Then initialize the button:

await sdk.initPayPal({
  id: 'pay-pal-button',
  buttonOptions: {
    HEIGHT: 48, // only numeric value, in the range [25...55], optional (default: 54)
  },
});

The SDK automatically injects and configures the PayPal button within the provided container.

Event Reference

Each emitted event includes:

• id – instance identifier
• scope – always 'TRUEGATE_SDK'
• channel – event source ('SDK', 'APPLE_PAY', 'CARD_PAYMENT', 'PAY_PAL')
• type – event name
• details – optional contextual data (e.g. validation errors, card provider info)

| Channel | Example Events | Description | |----------------|---------------------------------------------------|--------------------------| | SDK | INIT_PAYMENTS_SUCCESS, INIT_APPLE_PAY_SUCCESS | High-level SDK lifecycle | | APPLE_PAY | APPLE_PAY_READY, PAYMENT_STATUS | Apple Pay lifecycle | | CARD_PAYMENT | CARD_NUMBER_INPUT, PAYMENT_STATUS | Card Payment lifecycle | | PAY_PAL | PAY_PAL_BUTTON_CLICK, PAYMENT_STATUS | PayPal lifecycle |

SDK Configuration Options

SdkPayload

| Field | Type | Required | Description | |-----------------|-----------------------------|----------|--------------------------------------------------------------------------------------------------| | id | string | ✅ | Used to identify events belonging to a specific SDK instance | | transactionId | string | ✅ | Unique transaction/session ID | | env | 'DEV' \| 'TEST' \| 'PROD' | ❌ | SDK environment (default: 'PROD'). Warning: not all integrations support non-prod environment. |

CardPaymentOptions

| Option | Type | Default | Description | |------------------------------|-----------|-------------------------|--------------------------------------| | FONT_NAME | see below | 'ROBOTO' | Input font | | FONT_SIZE | string | '14px' | Input text size | | LINE_HEIGHT | string | '20px' | Line height | | FONT_WEIGHT | string | '400' | Font weight | | COLOR | string | '#000000' | Input text color | | LANG | string | 'en' | Used for lang attribute on input | | PLACEHOLDER_CARD_NUMBER | string | '0000 0000 0000 0000' | Placeholder text for card number | | PLACEHOLDER_EXPIRATION | string | 'MM/YY' | Custom placeholder text | | PLACEHOLDER_SECURITY_CODE | string | 'CVV/CVC' | Custom placeholder text |

Supported values for FONT_NAME.

export enum FontName {
  ROBOTO = 'ROBOTO',
  OPEN_SANS = 'OPEN SANS',
  LATO = 'LATO',
  MONTSERRAT = 'MONTSERRAT',
  OSWALD = 'OSWALD',
  SOURCE_SANS_PRO = 'SOURCE_SANS_PRO',
  SLABO_27PX = 'SLABO_27PX',
  RALEWAY = 'RALEWAY',
  PT_SANS = 'PT SANS',
  MERRIWEATHER = 'MERRIWEATHER',
  ROBOTO_CONDENSED = 'ROBOTO_CONDENSED',
  NOTO_SANS = 'NOTO_SANS',
  POPPINS = 'POPPINS',
  UBUNTU = 'UBUNTU',
  PLAYFAIR_DISPLAY = 'PLAYFAIR_DISPLAY',
  RUBIK = 'RUBIK',
  WORK_SANS = 'WORK_SANS',
  NUNITO = 'NUNITO',
  EXO_2 = 'EXO 2',
  CABIN = 'CABIN',
  INTER = 'INTER',
}

ApplePayPayload

| Field | Type | Required | Description | |------------------------|----------|----------|---------------------------------------------------------------| | id | string | ✅ | ID of the element where the Apple Pay button will be rendered | | buttonOptions.HEIGHT | string | ❌ | Height of the Apple Pay button (default: '64px') |

PayPalPayload

| Field | Type | Required | Description | |------------------------|----------|----------|------------------------------------------------------------------------| | id | string | ✅ | ID of the element where the PayPal button will be rendered | | buttonOptions.HEIGHT | number | ❌ | Height of the PayPal button (default: 54), a value from 25 to 55 |

API Reference

window.truegateSdk

Global constructor available after script load - applicable only for window script usage.

const sdk = new window.truegateSdk(payload: SdkPayload): SdkInstance

SdkInstance methods

| Method | Description | |----------------------------|------------------------------------------------------------| | init() | Initializes available payment methods | | on(eventType, handler) | Subscribes to an event and returns an unsubscribe function | | initApplePay(payload) | Injects the Apple Pay button | | initCardPayment(payload) | Injects card payment fields and returns { submit } | | initPayPal(payload) | Injects the PayPal button | | VERSION | Static property indicating SDK version |

Tips & Best Practices

• Always wait for SDK_READY before creating your instance (applicable only for window script usage).
• Call init() once per instance before using payment methods.
• Subscribe to events before initializing integrations to avoid missing early events.
• Use the id field in payloads to differentiate multiple SDK instances.
• Validate all form fields before calling submit().

© Truegate