Omni API Dev

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>

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

Each response includes sessionId and iframeUrl.

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

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.

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)

{
  "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)

{
  "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