Pay Session

<script src="https://gateway.prahsys.com/n1/merchant/{merchantId}/session/{sessionId}/script.js"></script>

declare global {
  interface Window {
    PaymentSession: PaymentSession;
  }
}

interface PaymentSession {
  /**
   * Initialize the session: replace your input elements with secure iframes
   * and wire up callbacks.
   */
  configure(config: PaymentSessionConfig): void;

  /**
   * Collect values from all configured fields and submit them to the
   * session. The formSessionUpdate callback fires with the result.
   * Resolves on success, rejects on system error.
   */
  updateSessionFromForm(formType: "card"): Promise<void>;

  /**
   * Generic style setter — accepts any combination of states.
   */
  setStyle(fields: string[], styles: StyleConfig): void;

  /** Convenience: style applied on focus. */
  setFocusStyle(fields: string[], styles: FieldStyles): void;

  /** Convenience: style applied on hover. */
  setHoverStyle(fields: string[], styles: FieldStyles): void;

  /** Convenience: style applied to the placeholder pseudo-element. */
  setPlaceholderStyle(fields: string[], styles: FieldStyles): void;

  /** Convenience: style applied when a field is in the error state. */
  setErrorStyle(fields: string[], styles: FieldStyles): void;

  /** Convenience: style applied when a field is in the valid state. */
  setValidStyle(fields: string[], styles: FieldStyles): void;

  /**
   * Programmatically set the visual state of one or more fields.
   * Pass null to clear the state.
   */
  setFieldState(fields: string[], state: "error" | "valid" | null): void;
}

interface PaymentSessionConfig {
  /**
   * Optional. The session ID is already embedded in the script URL; if
   * provided here it must match.
   */
  session?: string;

  fields: {
    card?: {
      number?: string;
      securityCode?: string;
      expiryMonth?: string;
      expiryYear?: string;
      expiryDate?: string;
      nameOnCard?: string;
    };
  };

  /** Clickjacking mitigation strategies. */
  frameEmbeddingMitigation?: Array<"javascript" | "x-frame-options" | "csp">;

  callbacks: {
    /** Fires once all configured iframes are mounted and ready. */
    initialized: (response: InitializedResponse) => void;

    /** Fires with the result of updateSessionFromForm(). */
    formSessionUpdate: (response: FormSessionUpdateResponse) => void;
  };
}

interface InitializedResponse {
  status: "ok" | "error";
  message?: string;
}

interface FormSessionUpdateResponse {
  status: "ok" | "fields_in_error" | "system_error";
  session?: {
    id: string;
    version?: number;
  };
  /**
   * Field-level validation errors. Keys are field names; values are
   * short error codes: "required" or "invalid".
   */
  errors?: {
    number?: string;
    securityCode?: string;
    expiryMonth?: string;
    expiryYear?: string;
    expiryDate?: string;
    nameOnCard?: string;
  };
}

interface StyleConfig {
  default?: FieldStyles;
  hover?: FieldStyles;
  focus?: FieldStyles;
  error?: FieldStyles;
  valid?: FieldStyles;
  placeholder?: FieldStyles;
}

interface FieldStyles {
  [cssProperty: string]: string;
}

PaymentSession.configure({
  fields: {
    card: {
      number: "#card-number",
      securityCode: "#security-code",
      expiryMonth: "#expiry-month",
      expiryYear: "#expiry-year",
      nameOnCard: "#cardholder-name",
    },
  },
  frameEmbeddingMitigation: ["javascript"],
  callbacks: {
    initialized: function (response) {
      if (response.status === "ok") {
        // Fields are mounted — reveal your form.
      }
    },
    formSessionUpdate: function (response) {
      if (response.status === "ok") {
        // response.session.id is the updated session — send to your server.
      } else if (response.status === "fields_in_error") {
        // response.errors contains per-field codes; see "Handling Validation Errors".
      } else {
        // system_error — network failure or server error. Show a generic message.
      }
    },
  },
});

PaymentSession.updateSessionFromForm("card");

PaymentSession.setFocusStyle(["card.number", "card.securityCode"], {
  borderColor: "#3b82f6",
  borderWidth: "2px",
});

PaymentSession.setHoverStyle(["card.number", "card.securityCode"], {
  borderColor: "#6366f1",
});

PaymentSession.setPlaceholderStyle(["card.number", "card.nameOnCard"], {
  color: "#9ca3af",
  fontWeight: "400",
});

PaymentSession.setErrorStyle(["card.number", "card.securityCode"], {
  borderColor: "#ef4444",
  borderWidth: "2px",
  boxShadow: "0 0 0 3px rgba(239, 68, 68, 0.1)",
});

PaymentSession.setValidStyle(["card.number"], {
  borderColor: "#10b981",
});

const fields = [
  "card.number",
  "card.securityCode",
  "card.expiryMonth",
  "card.expiryYear",
];

// Set default styles (applied immediately, not tied to a state).
// Use this to set fonts, padding, and background to match your form.
PaymentSession.setStyle(fields, {
  default: {
    fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
    fontSize: "14px",
    color: "#111827",
    backgroundColor: "#ffffff",
    paddingTop: "8px",
    paddingBottom: "8px",
    paddingLeft: "12px",
    paddingRight: "12px",
  },
});

// Or set multiple states in a single call.
PaymentSession.setStyle(fields, {
  default:      { borderColor: "#d1d5db", borderWidth: "1px" },
  focus:        { borderColor: "#3b82f6", borderWidth: "2px" },
  error:        { borderColor: "#ef4444", borderWidth: "2px" },
  valid:        { borderColor: "#10b981" },
});

const errorMessages = {
  required: "This field is required",
  invalid: "Please enter a valid value",
};

function showFieldErrors(errors) {
  // Note: error styles are applied automatically — setFieldState is not required here.
  // Call it manually only if you need to mark additional fields as errors.

  Object.entries(errors).forEach(([fieldName, code]) => {
    const messageEl = document.getElementById(`${fieldName}-error`);
    if (messageEl) {
      messageEl.textContent = errorMessages[code] || code;
      messageEl.classList.remove("hidden");
    }
  });
}

PaymentSession.configure({
  fields: {
    card: {
      number: "#card-number",
      securityCode: "#security-code",
      expiryMonth: "#expiry-month",
      expiryYear: "#expiry-year",
      nameOnCard: "#cardholder-name",
    },
  },
  callbacks: {
    initialized: () => {},
    formSessionUpdate: (response) => {
      if (response.status === "ok") {
        // Forward response.session.id to your server to charge the card
      } else if (response.status === "fields_in_error" && response.errors) {
        showFieldErrors(response.errors);
      }
    },
  },
});