Events

Listen to embedded checkout events

You can subscribe to both payment and minting / asset delivery events.

See a live demo

Fill out the checkout below and observe the events on the right side. Enter a valid email address to receive the purchase receipt.

Use the test card number 4242 4242 4242 4242 to trigger a successful payment.

Event Types

Payment Events

Payment events notify of price changes and events happening while capturing the user’s payment (e.g. successful payments, rejected cards).

Adding Payment Events

Subscribe by adding an onEvent handler to the CrossmintPaymentElement.

See example

The following example will log all events to the browser console. You can jump ahead to see some examples for capturing and reacting to specific events further below.

react

import { CrossmintPaymentElement } from "@crossmint/client-sdk-react-ui";

const Crossmint: React.FC = () => {
  return (
    <CrossmintPaymentElement
      projectId={projectId}
      collectionId={collectionId}
      environment={environment}
      emailInputOptions={{
        show: true,
      }}
      mintConfig={{
        totalPrice: "0.001",
        quantity: "1",
      }}
      onEvent={(event) => {
        console.log(event.type, event);
      }}
    />
  );
};

export default Crossmint;

Types of Payment Events

Quotes

quote:status.changed

Triggered when the price is calculated or when it changes.

Example response

{
  "type": "quote:status.changed",
  "payload": {
    "totalPrice": {
      "amount": "0.50",
      "currency": "usd"
    },
    "lineItems": [
      {
        "metadata": {
          "title": "Collection Name (set in dev console)",
          "description": "Collection Description (set in dev console)",
          "imageUrl": "https://uploadthing.com/f/your_collection_image.png"
        },
        "price": {
          "amount": "0.50",
          "currency": "usd"
        },
        "quantity": 1
      }
    ]
  }
}

quote:status.invalidated

Triggered when a new quote is retrieved and invalidates the previous one.

Example response

{
  "type": "quote:status.invalidated",
  "payload": {}
}

Payments

payment:preparation.succeeded

Triggered when checkout is ready for payment.

Example response

{
  "type": "payment:preparation.succeeded",
  "payload": {}
}

payment:preparation.failed

Triggered when checkout preparation fails.

How to solve

The most common cause is a missing email address. You can render an email input field to the CrossmintPaymentElement by setting the emailInputOptions prop to { show: true }. If you collect email elsewhere in your application you can set recipient.email programmatically.

Render Input

  <CrossmintPaymentElement
    // removed for brevity
    emailInputOptions={{
      show: true,
    }}
    ...
  />

Example response

{
  "type": "payment:preparation.failed",
  "payload": {}
}

payment:process.started

Triggered when checkout is ready for payment.

Example response

{
  "type": "payment:process.started",
  "payload": {}
}

payment:process.succeeded

Triggered when payment has been successfully authorized.

(Payment capture occurs after transaction:fulfillment.succeeded)

Example response

{
  "type": "payment:process.succeeded",
  "payload": {
    "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b"
  }
}

The orderIdentifier returned in the response is used to subscribe to minting events.

payment:process.rejected

Triggered if a user’s card has been rejected.

Example response

{
  "type": "payment:process.rejected",
  "payload": {
    "error": {
      "code": "payments:payment-rejected.generic-decline",
      "message": "The card was declined for an unknown reason."
    },
    "orderIdentifier": "3b8860e5-837b-44c5-99be-17f3f19238f6",
    "paymentMethodType": "credit-card"
  }
}

You can trigger this event using the high risk test card number: 4000 0000 0000 4954

payment:process.cancelled

Triggered if a user cancelled the payment or closed the checkout.

Payment events notify of price changes and events happening while capturing the user’s payment (e.g. successful payments, rejected cards).

Adding Payment Events

Subscribe by adding an onEvent handler to the CrossmintPaymentElement.

See example

The following example will log all events to the browser console. You can jump ahead to see some examples for capturing and reacting to specific events further below.

react

import { CrossmintPaymentElement } from "@crossmint/client-sdk-react-ui";

const Crossmint: React.FC = () => {
  return (
    <CrossmintPaymentElement
      projectId={projectId}
      collectionId={collectionId}
      environment={environment}
      emailInputOptions={{
        show: true,
      }}
      mintConfig={{
        totalPrice: "0.001",
        quantity: "1",
      }}
      onEvent={(event) => {
        console.log(event.type, event);
      }}
    />
  );
};

export default Crossmint;

Types of Payment Events

Quotes

quote:status.changed

Triggered when the price is calculated or when it changes.

Example response

{
  "type": "quote:status.changed",
  "payload": {
    "totalPrice": {
      "amount": "0.50",
      "currency": "usd"
    },
    "lineItems": [
      {
        "metadata": {
          "title": "Collection Name (set in dev console)",
          "description": "Collection Description (set in dev console)",
          "imageUrl": "https://uploadthing.com/f/your_collection_image.png"
        },
        "price": {
          "amount": "0.50",
          "currency": "usd"
        },
        "quantity": 1
      }
    ]
  }
}

quote:status.invalidated

Triggered when a new quote is retrieved and invalidates the previous one.

Example response

{
  "type": "quote:status.invalidated",
  "payload": {}
}

Payments

payment:preparation.succeeded

Triggered when checkout is ready for payment.

Example response

{
  "type": "payment:preparation.succeeded",
  "payload": {}
}

payment:preparation.failed

Triggered when checkout preparation fails.

How to solve

The most common cause is a missing email address. You can render an email input field to the CrossmintPaymentElement by setting the emailInputOptions prop to { show: true }. If you collect email elsewhere in your application you can set recipient.email programmatically.

