Embedded Checkout (ninepay.js)

The embedded checkout puts the payment of a NinePay invoice inside your page. Your page has the title, the amount and the pay button; the NinePay iframe has only the payment methods, the card fields and the PIX QR code, styled to match your page.

The card goes from the iframe straight to NinePay: your page never sees it.

Before you integrate

1. Register your site address. In the dashboard (user menu → Integrações → Checkout embutido), register the addresses that will open the checkout: only https://domain or https://domain:port, without a path, up to five. Without any, the browser refuses the iframe.
2. Check the plans' methods. The iframe offers the invoice's allowed_methods, in this order: card, PIX Automático, PIX and bank slip. Open Finance does not appear in the embedded checkout, because the bank does not open in an iframe. Subscription invoices inherit the plan's methods.

On your server

Everything that uses the API token stays on your server. The token never goes to the browser.

A one-off charge

Create the open invoice, without a card, with open: true and the methods the iframe may offer:

curl -X POST https://payments.cefis.com.br/api/v1/payments \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "id": 123 },
    "method": "credit",
    "open": true,
    "allowed_methods": ["credit", "pix", "billet"],
    "value": 5000,
    "due_date": "2026-11-10"
  }'

allowed_methods is required with open. Nothing is charged on creation: the invoice waits for payment in the iframe. Send the payment.uuid from the response to the page.

A subscription

Create the subscription with the method and without a card. It starts as new, with the first invoice open; that invoice is the one that goes to the iframe, and paying it activates the subscription.

curl -X POST https://payments.cefis.com.br/api/v1/subscriptions \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "id": 123 },
    "plan": { "id": 456 },
    "method": "credit",
    "allowed_methods": ["credit"]
  }'

• The response contains customer, subscription and payment: send the payment.uuid to the page.
• Without the method, the subscription is created without any invoice, and there is nothing to pay in the iframe.
• allowed_methods is optional: a subset of the plan's methods, for the first invoice only (later ones use the plan's). With ["credit"], the iframe shows only the card.

After the payment

• Grant or suspend access only through the webhook, confirming with GET /payments/{id}. The paid event on the page is for updating the screen: a browser event can be forged.
• A new subscription that is not paid is not canceled automatically. Cancel the subscription with POST /subscription/cancel and the body { "subscription": { "id": 789 } }, and the open invoice with DELETE /payments/{id}.
• A canceled invoice can no longer be paid. Cancel the invoices you no longer want.

On the page

The script always has the same address, https://checkout.ninepay.com.br/js/v1/ninepay.js. Fixes and new v1 features reach it without you changing anything; a breaking change gets a new address (/js/v2/), and v1 stays online. Ninepay.version reports the exact build.

The dashboard's Integrations screen generates this code with the look and options you choose.

<div id="pagamento"></div>
<button id="pagar" disabled>Pagar</button>

<script src="https://checkout.ninepay.com.br/js/v1/ninepay.js"></script>
<script>
  const ninepay = Ninepay()
  const elements = ninepay.elements({
    payment: '<uuid da fatura>', // comes from your server
    // Optional: without it, the look saved in the dashboard applies
    appearance: {
      theme: 'default', // or 'night' | 'flat'
      labels: 'floating', // or 'above' | 'auto'
      inputs: 'condensed', // or 'spaced'
      variables: { colorPrimary: '#0057b8', fontFamily: 'Inter', borderRadius: 8 },
      rules: { '.Tab--selected': { borderColor: '#0057b8' } }
    }
  })
  const pagamento = elements.create('payment', {
    layout: 'tabs', // or 'accordion' | 'steps'
    paymentMethodOrder: ['credit', 'pix', 'billet'],
    saveCard: 'ask' // or 'always' | 'never'
  })
  pagamento.mount('#pagamento')

  const pagar = document.getElementById('pagar')

  // The button is only enabled once the fields of the chosen method are complete
  pagamento.on('change', event => {
    pagar.disabled = !event.complete
  })
  pagamento.on('paid', () => {
    // Paid on this screen (including PIX or bank slip paid later).
    // Update the screen; access is granted through the webhook.
  })

  pagar.addEventListener('click', async () => {
    pagar.disabled = true
    const { error: invalido } = await elements.submit() // validates, without sending
    if (invalido) {
      pagar.disabled = false
      return
    }
    const { error, payment } = await ninepay.confirmPayment({ elements })
    if (error) {
      pagar.disabled = false // the decline is already shown in the iframe
      return
    }
    // payment.status: 'succeeded' (card approved) or 'requires_action'
    // (the PIX QR code or the bank slip on screen, waiting for payment)
  })
</script>

Changing the card

The same script, with the subscription uuid and mode: 'setup': only the card fields, and your page's button confirms.

const elements = ninepay.elements({ subscription: '<uuid da assinatura>', mode: 'setup' })
elements.create('payment').mount('#cartao')

botao.onclick = async () => {
  const { error, subscription } = await ninepay.confirmSetup({ elements })
  // subscription.status: 'succeeded' (the new card is now the subscription's card)
}

Always use the subscription uuid, which comes from your server; never the numeric id.

Reference

Element options

The methods are credit, pix_automatic, pix and billet. For example, on a one-off installment of a subscription with PIX Automático, paymentMethods: ['credit', 'pix', 'billet'] hides PIX Automático.

Events

All of them come with elementType: 'payment'.

Errors

Errors come as { type, code, message }, with message in Portuguese, ready to display:

Appearance

appearance accepts { theme?, labels?, inputs?, variables?, rules? }. Anything that does not follow the format is ignored, without an error, and the default applies.

• theme: 'default' (neutral), 'night' or 'flat', the starting point for the variables.
• labels: 'auto' (default), 'above' (the label above the field) or 'floating' (inside the field, moving up as you type).
• inputs: 'spaced' (default) or 'condensed' (the card fields in a single block).

The company's default appearance. In Integrações → Checkout embutido, in the dashboard, you save a theme and the variables; the iframe uses this appearance when the page does not send appearance. What the page sends wins, variable by variable; a theme different from the saved one discards the saved variables. A change in the dashboard shows up within a minute.

Variables

Rules

rules applies CSS by public class: { ".Tab--selected": { "borderColor": "#47a472" } }. Each selector is a class, with at most one state and one pseudo-class, in that order (.Class--state:pseudo).

A length is 0 or a number in px, rem or em (rem and em count as 16px). Not accepted: url(), var(), !important, attribute, descendant or sibling selectors, or properties that change the layout (position, display, width, height, margin, transform and similar). Limits: 40 selectors, 12 properties per selector and 120 characters per value. A rule with color or backgroundColor contrast below 3:1 is discarded. In older browsers (before Safari 16.4), rules do not apply and only the variables are used.

Precautions

• Always load the script from https://checkout.ninepay.com.br, never from a copy or a CDN: the iframe's origin is the one the script came from. For the sandbox, pass Ninepay({ origin: 'https://...' }); only https is accepted (or http://localhost, for testing).
• The page's CSP must allow the checkout: script-src and frame-src with https://checkout.ninepay.com.br.
• Display any data that comes from the iframe as text, never in innerHTML.
• The script does not use SRI, because it receives fixes at the same address. If you need SRI, ask NinePay for a frozen copy.
• Do not mount the checkout inside another iframe. If your page puts sandbox on a surrounding iframe, include allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox (the bank slip PDF opens in another tab).
• The iframe limits confirmations (one at a time and five per minute), but protection against card testing is NinePay's, on the server.