> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Accept card payments in your own checkout with the Modulus JavaScript SDK

## Overview

The JavaScript SDK lets you collect card payments **inside your own web checkout**. Customers stay on your site, and the card details are entered into secure Modulus-hosted fields that your page never touches.

An integration has two pieces:

<CardGroup cols={2}>
  <Card title="Payment Intents API" icon="server">
    A server-side REST call that represents an amount the customer has agreed to pay. Your backend creates the intent with your secret key.
  </Card>

  <Card title="JavaScript SDK" icon="browser">
    A browser library that renders the card fields, runs 3D Secure, and confirms the payment with your publishable key.
  </Card>
</CardGroup>

Card data is entered into Modulus-hosted iframes. It never enters your frontend code or DOM.

## End to end

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant FE as Your frontend
    participant BE as Your server
    participant API as Modulus API
    participant SDK as Modulus JavaScript SDK
    C->>FE: Reaches checkout
    FE->>BE: Start payment
    BE->>API: POST /payment-intents (sk_)
    API-->>BE: id + client_secret
    BE-->>FE: id + client_secret
    FE->>SDK: Initialize and mount card fields (pk_)
    C->>SDK: Enter card in secure fields
    FE->>SDK: confirmPayment
    SDK->>API: Confirm (card + client_secret)
    API-->>SDK: 3D Secure challenge (if required)
    SDK-->>API: Authentication result
    API-->>SDK: SUCCEEDED + receipt
    SDK-->>FE: Result
    FE-->>C: Show receipt
```

## How it works

<Steps>
  <Step title="Create a Payment Intent (server)">
    When the customer reaches checkout, your server calls [Create a Payment Intent](/api-reference/ecom/create-payment-intent) with the amount and currency, using your secret key. You receive an `id` and a `client_secret`.
  </Step>

  <Step title="Hand the intent to the browser">
    Pass the `id` and `client_secret` to your checkout page. Your server never sees card data from here on.
  </Step>

  <Step title="Mount the card fields">
    Load the SDK, initialize it with your publishable key, and mount the secure card fields into your checkout layout.
  </Step>

  <Step title="Confirm the payment">
    Call `confirmPayment`. The SDK collects the card securely, runs 3D Secure if the bank requires it, and resolves with the final result.
  </Step>
</Steps>

## Prerequisites

You are provisioned two keys at onboarding, with separate sandbox and live sets:

| Key             | Prefix                  | Where it runs | Purpose                                                                                              |
| --------------- | ----------------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| Secret key      | `sk_test_` / `sk_live_` | Server only   | Creates payment intents. Never expose it in a browser or mobile app.                                 |
| Publishable key | `pk_test_` / `pk_live_` | Browser (SDK) | Confirms a payment, scoped to a single intent by its `client_secret`. Safe to ship in your frontend. |

## Base URLs

| Resource            | Sandbox URL                              |
| ------------------- | ---------------------------------------- |
| Payment Intents API | `https://api.sbx.moduluslabs.io/ecom/v1` |
| JavaScript SDK      | `https://js.sbx.moduluslabs.io/v1`       |

<Note>
  This documentation targets the sandbox environment. Use keys provisioned for sandbox; no real money is moved. See [Testing](/docs/testing) for the sandbox card numbers. Amounts are integers in the currency's smallest unit (for PHP, centavos).
</Note>