Render Input

  <CrossmintPaymentElement
    // removed for brevity
    emailInputOptions={{
      show: true,
    }}
    ...
  />

Example response

{
  "type": "payment:preparation.failed",
  "payload": {}
}

payment:process.started

Triggered when checkout is ready for payment.

Example response

{
  "type": "payment:process.started",
  "payload": {}
}

payment:process.succeeded

Triggered when payment has been successfully authorized.

(Payment capture occurs after transaction:fulfillment.succeeded)

Example response

{
  "type": "payment:process.succeeded",
  "payload": {
    "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b"
  }
}

The orderIdentifier returned in the response is used to subscribe to minting events.

payment:process.rejected

Triggered if a user’s card has been rejected.

Example response

{
  "type": "payment:process.rejected",
  "payload": {
    "error": {
      "code": "payments:payment-rejected.generic-decline",
      "message": "The card was declined for an unknown reason."
    },
    "orderIdentifier": "3b8860e5-837b-44c5-99be-17f3f19238f6",
    "paymentMethodType": "credit-card"
  }
}

You can trigger this event using the high risk test card number: 4000 0000 0000 4954

payment:process.cancelled

Triggered if a user cancelled the payment or closed the checkout.

Minting events are triggered only after a payment has been successful captured. They notify of the status of the NFT mint and delivery (e.g. beginning the minting process, delivering the token to the user).

Adding Minting events

Minting events are not sent to the onEvent handler of the CrossmintPaymentElement. Instead, you must set them up using the code below

How to subscribe to minting events

You can subscribe by passing the orderIdentifier returned in the payment:process.succeedded event to the Minting component below.

Crossmint.tsx

"use client";

import React, { useState } from 'react';
import { CrossmintPaymentElement } from "@crossmint/client-sdk-react-ui";
import Minting from './Minting';

const Crossmint: React.FC = () => {
  const [orderIdentifier, setOrderIdentifier] = useState<string | null>(null);

  const projectId = process.env.NEXT_PUBLIC_CROSSMINT_PROJECT_ID as string;
  const collectionId = process.env.NEXT_PUBLIC_CROSSMINT_COLLECTION_ID as string;
  const environment = process.env.NEXT_PUBLIC_CROSSMINT_ENVIRONMENT as string;

  return (
    <>
      {orderIdentifier === null ? (
        <CrossmintPaymentElement
          projectId={projectId}
          collectionId={collectionId}
          environment={environment}
          emailInputOptions={{
            show: true,
          }}
          mintConfig={{
            totalPrice: "0.001",
            quantity: "1"
          }}
          onEvent={(event) => {
            switch (event.type) {
              case "payment:process.succeeded":
                console.log(event);
                setOrderIdentifier(event.payload.orderIdentifier);
                break;
              default:
                console.log(event);
                break;
            }
          }}
        />
      ) : (
        <Minting orderIdentifier={orderIdentifier} />
      )}
    </>
  );
}

export default Crossmint;

Types of Minting Events

Orders

order:process.started

Triggered when payment has been successfully authorized and the minting process has started.

Example response

{
  "type": "order:process.started",
  "payload": {}
}

order:process.finished

Triggered when all transactions have succeeded.

This event fires after the transaction:fulfillment.succeeded event.

Example response

{
  "type": "order:process.finished",
  "payload": {
    "successfulTransactionIdentifiers": [
      "601b06a9-e4af-423d-8db0-89eb7a457772"
    ],
    "failedTransactionIdentifiers": [],
    "totalPrice": {
      "amount": "0.50",
      "currency": "usd"
    },
    "verification": {
      "required": false
    },
    "paymentMethodType": "credit-card"
  }
}

Transactions

transaction:fulfillment.succeeded

Triggered when an NFT has been delivered successfully.

This event is returned after the blockchain transaction has been confirmed. It will not return immeditately after sending to RPC. This ensures the txId in the response will be valid.

Example response

{
  "type": "transaction:fulfillment.succeeded",
  "payload": {
    "transactionIdentifier": "601b06a9-e4af-423d-8db0-89eb7a457772",
    "txId": "0x2e69f11dae7869b92e3d5eaf4cadd50c48b5c6803d1232815f979d744521ad4c",
    "contractAddress": "0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA",
    "tokenIds": [
      "3"
    ],
    "price": {
      "amount": "0.50",
      "currency": "usd"
    }
  }
}

transaction:fulfillment.failed

Triggered when minting the NFT fails.

There is not a reliable way for you to trigger this event in testing.

One scenario when this may fire is if the last NFT is sold between the time payment is sent and Crossmint attempts to make the purchase.

Example response

{
  "type": "transaction:fulfillment.failed",
  "payload": {}
}

Errors

payments:mint-config.invalid

Error parsing parameter mintConfig.

How to solve

The value of the mintConfig must be an object type. Ensure you are passing in a valid object.

payments:payment-method.invalid

The param paymentMethod must be a string

How to solve

paymentMethod only accepts a string value. Ensure that you are passing in a string containing one of these possible values: “fiat”, “ETH, or “SOL”.

payments:email.invalid

The email value passed into the recipient.email property is invalid.

How to solve

Ensure that a valid email address is being passed.

payments:client-id.invalid

The provided collectionId does not exist.

How to solve

Ensure that you are using the correct collectionId. Common causes for this error include:

• using the wrong environment
  e.g. environment="staging" with a production collectionId or vice versa
• using the projectId instead of the collectionId

payments:minting-contract.missing

The collection associated with the provided collectionId does not have a minting contract registered.

How to solve

Register a smart contract in the developer console.