JS SDK

Push JS SDK Reference

The SDK must be loaded as a script tag on your website — it cannot be statically bundled via package management.

<script src="https://cdn.pushcash.com/sdk/push.umd.js"></script>

The SDK is loaded from cdn.pushcash.com and creates iframes that load content from the same origin. If your site uses a Content Security Policy, ensure the following directives include https://cdn.pushcash.com:

• script-src — to load the SDK script
• frame-src — to allow the widget iframes

Widget

new window.PushCash.Widget(options)

Creates the Push User Widget. When a selector is provided, the widget renders a card input form into the specified container. When selector is omitted, the widget does not render any UI and relies on the developer to collect the user’s card details in their own UI and pass them directly to tokenize().

Options (WidgetOptions)

Field	Type	Required	Description
url	string	✅	URL returned from create-user-url.
selector	string	❌	CSS selector for the container element to render into. Omit to create the widget in no-display mode.
onValid	() => void	❌	Called once the widget has received valid card details. Use to enable the submit button. Only applicable when selector is provided.
background	string	❌	Widget background (CSS color value). Only applicable when selector is provided.
fontSize	string	❌	Base font size (CSS value, e.g. 14px). Only applicable when selector is provided.
borderRadius	string	❌	Corner radius (CSS value, e.g. 12px). Only applicable when selector is provided.
padding	string	❌	Inner padding (CSS value, e.g. 16px). Only applicable when selector is provided.
color	string	❌	Text color (CSS color value). Only applicable when selector is provided.

Returns

A Widget instance.

Example - Widget Rendered to UI

const widget = new window.PushCash.Widget({
  url: 'https://cdn.pushcash.com/widget/?param=1&param=2',
  selector: '#payment-container',
  onValid: () => { console.log('user has provided valid card details') },
  background: '#ffffff',
  fontSize: '16px',
  borderRadius: '8px',
  padding: '12px',
  color: '#000000',
});

Example - Widget Hidden from UI

const widget = new window.PushCash.Widget({
  url: 'https://cdn.pushcash.com/widget/?param=1&param=2',
});

widget.tokenize(cardData?)

Generates a token from the user’s card details which can be used to process a transaction by calling authorize-payment or exchanged for a durable credential by calling create-credential.

• Display mode (widget created with selector): Call with no arguments. Throws an error if the user has not provided valid card details.
• No-display mode (widget created without selector): Call with a cardData object containing the card details collected in your own UI.

Card Data (CardData)

Field	Type	Required	Description
pan	string	✅	The card number.
cvv	string	✅	The card verification value.
expMonth	string	✅	The card expiration month (e.g. '12').
expYear	string	✅	The card expiration year (e.g. '28').

Signature

tokenize: (cardData?: CardData) => Promise<{ token: string }>

Example (display mode)

try {
  const { token } = await widget.tokenize();
} catch (error) {
  console.error(‘User has not provided valid card details:’, error);
}

Example (no-display mode)

const { token } = await widget.tokenize({
  pan: ‘5555555555554444’,
  cvv: ‘123’,
  expMonth: '12',
  expYear: '28',
});

widget.destroy()

Unmounts the widget and cleans up resources.

Signature

destroy: () => void

---

Apple Pay Launcher

new window.PushCash.ApplePay(config)

Creates an Apple Pay launcher instance.

Parameters

Field	Type	Required	Description
url	string	✅	URL returned from create-user-url with type: "apple_pay". Must be newly created per page load.

Example

const launcher = new window.PushCash.ApplePay({
  url: '<your-url>',
});

launcher.display(args)

Launches the Apple Pay payment sheet and runs the Apple Pay flow.

Parameters

Field	Type	Required	Description
amount	number	✅	Payment amount in cents (must be > 0).
direction	'cash_in'	✅	Only cash_in is supported.
currency	'USD'	✅	Only "USD" is supported.
onAuthorize	(token: string) => Promise<'approved' | 'declined'>	✅	Called after the user authorizes payment in the Apple Pay sheet. Receives a token which must be passed to authorize payment. Must return 'approved' or 'declined' based on the authorization result. The amount and currency must match the values provided to display().
onComplete	() => void | Promise<void>	❌	Called when the Apple Pay session completes.

Example

launcher.display({
  amount: 1000,
  direction: 'cash_in',
  currency: 'USD',
  onAuthorize: async (token) => {
    // call backend to authorize payment via Push API
    // pass token to POST /authorize
    const result = await yourBackend.authorize(token);
    return result.status; // 'approved' or 'declined'
  },
  onComplete: () => {
    // handle session completion
  },
});