Payin SDK

npm install @paymentlabs/paymentlabs-js
# or
yarn add @paymentlabs/paymentlabs-js
# or
pnpm add @paymentlabs/paymentlabs-js

<script src="https://sdk.paymentlabs.io/payin/latest/paymentlabs.js"></script>

import { PaymentLabs } from "@paymentlabs/paymentlabs-js";

// 1. Create the SDK once, with your environment and merchant ID.
const sdk = PaymentLabs.create({
  environment: "sandbox", // switch to "production" when you go live
  merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
});

// 2. Mount the payment element into a container on your page.
const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container", // <div id="checkout-container"></div>
});

<div id="checkout-container"></div>
<button id="pay-button" disabled>Pay</button>

const payButton = document.getElementById("pay-button");

// The form is rendered and interactive.
element.on("checkout-loaded", () => {
  payButton.disabled = false;
});

// Reflect progress so the buyer knows something's happening.
element.on("payment-processing", (isProcessing) => {
  payButton.disabled = isProcessing;
  payButton.textContent = isProcessing ? "Processing…" : "Pay";
});

// The payment succeeded. Confirm it on your server before fulfilling the order.
element.on("checkout-completed", () => {
  showSuccessScreen();
});

// Something went wrong — tell the buyer what to do next.
element.on("checkout-failed", ({ errorReason }) => {
  showError(errorReason);
});

// Hand control to the SDK when the buyer clicks Pay.
payButton.addEventListener("click", () => element.submitPayment());

// Backend created this checkout with an amount of 0.
const element = await sdk.createElement("checkout", savecardCheckoutId, {
  containerId: "checkout-container",
});

const saveButton = document.getElementById("save-card-button");

element.on("checkout-loaded", () => {
  saveButton.disabled = false;
});

// Fired the same way — the card is now saved and reusable.
element.on("checkout-completed", () => {
  showCardSavedScreen();
});

saveButton.addEventListener("click", () => element.submitPayment());

<div id="checkout-container"></div>
<!-- Label the action for what it really is -->
<button id="save-card-button" disabled>Save card</button>

const element = await sdk.createElement("subscription", planOfferId, {
  containerId: "subscription-container",
});

element.on("subscription-loaded", () => {
  const offer = element.getSubscriptionOfferData();
  console.log("Plans available:", offer?.subscriptionPlans);
});

// The buyer picked a different plan from the offer.
element.on("subscription-plan-changed", (plan) => {
  updatePlanSummary(plan); // plan.name, plan.amount.formattedValue, plan.schedule…
});

element.on("subscription-completed", () => {
  showSubscriptionActiveScreen();
});

element.on("subscription-failed", ({ errorReason }) => {
  showError(errorReason);
});

// The chosen plan's checkout is on screen: only now can the buyer pay.
element.on("checkout-loaded", () => {
  const submitButton = document.getElementById("subscribe-button");
  submitButton.hidden = false;
  submitButton.addEventListener("click", () => element.submitPayment());
});

const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container",
});

await element.submitPayment(); // address comes from the SDK-rendered fields

const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container",
  billingDetails: {
    addressLayout: "full", // every address field from the start
  },
});

const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container",
  billingDetails: {
    fields: { address: false }, // SDK won't render address fields
  },
});

await element.submitPayment({
  billingDetails: {
    address: {
      address1: "123 Main Street",
      address2: "Apt 4B", // optional
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US", // ISO 3166-1 alpha-2
    },
  },
});

const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container",
  hideFeeSummary: true,
});

element.on("payment-method-changed", ({ amount, payableAmount }) => {
  // No total yet: the methods cost different amounts and the buyer has not picked one.
  showOrderSummary({ subtotal: amount, total: payableAmount });
});

