Cashier SDK

Overview

The Cashier SDK is a JavaScript library that enables you to embed a payment/cashier interface into your web application.

Installation

Include the Cashier SDK script in your HTML file:

<script src="https://stage.papaya.ninja/v2/js/cashier.js?v=X.X.X"></script>

Replace X.X.X with the desired version number.

The SDK will be available globally as window.Cashier .

Rendering Modes

The Cashier SDK supports two rendering modes that you can specify during initialization:

Direct Mode (Default)

In direct mode, the cashier interface is rendered directly into your DOM. The cashier's HTML, CSS, and JavaScript are injected and executed in your page's context. This means:

DOM Manipulation: The cashier has full access to your page's DOM and can directly manipulate elements. CSS styles are loaded into your document head, and components are rendered as native DOM elements within your container.

Security: Since code executes in the same context as your application, there's no isolation boundary. The cashier shares the same JavaScript execution environment and has access to your page's window object and variables.

iFrame Mode

In iframe mode, the cashier interface is loaded inside an iframe element. The cashier runs in a completely separate browsing context. This means:

DOM Manipulation: The cashier's DOM is completely isolated within the iframe. It cannot directly access or modify your page's DOM. Communication happens through the postMessage API. The iframe automatically resizes based on content.

Security: The iframe provides a strong security boundary. The cashier code cannot access your page's JavaScript variables, cookies (if cross-origin), or localStorage. This is ideal when loading the cashier from a different domain or when you need strict isolation.

Step-by-Step Integration

Prepare Your HTML

Create a container element where the cashier will be rendered:

<!DOCTYPE html>
<html>
<head>
    <title>My App with Cashier</title>
    <script src="https://stage.papaya.ninja/v2/js/cashier.js?v=1.0.0"></script>
</head>
<body>
    <div id="cashier-root" style="width: 100%; height: 100vh;"></div>
</body>
</html>

Initialize the Cashier

Initialize the Cashier SDK with your configuration:

Configuration Options:

const rootElement = document.getElementById('cashier-root');

Cashier.Init({
    url: "https://your-cashier-domain.com/",
    renderMode: "direct" // Choose "direct" or "iframe"
}, rootElement)
    .then(() => {
        console.log('Cashier initialized successfully');
    })
    .catch((error) => {
        console.error('Failed to initialize Cashier:', error);
    });

Option

Type

Required

Description

url

string

Base URL of the cashier application

renderMode

string

Rendering mode: "direct" (default) or "iframe"

Display the Cashier

Once initialized, display the cashier with specific parameters:

Cashier.Display({
    key: "user-session-key",
    balance: 100,
    nav: true,
    header: true,
    lang: "en"
})
    .then(() => {
        console.log('Cashier displayed successfully');
    })
    .catch((error) => {
        console.error('Failed to display Cashier:', error);
    });

Listen to cashier events to react to user actions:

// Subscribe to amount change event
const unsubscribe = Cashier.on("amount_change", (data) => {
    console.log('Amount changed:', data);
});

// Unsubscribe when no longer needed
unsubscribe();

Send Events

Trigger actions in the cashier by sending events:

// Update the user's balance
Cashier.UpdateBalance({
    amount: 250,
    currency: "USD"
});

// Navigate to deposit page
Cashier.OpenDepositPage();

// Navigate back
Cashier.RouterPushBack();

For a complete list of available methods, see the API Reference section.

Cleanup

When you're done with the cashier (e.g., when navigating away), clean up:

Cashier.Remove();

API Reference

Methods

`Cashier.Init(config, rootElement)`

Initializes the Cashier SDK and prepares it for display.

Parameters:

Parameter

Type

Required

Description

config

Object

Configuration object

config.url

string

Base URL of the cashier application

config.renderMode

string

Rendering mode: "direct" or "iframe". Default: "direct"

rootElement

HTMLElement

DOM element where the cashier will be mounted

Returns: Promise<void> - Resolves when initialization is complete

Example:

Cashier.Init({
    url: "https://your-cashier-domain.com/",
    renderMode: "direct"
}, document.getElementById('root'));

`Cashier.Display(params)`

Displays the cashier interface with specified parameters.

Parameters:

Returns: Promise<void> — Resolves when display is complete

Example:

Cashier.Display({
    key: "abc123",
    balance: 100,
    nav: true,
    header: true,
    lang: "en",
    mode: "deposit",
    force_open_method: {
        type: "deposit",
        pg: 5
    }
});

`Cashier.UpdateBalance(balance)`

Updates the displayed balance in the cashier.

Parameters:

Parameter

Type

Required

Description

balance

Object

Balance information

balance.amount

number

Balance amount

balance.currency

string

Currency code (e.g., "USD")

Returns: void

Example:

Cashier.UpdateBalance({
    amount: 250,
    currency: "USD"
});

`Cashier.RouterPushBack()`

Navigates back in the cashier's internal router.

Parameters: None

Returns: void

Example:

Cashier.RouterPushBack();

`Cashier.OpenDepositPage()`

Opens the deposit page in the cashier.

Parameters: None

Returns: void

Example:

Cashier.OpenDepositPage();

`Cashier.OpenWithdrawPage()`

Opens the withdraw page in the cashier.

Parameters: None

Returns: void

Example:

Cashier.OpenWithdrawPage();

`Cashier.OpenBuyCryptoPage()`

Opens the buy crypto page in the cashier.

Parameters: None

Returns: void

Example:

javascript

Cashier.OpenBuyCryptoPage();

`Cashier.Remove()`

Removes the cashier from the DOM and cleans up all event listeners.

