HomeCircle APIsStablecoinVerite
Open a Circle AccountGet an API Key

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

# Schemas

## Checkout Session

NameTypeRequiredDescription
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.
onPaymentSuccessString
CallBack triggered when full payment completed.
onErrorFunction
Callback triggered only when terminal errors happen.
optionsFunction
Options for CircleCheckout component.

## Options

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

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

## CircleCheckoutThemeConfig

NameTypeRequiredDescription
themeTypeString [Enum]
Specify if you would like to use one of Circle’s preset themes. Enum values are `light` \|\| `dark`.
backgroundPrimaryString
Primary background color for overall container.
backgroundSecondaryString
Background color for cards
backgroundTertiaryString
Background color
textPrimaryColorString
Primary text color
textSecondaryColorString
Secondary text color
textTertiaryColorString
Tertiary text color
borderPrimaryColorString
Primary border color
borderRadiusString
Border radius
buttonBackgroundPrimaryString
Background color for buttons
loadingSpinnerColorString
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;