const element = await sdk.createElement("checkout", checkoutId, {
  containerId: "checkout-container",
  theme: {
    mode: "light", // "light" (default) or "dark"
    colors: {
      seed: {
        brand: "#5b3df5",    // your primary color — buttons, accents
        neutral: "#1f2937",  // text and neutral UI
        info: "#2563eb",
        positive: "#16a34a", // success
        negative: "#dc2626", // errors
        warning: "#d97706",
      },
      // Optional fine-grained overrides
      overrides: {
        "bg-main": "#ffffff",
      },
    },
  },
});

await sdk.updateTheme("dark");

// Register many at once
["checkout-loaded", "checkout-completed", "checkout-failed"].forEach((event) =>
  element.on(event, (data) => analytics.track(event, data)),
);

element.on("checkout-failed", ({ errorReason, extendedErrorReason, unresolved }) => {
  if (unresolved) {
    show("We are confirming your payment. Please don't pay again.");
    return;
  }
  switch (errorReason) {
    case "MISSING_INSTRUMENT":
      show("Please choose a payment method to continue.");
      break;
    case "INVALID_INSTRUMENT":
      show("Those payment details look off. Please double-check them.");
      break;
    case "CHARGE_INSTRUMENT_ERROR":
      show("Your card was declined. Try another card or contact your bank.");
      break;
    case "APPLICATION_ERROR":
      show("Something went wrong on our side. Please try again shortly.");
      break;
    default:
      show("Payment couldn't be completed. Please try again.");
  }

  if (extendedErrorReason) console.debug("Decline detail:", extendedErrorReason);
});

element.on("sdk-error", (error) => {
  // error.code      stable code, e.g. "CHARGE_REJECTED" — switch on this
  // error.category  "load" | "authentication" | "validation" | "payment" | "three_d_secure"
  //                 | "processing" | "wallet" | "address_autocomplete" | "internal"
  // error.severity  "fatal" | "recoverable" | "degraded"
  // error.message   fixed English sentence for the code — for your logs, not for buyers
  analytics.track("payment_sdk_error", error);

  if (error.code === "PAYMENT_STATUS_UNKNOWN") {
    // The payment may still go through. Don't cancel the order — check its status later.
  }
});

const result = await element.submitPayment();
if (!result.success) {
  console.log(result.code); // e.g. "CHARGE_VALIDATION"
}

import { useEffect, useRef, useState } from "react";
import { PaymentLabs, PaymentElement } from "@paymentlabs/paymentlabs-js";

export function Checkout({
  checkoutId,
  onSuccess,
  onFailure,
}: {
  checkoutId: string;
  onSuccess: () => void;
  onFailure: (reason: string) => void;
}) {
  const elementRef = useRef<PaymentElement | null>(null);
  const [ready, setReady] = useState(false);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    let element: PaymentElement | undefined;

    (async () => {
      const sdk = PaymentLabs.create({
        environment: "sandbox",
        merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
      });

      element = await sdk.createElement("checkout", checkoutId, {
        containerId: "checkout-container",
      });
      elementRef.current = element;

      element.on("checkout-loaded", () => setReady(true));
      element.on("payment-processing", setLoading);
      element.on("checkout-completed", onSuccess);
      element.on("checkout-failed", ({ errorReason }) => onFailure(errorReason));
    })();

    return () => element?.destroy();
  }, [checkoutId, onSuccess, onFailure]);

  return (
    <div>
      <div id="checkout-container" />
      {ready && (
        <button onClick={() => elementRef.current?.submitPayment()} disabled={loading}>
          {loading ? "Processing…" : "Pay"}
        </button>
      )}
    </div>
  );
}

<template>
  <div>
    <div id="checkout-container"></div>
    <button v-if="ready" @click="submit" :disabled="loading">
      {{ loading ? "Processing…" : "Pay" }}
    </button>
  </div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from "vue";
import { PaymentLabs, PaymentElement } from "@paymentlabs/paymentlabs-js";

const props = defineProps<{ checkoutId: string }>();
const emit = defineEmits<{ success: []; failure: [reason: string] }>();

