If you haven't already you can go to [NPM](🔗) to install the Checkout Widget SDK!

# Schemas

## Checkout Session

sessionIdStringXCheckout session ID as received from checkout sessions endpoint.
clientKeyStringXClient key as received from checkout session API.
environmentString [Enum]XThe desired environment. In sandbox, all crypto payments facilitated by a connected wallet will be on the blockchain’s testnet\*. \*Lobstr (via WalletConnect) on Stellar, as WalletConnect doesn’t support Stellar’s testnet Enum values are sandbox, production.
CallBack triggered when full payment completed.
Callback triggered only when terminal errors happen.
Options for CircleCheckout component.

## Options

Object to customize the UI of the CircleCheckout component.
Merchant name used for display purpose.
A redirect url for 3ds success result.
A redirect url for 3ds failure result.

Note: `threeDsSuccessRedirectUrl` and `threeDsFailureRedirectUrl` are **required** if 3DS is turned on through settings.

## CircleCheckoutThemeConfig

themeTypeString [Enum]
Specify if you would like to use one of Circle’s preset themes. Enum values are `light` \|\| `dark`.
Primary background color for overall container.
Background color for cards
Background color
Primary text color
Secondary text color
Tertiary text color
Primary border color
Border radius
Background color for buttons
Load spinner color

_ApplePay and GooglePay button and text color cannot be overwritten._

# Methods

## onPaymentSuccess

Callback is provided to let you know when a checkout session status is `completed`. You can take actions based on this to continue your customer journey.

onPaymentSuccess((result: { paymentId:string, paymentIntentId:string, redirectUrl: string, paymentMethodType: PaymentMethodType }) => void): method to be called after payment is completed:

  • `PaymentMethodType`: { ‘card’ | ‘apple_pay’ | ‘google_pay’ | ‘crypto }

  • `paymentId`: the fiat payment id associated with this completed checkout session. You can use this id to query fiat payment details.

  • `paymentIntentId`: the crypto paymentIntentId associated with this completed checkout session. You can use this id to query crypto payment details.

  • `redirectUrl`: the successUrl from checkoutSession creation.

## onError

We handle payment related errors like credit card validation, credit card decline, 3DS, crypto wallet with insufficient funds and more automatically so you don’t have to worry about it. Only if there are any terminal errors, the onError callback is triggered to let you know. By terminal error, it means errors that neither consumers nor Circle SDK can handle to recover from the failure status. You can determine next steps based on this information. It is recommended to reset the existing checkout flow or recreate a new checkoutSession under this case.

onError? (CircleCheckoutError) => void: method to be called if an error occurs during checkout

  • CircleCheckoutError: {type: CircleCheckoutErrorType, error?: Error}

    • CircleCheckoutErrorType:

      • CircleCheckoutErrorType.CircleAPIError

      • CircleCheckoutErrorType.CryptoPaymentFailed

      • CircleCheckoutErrorType.CheckoutSessionNotValid

    • Error:

      • name: string;

      • message: string;

      • stack?: string;