# Integrated Payment SDK

The Integrated Payment SDK embeds a fully encapsulated Web Component (Custom Element with Shadow DOM) into your checkout page. A single JavaScript module registers the `ic.payment.v1.mount(...)` function, which renders a secure payment form with optional Apple Pay and Google Pay wallet buttons.

> **Note:** Apple Pay and Google Pay are only available for card-based sale transactions (`POST /transactions/virtual-sale`). Wallet buttons are not displayed for authorization, tokenization, or ACH sessions.

## Script Endpoint

Load the SDK bundle on your checkout page:

```html
<script src="https://cdn.omni.integratedcommerce.io/sdk/latest/ic-pay-sdk.js"></script>
```

## Related API Endpoints

To start a hosted payment session and receive the `sessionId` used by `ic.payment.v1.mount(...)`, call one of:

- [`POST /transactions/virtual-sale`](#operation-saleCardNotPresent) — process a card-not-present sale
- [`POST /transactions/virtual-auth`](#operation-authCardNotPresent) — authorize a card-not-present transaction
- [`POST /payment-methods/virtual`](#operation-createCardNotPresentToken) — tokenize a card or ACH bank account

Each response includes `sessionId` and `iframeUrl`.

## Minimal Integration

```js
const controller = ic.payment.v1.mount({
  sessionId: response.sessionId,
  container: "#payment-container", // CSS selector, element ID, or HTMLElement
  environment: "prod",
  onComplete: (transaction) => console.log("Payment complete", transaction),
  onError: (error) => console.error("Payment error", error),
});

// To tear down the payment form (e.g. on page navigation):
controller.unmount();
```

## Full Configuration

All properties accepted by `ic.payment.v1.mount(config)`:

| Property | Type | Required | Description |
|---|---|---|---|
| `sessionId` | `string` | Yes | Payment session identifier returned by the API. |
| `container` | `string` or `HTMLElement` | Yes | CSS selector, element ID, or DOM element to mount into. |
| `environment` | `prod` or `sandbox` | No | Selects the API host. Defaults to `"prod"`. |
| `wallets` | `object` | No | `{ applePay?: boolean, googlePay?: boolean }`. Both default to `true`. Only applies to card-based sale sessions. |
| `theme` | `object` | No | Visual overrides — see Theming section below. |
| `onReady` | `function` | No | Called when the form is ready. Receives `{ sessionId }`. |
| `onComplete` | `function` | No | Called on successful payment. Receives the transaction object. |
| `onError` | `function` | No | Called on payment error. Receives the standard payment result object with `success: false`. |

The return value is a `MountController` with a single method:

- `unmount()` — removes the component, wallet buttons, event listeners, and cleans up all SDK state.

## Theming

Pass a `theme` object to customize the payment form appearance. Theme values are applied as CSS custom properties on the Shadow DOM host and propagated to hosted card fields.

```js
ic.payment.v1.mount({
  sessionId: "...",
  container: "#payment-container",
  theme: {
    primary: "#7c3aed",
    primaryHover: "#6d28d9",
    borderRadius: "8px",
    textColor: "#111827",
  },
});
```

## Response Examples

`onComplete` and `onError` both receive a standardized payment result object with a `success` flag.

Example Success Response (`onComplete`)

```json
{
  "success": true,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-06-02T23:56:18.2102020Z",
  "type": "Sale",
  "status": "Completed",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "accountHolder": {
    "id": "ach_01JRZQ1A2B3C4D5E6F7G8H9J0K",
    "externalId": "ext_customer_123",
    "contact": {
      "name": "Jane Doe",
      "countryCode": "US",
      "zipCode": "30303",
      "address": "123 Peachtree St",
      "address2": "Suite 200",
      "state": "GA",
      "city": "Atlanta"
    }
  },
  "transactionResponses": [
    {
      "responseCode": 1,
      "amountApproved": 1000,
      "cardType": "VISA",
      "paymentMethod": {
        "id": "pmt_tok_01JRZQ2B3C4D5E6F7G8H9J0KL"
      }
    }
  ],
  "resultCode": 0,
  "resultText": "APPROVED"
}
```

Example Failed Response (`onError`)

```json
{
  "success": false,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "type": "Sale",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "resultCode": 6000,
  "resultText": "Transaction declined",
  "errorMessage": "Transaction declined",
  "errorCode": 6000
}
```

## SDK Error Codes

The SDK uses a dedicated range of numeric error codes from **6000 to 6999**. These codes are reported to the `onError` callback and are also sent to the server for observability.

### General (6000–6099)

| Code | Name | Description |
|------|------|-------------|
| 6000 | SdkGenericError | Catch-all for unexpected SDK errors |
| 6001 | SdkJavaScriptError | Unexpected JavaScript runtime error |

### Session (6100–6199)

| Code | Name | Description |
|------|------|-------------|
| 6100 | SdkSessionLoadFailed | Failed to fetch session data from the API |
| 6101 | SdkSessionExpired | The payment session timed out |
| 6102 | SdkSessionNotInitialized | Session or component not yet initialized |

### Card / Tokenization (6200–6299)

| Code | Name | Description |
|------|------|-------------|
| 6200 | SdkCardFieldsInvalid | One or more hosted card fields failed validation |
| 6201 | SdkCardTokenizationFailed | Card tokenization request failed |
| 6202 | SdkCardInitFailed | Hosted card fields failed to initialize |
| 6203 | SdkCardProcessingFailed | Card payment API call failed |

### ACH (6300–6399)

| Code | Name | Description |
|------|------|-------------|
| 6300 | SdkAchFieldsInvalid | ACH form fields failed validation |
| 6301 | SdkAchProcessingFailed | ACH payment API call failed |

### EFT (6400–6499)

| Code | Name | Description |
|------|------|-------------|
| 6400 | SdkEftProcessingFailed | EFT payment API call failed |

### Wallet (6500–6599)

| Code | Name | Description |
|------|------|-------------|
| 6500 | SdkWalletError | Error during Apple Pay or Google Pay flow |
| 6501 | SdkWalletProcessingFailed | Wallet payment API call failed |

### Third-party SDK (6600–6699)

| Code | Name | Description |
|------|------|-------------|
| 6600 | SdkThirdPartySdkLoadFailed | Failed to load an external SDK (e.g. SafeCharge) |

### Form / Validation (6700–6799)

| Code | Name | Description |
|------|------|-------------|
| 6700 | SdkFormValidationFailed | General form validation failure |
| 6701 | SdkBillingValidationFailed | Billing address fields failed validation |