const element = ref<PaymentElement | null>(null);
const ready = ref(false);
const loading = ref(false);

onMounted(async () => {
  const sdk = PaymentLabs.create({
    environment: "sandbox",
    merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  });

  element.value = await sdk.createElement("checkout", props.checkoutId, {
    containerId: "checkout-container",
  });

  element.value.on("checkout-loaded", () => (ready.value = true));
  element.value.on("payment-processing", (p) => (loading.value = p));
  element.value.on("checkout-completed", () => emit("success"));
  element.value.on("checkout-failed", ({ errorReason }) => emit("failure", errorReason));
});

onUnmounted(() => element.value?.destroy());

const submit = () => element.value?.submitPayment();
</script>

<div id="checkout-container"></div>
<button id="pay-button" disabled>Pay</button>

<script type="module">
  import { PaymentLabs } from "@paymentlabs/paymentlabs-js";

  const sdk = PaymentLabs.create({
    environment: "sandbox",
    merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  });

  const element = await sdk.createElement("checkout", "your-checkout-id", {
    containerId: "checkout-container",
  });

  const payButton = document.getElementById("pay-button");
  element.on("checkout-loaded", () => (payButton.disabled = false));
  element.on("checkout-completed", () => alert("Payment complete"));
  element.on("checkout-failed", ({ errorReason }) => alert(`Failed: ${errorReason}`));
  payButton.addEventListener("click", () => element.submitPayment());
</script>

<!DOCTYPE html>
<html>
  <body>
    <div id="checkout-container"></div>
    <button id="pay-button" disabled>Pay</button>

    <script src="https://sdk.paymentlabs.io/payin/latest/paymentlabs.js"></script>
    <script>
      (async () => {
        // PaymentLabs is available globally from the CDN.
        const sdk = PaymentLabs.create({
          environment: "production",
          merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
        });

        const element = await sdk.createElement("checkout", "your-checkout-id", {
          containerId: "checkout-container",
        });

        const payButton = document.getElementById("pay-button");
        element.on("checkout-loaded", () => (payButton.disabled = false));
        element.on("payment-processing", (busy) => {
          payButton.disabled = busy;
          payButton.textContent = busy ? "Processing…" : "Pay";
        });
        element.on("checkout-completed", () => alert("Payment complete"));
        element.on("checkout-failed", (e) => alert(`Failed: ${e.errorReason}`));

        payButton.addEventListener("click", () => element.submitPayment());
      })();
    </script>
  </body>
</html>

const sdk = PaymentLabs.create({
  environment: "sandbox", // "sandbox" | "production"
  merchantId: "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
});

interface ElementOptions {
  containerId: string;            // ID of the DOM element to render into (required)
  theme?: ThemeConfig;            // Brand colors and light/dark mode
  billingDetails?: BillingDetailsConfig; // Address collection behavior
  hideFeeSummary?: boolean;       // Hide the subtotal, fee and total; default false (see Showing the fee)
}

const result = await element.submitPayment();
// { success: boolean; instrumentId?: string; transactionId?: string; error?: string; code?: SdkErrorCode }

import {
  PaymentLabs,
  PaymentElement,
  Checkout,
  SubscriptionOffer,
  SubscriptionPlan,
  CheckoutErrorReason,
  ThemeConfig,
  SdkErrorPayload,
  SdkErrorCode,
} from "@paymentlabs/paymentlabs-js";

