MARCO Connect SDK v2.10.2

The SDK

MARCO Connect is one embeddable SDK. It owns the widget, the wallet lifecycle, Passport discovery and creation, every state, the theme and size systems and accessibility. Your application subscribes to events and reads state — nothing else. Every Melega application and every external developer runs this exact runtime.

Script

Load once

SDK

Mount once

Events

Your app

React

Install

One script. mount() returns the SDK instance.

html

<div id="marco-connect"></div>
<script src="https://marco.melega.ai/widgets/marco-connect.v2.10.js" defer></script>
<script>
  window.addEventListener("load", function () {
    var marco = window.MarcoConnect.mount("#marco-connect", {
      application: "Your App",
      theme: "dark",
      size: "standard"
    });

    marco.on("passportResolved", function (e) {
      console.log("passport", e.passport.passportNumber);
    });
  });
</script>

https://marco.melega.ai/widgets/marco-connect.v2.10.js

Methods

connect()Runs the wallet + Passport ceremony.

disconnect()Ends the session and clears state.

open()Expands the connected panel.

close()Collapses the connected panel.

refresh()Re-reads Passport and M-Credits.

getState()Readonly snapshot of the current state.

on(event, fn)Subscribe. Returns an unsubscribe function.

destroy()Unmounts the widget and drops listeners.

Events

Subscribe with on(event, fn). Every subscription returns its own unsubscribe function.

readyThe SDK mounted and read its first state.

connectA wallet session was established.

disconnectThe session ended.

passportResolvedAn existing Passport was found.

passportCreatedA Passport was issued automatically.

errorAny failure, with a stable code.

changeAny state transition.

State

State is readonly and never fabricated. Unknown remains unknown.

statusidle · loading · connecting · connected · disconnected · error

connectedSession present.

loadingFirst read in flight.

syncingBackground refresh in flight.

wallet{ address, chainId } or null.

passport{ passportNumber, publicPassportId, lifecycleStatus } or null.

mCredits{ available, currency, known }. Unknown stays unknown.

applicationThe configured host application name.

versionSDK semantic version.

Configuration

Configuration only. There are no runtime forks.

applicationHost application name.

themedark · light · silver · blue · orange · forest · purple · gold

sizecompact · standard · full · navbar · floating

signatureCommunity signature visibility.

languageBCP-47 tag. 2.0.0 ships en.

originPortal origin used for links and the handshake.

Themes

Blacktheme: "dark"

Whitetheme: "light"

Silvertheme: "silver"

Bluetheme: "blue"

Orangetheme: "orange"

Foresttheme: "forest"

Purpletheme: "purple"

Goldtheme: "gold"

Sizes

Compactsize: "compact"

Standardsize: "standard"

Full widthsize: "full"

Navbarsize: "navbar"

Floatingsize: "floating"

Iconsize: "icon"

Examples

These are not separate integrations. Each one mounts the same SDK runtime.

html

<div id="marco-connect"></div>
<script src="https://marco.melega.ai/widgets/marco-connect.v2.10.js" defer></script>
<script>
  window.addEventListener("load", function () {
    var marco = window.MarcoConnect.mount("#marco-connect", {
      application: "Your App",
      theme: "dark",
      size: "standard"
    });

    marco.on("passportResolved", function (e) {
      console.log("passport", e.passport.passportNumber);
    });
  });
</script>

MARCO Pay hosted checkout

The merchant shows one Pay with MARCO control. Its server creates a signed session and sends the customer to MARCO's payment page; MARCO handles approval, the canonical receipt and the automatic return. No payment panel or wallet logic is embedded in the merchant experience.

v1.1.0 · https://marco.melega.ai/widgets/marco-pay.v1.js

Redirect control

html

<marco-pay
  checkout-url="{{ approval_url_from_your_server }}"
  theme="dark"
  size="standard"
></marco-pay>

<script src="https://marco.melega.ai/widgets/marco-pay.v1.js" defer></script>

States

Pay with MARCOThe merchant's own checkout control.

MARCO checkoutPayment and wallet approval on MARCO.

ReceiptCanonical MARCO payment result.

Automatic returnBack to the validated merchant page.

Configuration

checkoutUrlServer-created MARCO approval URL.

themedark · light · silver · blue · orange · forest · purple · gold

sizecompact · standard · full · navbar · floating · icon

signatureCommunity signature visibility.

originMARCO hosted-checkout origin.

Events

onReadyThe widget mounted.

onOpenThe customer opened the payment.

onPaymentCreatedA payment was created by the runtime.

onPaymentCompletedThe runtime reported a completed payment.

onRewardReceivedM-Credits were credited to the Passport.

onErrorAny failure, with a stable code.

Themes

Blacktheme: "dark"

Whitetheme: "light"

Silvertheme: "silver"

Bluetheme: "blue"

Orangetheme: "orange"

Foresttheme: "forest"

Purpletheme: "purple"

Goldtheme: "gold"

Examples

html

<marco-pay
  checkout-url="{{ approval_url_from_your_server }}"
  theme="dark"
  size="standard"
></marco-pay>

<script src="https://marco.melega.ai/widgets/marco-pay.v1.js" defer></script>

// approvalUrl is returned by your signed server request.
window.MarcoPay.redirect(approvalUrl);

tsx

<a href={approvalUrl}>Pay with MARCO</a>

Versioning

The SDK follows semantic versioning and exposes its version at window.MarcoConnect.version and on state.version. The v1 loader still works: it now delegates to this SDK.

Community Edition

Free forever. The expanded widget carries one discreet signature: “Powered by MARCO Passport”. Enterprise removes it.

Need an answer?

Search product help, ask the community or create a Passport-linked support ticket.

Open Help →

Back to Grow with MARCO