Checkout SDK Reference

If you haven't already you can go to NPM to install the Checkout Widget SDK!


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.
onPaymentSuccessStringCallBack triggered when full payment completed.
onErrorFunctionCallback triggered only when terminal errors happen.
optionsFunctionOptions for CircleCheckout component.


themeCircleCheckoutThemeConfigObject to customize the UI of the CircleCheckout component.
merchantNameStringMerchant name used for display purpose.
threeDsSuccessRedirectUrlStringA redirect url for 3ds success result.
threeDsFailureRedirectUrlStringA redirect url for 3ds failure result.

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


themeTypeString [Enum]Specify if you would like to use one of Circle’s preset themes.

Enum values are light || dark.
backgroundPrimaryStringPrimary background color for overall container.
backgroundSecondaryStringBackground color for cards
backgroundTertiaryStringBackground color
textPrimaryColorStringPrimary text color
textSecondaryColorStringSecondary text color
textTertiaryColorStringTertiary text color
borderPrimaryColorStringPrimary border color
borderRadiusStringBorder radius
buttonBackgroundPrimaryStringBackground color for buttons
loadingSpinnerColorStringLoad spinner color

ApplePay and GooglePay button and text color cannot be overwritten.



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.


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;