> For the complete documentation index, see [llms.txt](https://coda-payments.gitbook.io/coda-public-technical-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/hosted-component-integration/cards/integration-guide.md).

# Integration Guide

This guide walks you through the implementation of the Card Payment Hosted Component. Before you begin, ensure you have your `apiKey` and `projectId` ready.

### Prerequisites

* HTTPS: Your checkout page must be served over HTTPS with TLS 1.2 or higher.
* Backend Endpoint: You must have a server-side endpoint capable of receiving webhooks notifications.
* API Credentials: A valid `apiKey` and `projectId` assigned by Coda.

### Step 1: Initiate a Payment

The lifecycle begins on your server. Call the `/init.json` endpoint to generate the required session credentials.

Endpoint:  `POST /init.json`

```javascript
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/Component/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": 702,
        "payType": 427,
        "apiKey": "test_32774abe1cd7d8bae650ea48265e",
        "projectId": 21
        "orderId": "12321312321314",
        "currency": 702,
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}'
```

**Response**

Coda returns a Transaction ID and a Client Secret.

* Transaction ID: Store this in your database to link Coda's payment to your order.
* Client Secret: Pass this to your frontend securely. This secret authorizes the SDK to load the card fields for this specific transaction.

### Step 2: Initialize and Mount

Once your frontend receives the `clientSecret`, you can mount the secure card fields.

**Load the SDK & Container**

Include the Coda library on your checkout page and define a placeholder `div`. This container acts as the anchor where the SDK will securely inject the card input fields.

```html
<script src="https://js.codapayments.com/8.9.0/coda-card.min.js"></script>

<div id="payment-form"></div>

<button id="pay-button" disabled>Pay Now</button>
```

**Mount the Component**

With the library loaded and the container ready, use your `clientSecret` to initialize the session. The `mount()` method then replaces your empty `div` with a fully functional, secure card entry form.

```javascript
const codaCard = CodaCard();

// Initialize the components with your secret
const components = codaCard.components({
    clientSecret: '{{CLIENT_SECRET_FROM_BACKEND}}',
    appearance: {}
});

// Create and mount the 'charge' component into your #payment-form div
const chargeComponent = components.create('charge');
chargeComponent.mount('#payment-form');
```

Full documentation on the CodaCard SDK [here](/coda-public-technical-documentation/codapay/hosted-component-integration/cards/interact-with-the-codacard-sdk.md).

### Step 3: Handle Submission

The submit action is fully owned by you. You are responsible for managing the button state and invoking the submission.

**Readiness Logic**

Listen to the `readyStateChange` event to determine when to enable your "Pay" button. The form is considered ready only when all fields are filled and pass the Luhn algorithm and format checks.

```javascript
chargeComponent.on('readyStateChange', (isReady) => {
    // isReady returns a boolean
    document.getElementById('pay-button').disabled = !isReady;
});
```

**Invoking Submit**

When the user clicks your button, explicitly call the SDK's `submit()` method to forward the sensitive data directly to Coda.

```javascript
document.getElementById('pay-button').addEventListener('click', () => {
    // Trigger the payment flow
    chargeComponent.submit();
});
```

Full documentation on the CodaCard SDK [here](/coda-public-technical-documentation/codapay/hosted-component-integration/cards/interact-with-the-codacard-sdk.md).

### Step 4: Handle Payment Results

After the user submits the form and the payment is successful, Coda sends an asynchronous notification to your backend.

Webhook Requirements:

* Security: You must verify the Checksum of every notification to ensure it originated from Coda.
* Your server must respond with a `200 OK` within X seconds to acknowledge receipt.

Full documentation on notifications [here](/coda-public-technical-documentation/codapay/hosted-component-integration/cards/get-notified-of-a-transaction-status-change.md).