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 and UX iframes

Creates the Push User Widget. The widget renders a card input form into the container specified by selector.

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.
`onValid`	`() => void`	❌	Called once the widget has received valid card details. Use to enable the submit button.
`background`	`string`	❌	Widget background (CSS color value).
`fontSize`	`string`	❌	Base font size (CSS value, e.g. `14px`).
`borderRadius`	`string`	❌	Corner radius (CSS value, e.g. `12px`).
`padding`	`string`	❌	Inner padding (CSS value, e.g. `16px`).
`color`	`string`	❌	Text color (CSS color value).

Returns

A Widget instance.

Example

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',
});

Generates a token from the user’s card details which can be used to process a transaction by calling authorize-payment. Throws an error if the user has not provided valid card details.

Signature

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

Example

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

Unmounts the widget and cleans up resources.

Signature

destroy: () => void

UX

Presents the Push-hosted authentication UI for an intent in a modal. Use it on the web to complete the step-up authentication requested when authorize-payment returns 202 Accepted — see Presenting the authentication UI.

`window.PushCash.UX(config)`

Creates a UX handler for a single intent. It renders the hosted UX in a modal — a centered dialog on desktop, a full-page sheet on mobile — and manages its lifecycle.

Config (`PushUXConfig`)

Field	Type	Required	Description
`intentId`	`string`	✅	The intent `id` returned by authorize-payment with a `202 Accepted` response.
`onExit`	`() => void`	✅	Called exactly once when the flow ends — whether the user completes it or dismisses the modal. It carries no result; retrieve the authoritative outcome from the server (see below).

Because you omit redirect_url when presenting on the web, the flow’s end is signaled through onExit rather than a redirect. onExit does not indicate whether the payment succeeded — call get-an-intent (or wait for the intent webhook) and inspect status.

Returns

A PushUXHandler.

Example

const ux = window.PushCash.UX({
  // the intent id returned from the authorize-payment 202 response
  intentId: 'intent_sandbox_dMggQ93ZYH6DH9LBhVeijE',
  onExit: async () => {
    // the flow has ended — fetch the result from your backend
    const intent = await yourBackend.getIntent('intent_sandbox_dMggQ93ZYH6DH9LBhVeijE');
    console.log(intent.status); // 'approved' | 'declined' | ...
  },
});

ux.open();

`handler.open()`

Presents the modal and begins the flow. Calling open() again while the modal is already open, or after the flow has ended, is a no-op.

Signature

open: () => void

`handler.exit()`

Ends the flow programmatically: tears down the modal and fires onExit (once). Use it to close the UX from your own UI.

Signature

exit: () => void

`handler.destroy()`

Removes the modal and all listeners without firing onExit. Terminal and idempotent — after destroy() the handler is spent and open() does nothing. Use it for cleanup (for example, when unmounting your page) where teardown should not be treated as an exit.

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
  },
});

Getting Started

Integration Guides

Reference

Push JS SDK Reference

Widget

`new window.PushCash.Widget(options)`

Options (`WidgetOptions`)

Returns

Example

`widget.tokenize()`

Signature

Example

`widget.destroy()`

Signature

UX

`window.PushCash.UX(config)`

Config (`PushUXConfig`)

Returns

Example

`handler.open()`

Signature

`handler.exit()`

Signature

`handler.destroy()`

Signature

Apple Pay Launcher

`new window.PushCash.ApplePay(config)`

Parameters

Example

`launcher.display(args)`

Parameters

Example

​Push JS SDK Reference

​Widget

​new window.PushCash.Widget(options)

​Options (WidgetOptions)

​Returns

​Example

​widget.tokenize()

​Signature

​Example

​widget.destroy()

​Signature

​UX

​window.PushCash.UX(config)

​Config (PushUXConfig)

​Returns

​Example

​handler.open()

​Signature

​handler.exit()

​Signature

​handler.destroy()

​Signature

​Apple Pay Launcher

​new window.PushCash.ApplePay(config)

​Parameters

​Example

​launcher.display(args)

​Parameters

​Example

Push JS SDK Reference

Widget

`new window.PushCash.Widget(options)`

Options (`WidgetOptions`)

Returns

Example

`widget.tokenize()`

Signature

Example

`widget.destroy()`

Signature

UX

`window.PushCash.UX(config)`

Config (`PushUXConfig`)

Returns

Example

`handler.open()`

Signature

`handler.exit()`

Signature

`handler.destroy()`

Signature

Apple Pay Launcher

`new window.PushCash.ApplePay(config)`

Parameters

Example

`launcher.display(args)`

Parameters

Example