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:

<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 — process a card-not-present sale
• POST /transactions/virtual-auth — authorize a card-not-present transaction
• POST /payment-methods/virtual — tokenize a card or ACH bank account

Each response includes sessionId.

Minimal Integration

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):

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.

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

Response Examples

onComplete receives the full transaction object for transactions that reached the payment gateway (both approved and declined). onError receives a standard error object for SDK errors, session errors, and other non-transaction failures.

Example Approved Transaction (onComplete)

{
  "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 Declined Transaction (onComplete)

{
  "success": false,
  "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": 0,
  "balanceAmount": 0,
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "transactionResponses": [
    {
      "responseCode": 2,
      "amountApproved": 0,
      "cardType": "VISA",
      "paymentMethod": {
        "id": "pmt_tok_01JRZQ2B3C4D5E6F7G8H9J0KL"
      }
    }
  ],
  "resultCode": 3000,
  "resultText": "DECLINED"
}

Example Session Error (onError)

{
  "code": 3201,
  "status": "Rejected",
  "message": "Failed to retrieve session data",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-06-02T23:56:18.2102020Z"
}

Example SDK Error (onError)

{
  "code": 6000,
  "status": "Interrupted",
  "message": "Payment processing failed",
  "timestamp": "2025-06-02T23:56:18.2102020Z"
}

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)

Session (6100–6199)

Card / Tokenization (6200–6299)

ACH (6300–6399)

EFT (6400–6499)

Wallet (6500–6599)

Third-party SDK (6600–6699)

Form / Validation (6700–6799)

3D Secure (6800–6899)

3DS-specific codes are surfaced on declined card transactions via the transaction's resultCode (and, correspondingly, on the failure redirect URL's errorCode query parameter and the JS SDK's onComplete callback payload). They let merchants distinguish a 3DS-driven decline from a generic issuer decline or an unrelated SDK error. Only emitted when the session was initiated with formConfig.enable3DSecure: true.