Parameters: None

Returns: void

Example:

Cashier.Remove();

`Cashier.on(event, callback)`

Subscribes to a cashier event.

Parameters:

Parameter

Type

Required

Description

event

string

Event name (see Events)

callback

Function

Callback function to handle the event

Returns: Function - Unsubscribe function

Example:

const unsubscribe = Cashier.on("amount_change", (data) => {
    console.log('Amount changed:', data);
});

// Later, to unsubscribe:
unsubscribe();

Events

The Cashier SDK emits various events that you can subscribe to:

Event Name

Description

Data Payload

init

Fired when cashier initialization is complete

{ timestamp: string, version: string, displayTimestamp: string, mode: string }

resize_iframe

Fired when iframe needs to be resized (iframe mode only)

{ height: number }

change_header_title

Fired when header title changes

`{ title: string, canGoBack: boolean, methodPG: number \

deposit_page_open

Fired when deposit page is opened

{} (empty object)

withdraw_page_open

Fired when withdraw page is opened

{} (empty object)

buy_crypto_page_open

Fired when buy crypto page is opened

{} (empty object)

payin_form_open

Fired when pay-in form is opened

{} (empty object)

payout_form_open

Fired when payout form is opened

{} (empty object)

amount_change

Fired when amount value changes

{ amount: number, currency: string }

pay_with_crypto

Fired when user chooses to pay with crypto

{ amount: number, smart_contract_currency: string, smart_contract: string, address: string, coinAmount: number }

Examples

React Integration

import { useEffect, useRef, useState } from 'react';

function CashierComponent() {
    const rootRef = useRef(null);
    const [key, setKey] = useState("your-session-key");
    const [inited, setInited] = useState(false);
    const [display, setDisplay] = useState(true);
    const [balance, setBalance] = useState(100);
    
    // Initialize cashier on component mount
    useEffect(() => {
        Cashier.Init({ 
            url: "https://stage.papaya.ninja/",
            renderMode: "direct" // or "iframe"
        }, rootRef.current)
            .then(() => setInited(true))
            .catch(console.error);

        return () => Cashier.Remove();
    }, []);

    // Display cashier when dependencies change
    useEffect(() => {
        if (!inited) return;
        
        setDisplay(false);
        Cashier.Display({ 
            key, 
            balance, 
            nav: true,
            header: true
        })
            .then(() => setDisplay(true))
            .catch(console.error);
    }, [key, inited]);
    
    // Subscribe to events
    useEffect(() => {
        if (!inited) return;
        
        const unsubAmount = Cashier.on("amount_change", (data) => {
            console.log('Amount changed:', data);
        });
        
        const unsubDeposit = Cashier.on("deposit_page_open", (data) => {
            console.log('Deposit page opened:', data);
        });
        
        return () => {
            unsubAmount();
            unsubDeposit();
        };
    }, [inited]);

    // Update balance when it changes
    useEffect(() => {
        if (!inited || !display) return;
        
        Cashier.UpdateBalance({ 
            amount: balance, 
            currency: "USD" 
        });
    }, [display, balance, inited]);

    return (
        <div style={{ width: "100%", height: "100vh" }}>
            <button onClick={() => setBalance(balance + 50)}>
                Add $50
            </button>
            <div ref={rootRef} style={{ width: "100%", height: "100%" }} />
        </div>
    );
}

export default CashierComponent;

Vanilla JavaScript Example (Direct Mode)

// Wait for DOM to be ready
document.addEventListener('DOMContentLoaded', () => {
    const container = document.getElementById('cashier-root');
    
    // Initialize in direct mode
    Cashier.Init({
        url: "https://stage.papaya.ninja/",
        renderMode: "direct"
    }, container)
        .then(() => {
            console.log('Cashier initialized');
            
            // Display the cashier
            return Cashier.Display({
                key: "user-session-key",
                balance: 100,
                nav: true,
                header: true,
                lang: "en"
            });
        })
        .then(() => {
            console.log('Cashier displayed');
            
            // Subscribe to events
            Cashier.on("deposit_page_open", () => {
                console.log('User opened deposit page');
            });
            
            Cashier.on("amount_change", (data) => {
                console.log('Amount changed:', data);
            });
        })
        .catch((error) => {
            console.error('Error:', error);
        });
});

Version Information

Current SDK Version: 1.0.0

The SDK automatically detects its version from the script URL query parameter or defaults to the latest version.

PreviousCashier opening 2.0 NextPayment processing

Last updated 7 days ago

Overview

Installation

Rendering Modes

Direct Mode (Default)

iFrame Mode

Step-by-Step Integration

Prepare Your HTML

Initialize the Cashier

Display the Cashier

Subscribe to Events

Send Events

Cleanup

API Reference

Methods

Cashier.Init(config, rootElement)

Cashier.Display(params)

Cashier.UpdateBalance(balance)

Cashier.RouterPushBack()

Cashier.OpenDepositPage()

Cashier.OpenWithdrawPage()

Cashier.OpenBuyCryptoPage()

Cashier.Remove()

Cashier.on(event, callback)

Events

Examples

React Integration

Vanilla JavaScript Example (Direct Mode)

Version Information

`Cashier.Init(config, rootElement)`

`Cashier.Display(params)`

`Cashier.UpdateBalance(balance)`

`Cashier.RouterPushBack()`

`Cashier.OpenDepositPage()`

`Cashier.OpenWithdrawPage()`

`Cashier.OpenBuyCryptoPage()`

`Cashier.Remove()`

`Cashier.on(event, callback)`