iFrame

Request address and request parameters for opening cashier in iFrame version 2.0

Opening the cashier in the iFrame version

Open and manage the cashier widget via the cashier iframe library. This method uses a global cashier object after loading the script in a web environment.

Include a file in html

To use the cashier widget, include the script tag inside your HTML:

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

Replace X.X.X with a specific version (e.g. 1.0.0) or use v=latest to always load the latest version.

If v=latest is used, browser caching must be disabled to ensure the most recent script is always loaded.

Cashier initialization

Initialize the cashier iFrame after the page has loaded by calling the following method:

For stage

Cashier.Init({
    url: "https://stage.papaya.ninja/v2/"
}, root)

For production

Cashier.Init({
    url: "{{project_cash_url}}/v2/"
}, root)

• url — Cashier environment URL.

• root — A reference to the DOM element (HTMLDivElement) where the cashier will be embedded.

The method resolves on the init event after all source files are loaded.

Cashier display

Once initialized, display the cashier content by calling:

Cashier.Display({
    key: "your_token",
    balance: 10.55,
    process_crypto: true,
    header: true,
    nav: true,
    mode: "deposit"
})

Request parameters

Parameter	Mandatory	Format	Description	Example
key		string	Cashier token	"abc123..."
balance		number	Available balance to show	10.55
process_crypto		boolean	Enables Metamask and crypto payment options	true
header		booleaan	Show/hide header (title with back button)	true
nav		boolean	Show/hide navigation buttons (Deposit/Withdraw)	true
mode		string	Initial mode to open with	'deposit' | 'withdraw' | 'saved_methods'

Balance update

To dynamically update the displayed balance:

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

Event handling

Subscribe to cashier iframe events using:

const unsub = Cashier.on("amount_change", (data) => {
    // handle event
})

Available events:

• init

• change_header_title

• deposit_page_open

• withdraw_page_open

• payin_form_open

• payout_form_open

• amount_change

• pay_with_crypto

To unsubscribe, call the function returned by .on(...).

Navigation

To navigate back within the iframe (equivalent to react-router’s back):

Cashier.RouterPushBack()

Cleanup

To unmount the Cashier iFrame and remove all listeners:

Cashier.Remove()

Example code

function App() {
    const rootRef = useRef(null);
    const [key, setKey] = useState("...");
    const [inited, setInited] = useState(false);
    const [display, setDisplay] = useState(true);
    const [balance, setBalance] = useState(100);
    
    // Load iframe on app init.
    useEffect(() => {
        // Make sure window.Cashier object is loaded.
        Cashier.Init({ url: "https://stage.papaya.ninja/cashier-v2/" }, rootRef.current)
            .then(() => setInited(true));

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

    // Redraw cashier display on dependency states update.
    useEffect(() => {
        if (!inited) return;
        setDisplay(false);
        Cashier.Display({ key, balance, nav: true })
            .then(() => setDisplay(true));
    }, [key, inited]);
    
    // Subscribe on Cashier events.
    useEffect(() => {
        if (!inited) return;
        const amountChangeUnsub = Cashier.on("amount_change", () => {});
        const depositPageOpenUnsub = Cashier.on("deposit_page_open", () => {});
        return () => {
            amountChangeUnsub();
            depositPageOpenUnsub();
        };
    }, [inited]);

    // Fire Cashier events.
    useEffect(() => {
        if (!inited) return;
        Cashier.UpdateBalance({ amount: balance, currency: "USD" });
    }, [display, balance]);

    return <div style={{ width: "100%", height: "100%" }} ref={rootRef}></div>;
}

Changelog ## 1.0.0