@cofee/checkout-web-sdk

Browser SDK for CoFee Standard Checkout. It opens a checkout overlay on your site and returns success, failure, and dismiss events to your page.

Always verify the payment on your server. Browser callbacks are not a source of truth.

Requirements

• A CoFee merchant publishable key
• A payment order_id created on your server before opening checkout

Install

npm install @cofee/checkout-web-sdk

For prerelease builds:

npm install @cofee/checkout-web-sdk@beta

Quick start

import { CofeeCheckout } from '@cofee/checkout-web-sdk';

const cofee = new CofeeCheckout({
  key: 'YOUR_KEY_ID',
  order_id: 'ord_…',
  environment: 'production', // or 'sandbox'
  currency: 'INR',
  name: 'Acme Corp',
  description: 'Test Transaction',
  logo_url: 'https://example.com/logo.png',
  handler(response) {
    // Payment completed in the overlay — verify on your server
    console.log(response.order_id, response.intent_id, response.amount, response.status);
  },
  modal: {
    ondismiss() {
      console.log('Checkout closed');
    }
  }
});

cofee.on('payment.failed', (response) => {
  console.log(response.error.code, response.error.description);
});

document.getElementById('pay-btn')?.addEventListener('click', (e) => {
  e.preventDefault();
  cofee.open();
});

Sandbox

const cofee = new CofeeCheckout({
  key: 'YOUR_KEY_ID',
  order_id: 'ord_…',
  environment: 'sandbox',
  handler(response) { /* … */ }
});

| environment | Checkout host | |---------------|---------------| | 'production' (default) | https://www.cofee.life/pay | | 'sandbox' | https://www.dev.cofee.life/pay |

Payment UI v2

Pass ui_version: 'v2' to open the v2 checkout experience inside the overlay:

const cofee = new CofeeCheckout({
  key: 'YOUR_KEY_ID',
  order_id: 'ord_…',
  ui_version: 'v2',
  theme: {
    color: '#05954e',
    ctaVarient: 'default' // or 'dark'
  },
  handler(response) { /* … */ }
});

The SDK appends version=v2 to the iframe entry URL. Bank return and in-checkout redirects preserve the flag automatically.

API

new CofeeCheckout(options)

| Option | Required | Description | |--------|----------|-------------| | key | Yes | Merchant publishable key | | order_id | Yes | Payment order id | | environment | No | 'production' (default) or 'sandbox' — selects the checkout host | | currency | No | Defaults to INR | | name | No | Business / display name | | description | No | Short description | | logo_url | No | Merchant logo URL | | ui_version | No | Pass 'v2' for the v2 payment gateway UI (default is v1) | | handler | No | Success callback | | modal.ondismiss | No | Called when the user closes checkout without completing | | modal.escape | No | Allow Escape to close (default true) | | theme.color | No | Accent color for v2 UI (hex, e.g. #05954e) | | theme.ctaVarient | No | Solid CTA fill: 'default' (green) or 'dark' (#262626). Accents still follow theme.color. |

Amount is taken from the order on CoFee’s side — you do not pass it into the SDK.

Methods

| Method | Description | |--------|-------------| | open() | Open the checkout overlay | | close() | Close the overlay (fires modal.ondismiss if payment was not completed) | | on(event, handler) | Listen for payment.success or payment.failed | | off(event, handler?) | Remove listener(s) |

Success response (handler / payment.success)

{
  order_id: 'ord_…',
  intent_id: '…',
  amount: '118',
  status: 'success'
}

Failure response (payment.failed)

{
  error: {
    code: 'PAYMENT_FAILED',
    description: 'Payment failed'
  }
}

Recommended flow

1. Create an order on your backend and receive an order_id.
2. Pass key and order_id into CofeeCheckout (set environment for sandbox).
3. Call open() when the customer chooses to pay.
4. On success, confirm the payment with your server before fulfilling the order.

More detail

• Option reference: documents/checkout.md
• Release notes: CHANGELOG.md

License

MIT