interface Checkout {
  id: string;
  buyerEmail: string;
  buyerId: string;
  merchantId: string;
  merchantName: string;
  alias: string;                 // your reference / description
  amount: { value: number; currency: string }; // value: 0 ⇒ save-card checkout
  payableAmount?: { value: number; currency: string }; // see Showing the fee
  payableAmounts?: Partial<Record<InstrumentType, { value: number; currency: string }>>;
  recurring?: {                  // a subscription's cycle, priced like the fields above
    payableAmount?: { value: number; currency: string };
    payableAmounts?: Partial<Record<InstrumentType, { value: number; currency: string }>>;
  };
  status: CheckoutStatus;
  currentTransactionStatus?: CheckoutTransactionStatus;
  errorTransaction?: {
    transactionId: string;
    errorReason: CheckoutErrorReason;
    extendedErrorReason?: CheckoutExtendedErrorReason;
    checkoutInstrumentId: string;
    instrumentType: InstrumentType;
  };
  enabledCheckoutInstruments: InstrumentType[];
  requiresFraudSession: boolean;
  expiresAt: string;             // ISO 8601
  links: { embeddable: string; checkout: string };
  redirectLinks?: {
    successRedirectUrl?: string;
    failureRedirectUrl?: string;
    expiredRedirectUrl?: string;
  };
  termsOfServiceUrl: string;
  privacyPolicyUrl: string;
}

type CheckoutStatus =
  | "PENDING"     // awaiting payment
  | "PROCESSING"  // payment in progress
  | "PAID"        // succeeded
  | "FAILED"      // failed
  | "EXPIRED"     // time window passed
  | "UNKNOWN"     // the charge was never confirmed; do not charge again
  | "CREATING" | "ACTIVE" | "TRIAL"; // subscription statuses; a checkout never has them

interface SubscriptionOffer {
  id: string;
  merchantId: string;
  userId: string;
  subscriptionPlanIds: string[];
  subscriptionPlans: SubscriptionPlan[];
  expiresAt: string;
  links: { embeddable: string; self: string };
}

interface SubscriptionPlan {
  id: string;
  merchantId: string;
  merchantDisplayName: string;
  sort: string;                  // ordering/grouping hint, e.g. "RegularPlan#100"
  name: string;
  description?: string;
  enabledCheckoutInstruments: InstrumentType[];
  schedule: Schedule;
  amount: Money;
  trialPeriod?: Schedule;
  status: "ACTIVE" | "CANCELED";
  termsOfServiceUrl?: string;
  privacyPolicyUrl?: string;
}

interface Schedule {
  interval: "daily" | "weekly" | "monthly" | "yearly";
  intervalCount: number;         // e.g. interval "monthly" + count 2 = every 2 months
}

interface Money {
  value: number;                 // amount as a decimal value
  currency: string;              // ISO 4217
  formattedValue: string;        // e.g. "$9.99"
  digits: number;                // decimal digits for the currency
  wholeValue: number;            // value with no decimals (usually cents)
}

interface SdkErrorPayload {
  code: SdkErrorCode;            // e.g. "CHARGE_REJECTED"
  category: "load" | "authentication" | "validation" | "payment" | "three_d_secure"
    | "processing" | "wallet" | "address_autocomplete" | "internal";
  severity: "fatal" | "recoverable" | "degraded";
  message: string;               // fixed English sentence for the code
  timestamp: string;             // ISO 8601
  paymentMethod?: "payment-card" | "bank-transfer" | "saved-instrument" | "apple-pay" | "google-pay";
  httpStatus?: number;
  reason?: string;               // 3D Secure step that failed
  fields?: string[];             // invalid field ids, never values
  checkoutId?: string;
  transactionId?: string;
}

interface ThemeConfig {
  mode?: "dark" | "light";       // defaults to "light"
  colors?: {
    seed?: {
      brand: string;
      neutral: string;
      info: string;
      positive: string;
      negative: string;
      warning: string;
    };
    overrides?: {
      "bg-main": string;         // main background override
    };
  };
}

interface BillingDetailsConfig {
  fields?: {
    address?: boolean;           // false ⇒ you provide the address at submit time
  };
  addressLayout?: "compact" | "full"; // optional, default "compact"
}

interface SubmitPaymentRequest {
  billingDetails: {
    address?: {
      address1: string;          // required
      address2?: string;
      city: string;              // required
      state: string;             // required
      postalCode: string;        // required
      country: string;           // required, ISO 3166-1 alpha-2
    };
  };
}