Embeddable checkout

The embeddable checkout opens Lango’s hosted pay page in a modal on your own site. The customer never leaves your page; when they finish, the popup tells your page and closes. It needs one script and a publishable key — no backend required.

1. Get a publishable key

In your dashboard, go to Developers → Keys → Publishable keys and create one.

A publishable (pk_) key is safe to put in a web page. Unlike a secret sk_ key it grants no read access and cannot move money — the most it can do is start a checkout that can only ever pay you. Lock each key to the domains where your button lives (its allowed origins); the popup will only open on those sites.

2. Add the button

Drop in the script once, then mark any element with data-lango-checkout:

<script src="https://checkout.lango.co.zw/embed.js"></script>

<button
  data-lango-checkout
  data-lango-key="pk_live_your_key"
  data-lango-amount="10000"
  data-lango-currency="USD"
  data-lango-reference="ORDER-1042"
>
  Pay with EcoCash
</button>

data-lango-amount is in minor units — 10000 is USD 100.00. That is the whole integration: a click opens the popup, the customer approves on their phone, and you get the result.

Attribute	Required	What it is
data-lango-key	yes	Your publishable pk_ key
data-lango-amount	yes	Amount in minor units (cents)
data-lango-currency	no	USD (default) or ZWG
data-lango-reference	yes	Your order reference
data-lango-return-url	no	Where to send the customer after paying

You don’t list the methods

The popup shows whatever methods are live right now — the same live catalogue (GET /v1/payment-methods). EcoCash, O’mari, InnBucks and any new rail appear automatically, and retired ones drop off, with no change to your page. The button label is just text; the customer picks the actual method in the popup.

3. Or call it yourself

For full control, call Lango.checkout(...) from your own code and react to the result:

<script src="https://checkout.lango.co.zw/embed.js"></script>
<script>
  document.querySelector('#pay').addEventListener('click', function () {
    Lango.checkout({
      key: 'pk_live_your_key',
      amount: 10000,
      currency: 'USD',
      reference: 'ORDER-1042',
      onSuccess: function () {
        window.location = '/thank-you'
      },
      onClose: function () {
        console.log('checkout closed')
      },
    })
  })
</script>

Tamper-proof amounts (recommended for real money)

With the button above, the amount lives in the page, so a determined customer could change it before paying. For anything that matters, create the checkout on your server with your secret key and hand the popup the resulting token — the amount is then fixed server-side and cannot be edited:

curl https://api.lango.co.zw/v1/checkout_sessions \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "currency": "USD", "reference": "ORDER-1042" }'
# → { "checkout_token": "tok_...", "checkout_url": "https://checkout.lango.co.zw/c/tok_..." }

Lango.checkout({ key: 'pk_live_your_key', token: 'tok_...' })

You can also skip the popup entirely and just redirect the customer to the returned checkout_url.

How it’s kept secure

• The popup is an iframe served by Lango, and it will only render on the origins you listed on the key (frame-ancestors, enforced by the browser).
• The publishable key can start a checkout and nothing else. Your secret keys never touch the page.
• Confirm every payment from your backend the same way you always do — the payment.succeeded webhook is the source of truth, not the popup.

Reacting to the result

onSuccess fires when the payment completes. Treat it as a UI cue only — fulfil the order from the webhook, which is signed and can’t be spoofed. A payment that is still confirming is unknown, never failed: see the unknown state.