Skip to main content
The PapelShip JavaScript SDK mounts the PapelPay card form inside your own checkout page, so the customer never leaves your site. The form loads in a frame from PapelShip: card details never touch your server or your page.

Before you start

  • Start the card payment on your server with POST /api/v1/invoices/{invoiceId}/papelpay and pass payment.embed_url to your page. See Overview.
  • Add the domain of your checkout page in the dashboard under PapelPay > Domains and verify it. A verified custom domain of your store works too, and so do its subdomains.
  • localhost and 127.0.0.1 work without setup while you develop.
On a domain that isn’t verified, the frame shows a notice instead of the form and onError receives origin_not_allowed.

Mount the form

checkout.html
The frame grows and shrinks with its content. mount returns { iframe, destroy }; call card.destroy() to remove the form, for example when the customer picks another payment method.

Options

Events

The same events are available globally with PapelShip.on("papelpay:paid", fn), papelpay:declined, papelpay:error and papelpay:ready, and as papelship:papelpay:paid (and so on) CustomEvents on window.

Confirm the payment on your server

onPaid tells your page that the card was charged. Before you deliver anything yourself, confirm the order on your server: wait for the order.completed webhook or read GET /api/v1/invoices/{invoiceId} and check that status is completed. See Webhooks.
Allow card payment features in the frame’s parent if you use your own iframe sandbox or permissions policy: the SDK sets allow="payment *" on its frame for wallet payments.