@unifold/core 0.1.67 → 0.1.68-beta.1

package/dist/index.d.mts

@@ -108,9 +108,9 @@ declare enum ExecutionStatus {
 }
 interface IconUrl {
     url: string;
-    format: "svg" | "png";
+    format: 'svg' | 'png';
 }
-type ProductType = "deposit" | "payment";
+type ProductType = 'deposit' | 'payment';
 interface DirectExecutionResponse {
     id: string;
     project_id: string;
@@ -277,7 +277,7 @@ declare function getTokenMetadata(request: GetTokenMetadataRequest, publishableK
  * @param preferredFormat - Preferred format ("svg" or "png"), defaults to "svg"
  * @returns The URL string for the preferred format, or first available if preferred not found
  */
-declare function getPreferredIconUrl(iconUrls: IconUrl[] | undefined, preferredFormat?: "svg" | "png"): string | undefined;
+declare function getPreferredIconUrl(iconUrls: IconUrl[] | undefined, preferredFormat?: 'svg' | 'png'): string | undefined;
 interface FiatCurrency {
     currency_code: string;
     name: string;
@@ -340,6 +340,14 @@ interface OnrampQuotesResponse {
  * @param publishableKey - Optional publishable key, defaults to configured key
  */
 declare function getOnrampQuotes(request: OnrampQuotesRequest, publishableKey?: string): Promise<OnrampQuotesResponse>;
+/**
+ * Payment method for an onramp session. Defaults to `card` server-side.
+ * `sepa` routes the session through SEPA bank transfer (Swapped-only today).
+ * `apple_pay` preselects Apple Pay on Coinbase's standard onramp surface
+ * (Coinbase only) — useful as a fallback when the headless Apple Pay flow
+ * is unavailable.
+ */
+type OnrampSessionPaymentMethod = 'card' | 'sepa' | 'apple_pay';
 interface OnrampSessionRequest {
     service_provider: string;
     country_code: string;
@@ -352,6 +360,7 @@ interface OnrampSessionRequest {
     redirect_url?: string;
     external_id?: string;
     email?: string;
+    payment_method?: OnrampSessionPaymentMethod;
 }
 interface OnrampSessionResponse {
     url: string;
@@ -363,6 +372,73 @@ interface OnrampSessionResponse {
  * @param publishableKey - Optional publishable key, defaults to configured key
  */
 declare function createOnrampSession(request: OnrampSessionRequest, publishableKey?: string): Promise<OnrampSessionResponse>;
+/**
+ * A bank-transfer onramp provider returned by `getBankTransferProviders()`.
+ * Mirrors the shape of `IntegrationExchangeInfo` so SDK consumers can render
+ * exchanges + bank-transfer with the same UI primitives.
+ */
+interface BankTransferProvider {
+    service_provider: string;
+    service_provider_display_name: string;
+    description: string;
+    icon_url: string;
+    icon_urls: IconUrl[];
+    /**
+     * True when the provider is configured AND the rail supports the caller's
+     * country. Use this to decide whether the row is clickable.
+     */
+    enabled: boolean;
+    /**
+     * Payment methods this provider supports. Forward one of these as
+     * `payment_method` when calling `/onramps/sessions`. Stored as an array so
+     * a single provider can light up multiple rails (e.g. SEPA + ACH) without
+     * forking the row.
+     */
+    payment_methods: OnrampSessionPaymentMethod[];
+    /** All fiat currencies the rail accepts (e.g. ['eur', 'gbp']). */
+    supported_currencies: string[];
+    /**
+     * Preferred fiat for the caller's country, picked from `supported_currencies`.
+     * Forward as `source_currency` to `/onramps/sessions` — avoids the SDK
+     * re-implementing the country → fiat mapping.
+     */
+    source_currency: string;
+}
+interface BankTransferProvidersResponse {
+    data: BankTransferProvider[];
+}
+interface GetBankTransferProvidersOptions {
+    /** ISO 3166-1 alpha-2 country code. Drives the `enabled` flag per provider. */
+    countryCode?: string;
+}
+/**
+ * Get supported bank-transfer onramp providers (SEPA via Swapped today).
+ * Each provider's `enabled` flag reflects project config + native integration
+ * availability + the caller-supplied country.
+ */
+declare function getBankTransferProviders(publishableKey?: string, options?: GetBankTransferProvidersOptions): Promise<BankTransferProvidersResponse>;
+interface ApplePayProvider {
+    service_provider: string;
+    service_provider_display_name: string;
+    description: string;
+    icon_url: string;
+    icon_urls: Array<{
+        url: string;
+        format: string;
+    }>;
+    enabled: boolean;
+    payment_methods: string[];
+    supported_countries: string[];
+}
+interface ApplePayProvidersResponse {
+    data: ApplePayProvider[];
+}
+/**
+ * Get supported Apple Pay onramp providers. The response is geo-restricted:
+ * only returns providers when the caller IP is in a supported region (US
+ * excluding NY for Coinbase) and the project has Apple Pay enabled.
+ */
+declare function getApplePayProviders(publishableKey?: string): Promise<ApplePayProvidersResponse>;
 /**
  * Generate a URL for the sessions/start endpoint that redirects to the onramp provider.
  * This is useful for avoiding popup blockers by opening the URL directly via anchor tag.
@@ -454,6 +530,7 @@ interface FeaturedWallet {
     icon_urls: IconUrl[];
 }
 interface ProjectConfigResponse {
+    project_id?: string;
     project_name?: string;
     asset_cdn_url: string;
     transfer_crypto: {
@@ -475,24 +552,58 @@ interface ProjectConfigResponse {
     cash_app?: {
         enabled: boolean;
     };
+    apple_pay?: {
+        enabled: boolean;
+    };
     pay_with_exchange?: {
         enabled: boolean;
     };
     fiat_onramp?: {
+        /** Developer/merchant-controlled toggle (dashboard + SDK prop). */
         enabled: boolean;
+        /**
+         * Platform-controlled hard hide, independent of `enabled`. Defaults to
+         * false. When true, the fiat on-ramp must be hidden regardless of `enabled`
+         * or the SDK prop.
+         */
+        is_hidden?: boolean;
     };
     deposit_tracker?: {
         enabled: boolean;
     };
+    bank_transfer?: BankTransferConfig;
     hypercore_sponsorship?: {
         enabled: boolean;
     };
 }
+/**
+ * Bank-transfer project-level toggle returned by `/projects/config`.
+ *
+ * Only reflects the dashboard preference — the actual rails available for
+ * a given country live under `getBankTransferProviders()`.
+ */
+interface BankTransferConfig {
+    enabled: boolean;
+}
 /**
  * Get project configuration
  * @param publishableKey - Optional publishable key, defaults to configured key
  */
-declare function getProjectConfig(publishableKey?: string): Promise<ProjectConfigResponse>;
+/**
+ * Optional caller-location hints for {@link getProjectConfig}.
+ *
+ * When `countryCode` is provided it is sent to the API, which uses it for
+ * region-based settings (e.g. whether the fiat on-ramp is hidden) and skips
+ * server-side IP geolocation. Omit to let the backend resolve the region from
+ * the request IP.
+ */
+interface GetProjectConfigOptions {
+    /** ISO 3166-1 alpha-2 country code (e.g. "US"). */
+    countryCode?: string;
+    /** ISO 3166-2 subdivision code (e.g. "CA"). */
+    subdivisionCode?: string;
+}
+declare function getProjectConfig(publishableKey?: string, options?: GetProjectConfigOptions): Promise<ProjectConfigResponse>;
 interface IpAddressResponse {
     alpha2: string;
     alpha3: string;
@@ -552,9 +663,9 @@ interface AddressBalancesResponse {
  */
 declare function getAddressBalances(address: string, chainType: ChainType, publishableKey?: string): Promise<AddressBalancesResponse>;
 /** Wallet ids supported by the connect-wallet flow. */
-type WalletMobileDeepLinkWallet = "phantom" | "metamask" | "coinbase" | "trust" | "rainbow" | "rabby" | "okx";
+type WalletMobileDeepLinkWallet = 'phantom' | 'metamask' | 'coinbase' | 'trust' | 'rainbow' | 'rabby' | 'okx';
 /** Chain types an external wallet can connect on. */
-type ExternalWalletChainType = "ethereum" | "solana";
+type ExternalWalletChainType = 'ethereum' | 'solana';
 /** A supported external (self-custody) wallet from the directory endpoint. */
 interface ExternalWalletInfo {
     id: WalletMobileDeepLinkWallet;
@@ -564,7 +675,7 @@ interface ExternalWalletInfo {
     icon_url: string;
     icon_urls: Array<{
         url: string;
-        format: "svg" | "png";
+        format: 'svg' | 'png';
     }>;
     /** Whether the wallet can be opened into its in-app browser on mobile. */
     supports_mobile_browse: boolean;
@@ -573,7 +684,7 @@ interface ExternalWalletInfo {
      * `null` means all platforms; an explicit list (e.g. `["ios"]`) tells the
      * client to only offer mobile-browse on those platforms.
      */
-    mobile_browse_platforms: ("ios" | "android")[] | null;
+    mobile_browse_platforms: ('ios' | 'android')[] | null;
 }
 interface ExternalWalletsResponse {
     data: ExternalWalletInfo[];
@@ -794,9 +905,9 @@ interface IntegrationAccount {
     icon_urls: IconUrl[];
 }
 type AuthenticateOAuthResult = {
-    status: "pending";
+    status: 'pending';
 } | {
-    status: "completed";
+    status: 'completed';
     accounts: IntegrationAccount[];
     access_token: string;
     expires_at: string;
@@ -931,13 +1042,13 @@ interface PaymentIntentDepositAddress {
  * this vocabulary; the `awaiting_refund` / `refunding` / `refunded` /
  * `refund_failed` states are only reachable for `type === 'locked_quote'` in v1.
  */
-type PaymentIntentStatus = "requires_payment" | "processing" | "succeeded" | "canceled" | "expired" | "awaiting_refund" | "refunding" | "refunded" | "refund_failed";
+type PaymentIntentStatus = 'requires_payment' | 'processing' | 'succeeded' | 'canceled' | 'expired' | 'awaiting_refund' | 'refunding' | 'refunded' | 'refund_failed';
 /**
  * Product mode of a payment intent. `default` is the standard PI flow.
  * `locked_quote` adds time-boxed rate locking, source-side amount tracking,
  * an expiration timer, and a refund flow. Same row, different mode.
  */
-type PaymentIntentType = "default" | "locked_quote";
+type PaymentIntentType = 'default' | 'locked_quote';
 interface PaymentIntent {
     id: string;
     /** Discriminator — `default` for the standard flow, `locked_quote` for rate-locked. */
@@ -1258,7 +1369,350 @@ interface CashAppLimits {
 declare function getCashAppLimits(currency?: string, publishableKey?: string): Promise<CashAppLimits>;
 declare function createCashAppSession(request: CashAppSessionRequest, publishableKey?: string): Promise<CashAppSessionResponse>;
 declare function getCashAppSessionStatus(externalId: string, publishableKey?: string): Promise<CashAppSessionStatusResponse>;
+interface StripeConfigResponse {
+    publishable_key: string;
+    merchant_identifier: string | null;
+}
+interface StripeAuthIntentResponse {
+    auth_intent_id: string;
+    expires_at: number;
+}
+interface StripeAccessTokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    /** Stripe sometimes nests the refresh token here instead of top-level */
+    refresh?: {
+        refresh_token: string;
+        expires_in: number;
+    };
+}
+interface StripeCustomerVerification {
+    name: string;
+    status: 'not_started' | 'pending' | 'rejected' | 'verified';
+    errors: string[];
+}
+interface StripeCryptoCustomer {
+    id: string;
+    object: string;
+    provided_fields: string[];
+    verifications: StripeCustomerVerification[];
+}
+interface StripeConsumerWallet {
+    id: string;
+    livemode: boolean;
+    network: string;
+    wallet_address: string;
+    chain_type?: string;
+    chain_id?: string;
+}
+interface StripePaymentToken {
+    id: string;
+    type: 'card' | 'us_bank_account';
+    card?: {
+        brand?: string;
+        last4?: string;
+        exp_month?: number;
+        exp_year?: number;
+        funding: string;
+        wallet?: {
+            type: string;
+        };
+    };
+    us_bank_account?: {
+        account_type?: string;
+        last4?: string;
+        bank_name?: string;
+    };
+}
+interface StripeListResponse<T> {
+    data: T[];
+    has_more: boolean;
+}
+interface StripeCreateSessionRequest {
+    cryptoCustomerId: string;
+    paymentToken: string;
+    sourceAmount: number;
+    sourceCurrency: string;
+    destinationCurrency: string;
+    destinationNetwork: string;
+    walletAddress: string;
+}
+interface StripeOnrampTransactionDetails {
+    wallet_address?: string;
+    wallet_addresses?: Record<string, string> | null;
+    source_amount?: string;
+    source_currency?: string;
+    destination_amount?: string;
+    destination_currency?: string;
+    destination_network?: string;
+    fees?: {
+        network_fee_amount?: string;
+        transaction_fee_amount?: string;
+    };
+    quote_expiration?: number;
+    transaction_id?: string | null;
+    last_error?: string | null;
+}
+interface StripeOnrampSession {
+    id: string;
+    object: string;
+    status: string;
+    client_secret?: string;
+    crypto_customer_id?: string;
+    livemode?: boolean;
+    transaction_details?: StripeOnrampTransactionDetails;
+}
+interface StripeConfirmRequest {
+    mandateData?: Record<string, unknown>;
+}
+interface StripeDefaultTokenResponse {
+    destination_network: string;
+    destination_currency: string;
+    destination_token_metadata: {
+        icon_url?: string;
+        icon_urls?: Array<{
+            url: string;
+            format: string;
+        }>;
+        decimals?: number;
+        symbol: string;
+        name: string;
+        token_address: string;
+        chain_id: string;
+        chain_type: string;
+        chain_name: string;
+        chain?: {
+            icon_url?: string;
+            icon_urls?: Array<{
+                url: string;
+                format: string;
+            }>;
+            chain_id: string;
+            chain_name: string;
+            chain_type: string;
+        };
+    };
+    estimated_processing_time: number | null;
+}
+/**
+ * Get the default token for the Stripe headless onramp flow.
+ * Requires the user's destination token context (same params as the
+ * non-headless default_token endpoint).
+ */
+declare function stripeGetDefaultToken(params: {
+    tokenAddress: string;
+    chainId: string;
+    chainType: string;
+    countryCode?: string;
+}, publishableKey?: string): Promise<StripeDefaultTokenResponse>;
+interface StripeQuoteRequest {
+    sourceAmount: string;
+    sourceCurrency: string;
+    destinationCurrency: string;
+    destinationNetwork: string;
+}
+interface StripeQuotesResponse {
+    source_amount: number;
+    source_currency: string;
+    total_fee: number;
+    source_total_amount: number;
+    destination_amount: number;
+    destination_currency: string;
+    destination_network: string;
+    service_provider: string;
+    service_provider_display_name: string;
+    destination_network_quotes: Record<string, unknown[]>;
+}
+/**
+ * Backend error_type values for headless Stripe onramp failures. The SDK can
+ * branch on these instead of string-matching Stripe messages.
+ */
+type StripeOnrampErrorType = 'stripe_onramp_missing_minimum_identity_verification' | 'stripe_onramp_missing_identity_verification' | 'stripe_onramp_missing_document_verification' | 'stripe_onramp_purchase_limit_reached' | 'stripe_onramp_bad_request' | 'stripe_onramp_forbidden' | 'stripe_onramp_not_found' | 'stripe_onramp_upstream_error' | (string & NonNullable<unknown>);
+declare class StripeApiResponseError extends Error {
+    readonly statusCode: number;
+    /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
+    readonly stripeCode?: string | undefined;
+    /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
+    readonly errorType?: StripeOnrampErrorType | undefined;
+    constructor(message: string, statusCode: number, 
+    /** Underlying Stripe error code (e.g. `crypto_onramp_session_error`), when available */
+    stripeCode?: string | undefined, 
+    /** Unifold backend error_type (e.g. `stripe_onramp_missing_document_verification`) */
+    errorType?: StripeOnrampErrorType | undefined);
+}
+/**
+ * Fetch Stripe config (publishable key + merchant ID) for SDK initialization.
+ * The Stripe publishable key is stored server-side per project, so consumers
+ * don't need to pass it manually — this endpoint returns it.
+ */
+declare function stripeGetConfig(publishableKey?: string): Promise<StripeConfigResponse>;
+/**
+ * Create a LinkAuthIntent to start the Stripe Link OAuth flow.
+ * Only `email` is required — OAuth scopes are configured server-side.
+ */
+declare function stripeCreateAuthIntent(email: string, publishableKey?: string): Promise<StripeAuthIntentResponse>;
+/**
+ * Exchange a consented LinkAuthIntent for OAuth access tokens.
+ */
+declare function stripeExchangeTokens(authIntentId: string, publishableKey?: string): Promise<StripeAccessTokenResponse>;
+/**
+ * Refresh an expired OAuth access token.
+ */
+declare function stripeRefreshToken(refreshToken: string, publishableKey?: string): Promise<StripeAccessTokenResponse>;
+declare function stripeGetCustomer(customerId: string, oauthToken: string, publishableKey?: string): Promise<StripeCryptoCustomer>;
+/**
+ * List wallet addresses registered for a CryptoCustomer.
+ * Endpoint: GET /customers/:id/wallet_addresses
+ */
+declare function stripeListWallets(customerId: string, oauthToken: string, publishableKey?: string): Promise<StripeListResponse<StripeConsumerWallet>>;
+declare function stripeListPaymentTokens(customerId: string, oauthToken: string, publishableKey?: string): Promise<StripeListResponse<StripePaymentToken>>;
+/**
+ * Create a headless CryptoOnrampSession.
+ * Uses `walletAddress` (string) not `wallet_addresses` (object).
+ */
+declare function stripeCreateSession(request: StripeCreateSessionRequest, oauthToken: string, publishableKey?: string): Promise<StripeOnrampSession>;
+/**
+ * Confirm a CryptoOnrampSession to initiate payment.
+ * Endpoint: POST /sessions/:id/confirm (not /checkout)
+ */
+declare function stripeConfirmSession(sessionId: string, oauthToken: string, request?: StripeConfirmRequest, publishableKey?: string): Promise<StripeOnrampSession>;
+declare function stripeRefreshQuote(sessionId: string, oauthToken: string, publishableKey?: string): Promise<StripeOnrampSession>;
+/**
+ * Retrieve a CryptoOnrampSession by ID.
+ */
+declare function stripeGetSession(sessionId: string, oauthToken: string, publishableKey?: string): Promise<StripeOnrampSession>;
+/**
+ * Get onramp quotes from Stripe — returns quotes grouped by network
+ * with destination amounts, fees, and totals.
+ */
+/**
+ * Get onramp quotes from Stripe. Same shape as the unified onramp quotes
+ * (sourceAmount, sourceCurrency, destinationCurrency, destinationNetwork).
+ * OAuth token is optional — without it, returns indicative pricing.
+ */
+declare function stripeGetQuotes(request: StripeQuoteRequest, oauthToken?: string, publishableKey?: string): Promise<StripeQuotesResponse>;
+interface StripeTransactionLimitEntry {
+    limit: number;
+    settlement_speed: 'instant' | 'standard';
+}
+/** limits keyed by source currency → payment method → entries */
+interface StripeTransactionLimitsResponse {
+    object: string;
+    crypto_customer_id: string;
+    livemode: boolean;
+    limits: Record<string, Record<string, StripeTransactionLimitEntry[]>>;
+}
+/**
+ * Retrieve the customer's remaining onramp transaction limits.
+ * Use this to proactively detect when a desired amount exceeds the limit
+ * for the customer's current KYC tier before attempting to create a session.
+ */
+declare function stripeGetTransactionLimits(params: {
+    cryptoCustomerId: string;
+    destinationNetwork: string;
+    walletAddress: string;
+    destinationTag?: string;
+    refresh?: boolean;
+}, oauthToken: string, publishableKey?: string): Promise<StripeTransactionLimitsResponse>;
 declare function sendHypercoreTransaction(request: SendHypercoreTransactionRequest, publishableKey?: string): Promise<SendHypercoreTransactionResponse>;
+interface CoinbaseLegalAgreement {
+    key: string;
+    name: string;
+    url: string;
+}
+interface CoinbaseLegalAgreementsResponse {
+    agreements: CoinbaseLegalAgreement[];
+    /** Disclosure copy; `{{links}}` is replaced with the joined agreement links. */
+    disclosure: string;
+}
+/** Coinbase Guest Checkout ToS / User Agreement / Privacy URLs. Safe to cache. */
+declare function getCoinbaseLegalAgreements(publishableKey?: string): Promise<CoinbaseLegalAgreementsResponse>;
+type OnrampVerificationFactorStatus = 'unverified' | 'verified';
+interface OnrampVerificationFactor {
+    status: OnrampVerificationFactorStatus;
+    verified_at?: string;
+}
+type OnrampVerificationStatus = 'requires_input' | 'verified' | 'expired' | 'canceled';
+interface OnrampVerificationSession {
+    id: string;
+    object: 'onramp.verification_session';
+    status: OnrampVerificationStatus;
+    /** Returned ONLY on creation. Required on all subsequent actions. */
+    client_secret?: string;
+    email: OnrampVerificationFactor;
+    phone: OnrampVerificationFactor;
+    expires_at: string;
+}
+interface CreateOnrampVerificationSessionRequest {
+    email: string;
+    /** US phone in E.164 (e.g. +12345678901). */
+    phone: string;
+    terms_accepted: boolean;
+    /** Skip email OTP when the caller has verified the address out-of-band. Phone OTP is never skippable. */
+    email_already_verified?: boolean;
+    /** Optional correlation id for a planned order. */
+    external_id?: string;
+}
+interface OnrampVerificationTokenResponse {
+    token: string;
+    token_type: 'Bearer';
+    /** Token lifetime in seconds. */
+    expires_in: number;
+}
+declare function createOnrampVerificationSession(request: CreateOnrampVerificationSessionRequest, publishableKey?: string): Promise<OnrampVerificationSession>;
+declare function sendOnrampVerificationOtp(id: string, factor: 'email' | 'phone', clientSecret: string, publishableKey?: string): Promise<OnrampVerificationSession>;
+declare function verifyOnrampVerificationOtp(id: string, factor: 'email' | 'phone', clientSecret: string, code: string, publishableKey?: string): Promise<OnrampVerificationSession>;
+declare function exchangeOnrampVerificationToken(id: string, clientSecret: string, publishableKey?: string): Promise<OnrampVerificationTokenResponse>;
+declare function getOnrampVerificationSession(id: string, clientSecret: string, publishableKey?: string): Promise<OnrampVerificationSession>;
+interface CreateCoinbaseApplePaySessionRequest {
+    source_currency: string;
+    /** Mutually exclusive with destination_amount. */
+    source_amount?: string;
+    /** Mutually exclusive with source_amount. */
+    destination_amount?: string;
+    destination_currency: string;
+    destination_network: string;
+    wallet_address: string;
+    /** Optional override; defaults to the verified email on the onramp token. */
+    email?: string;
+    /** Auto-generated when omitted. */
+    external_id?: string;
+    /**
+     * Iframe-embedding origin (CDP-registered + Apple-verified by the merchant).
+     * Reserved for a future iframe checkout — the SDK currently opens the payment
+     * surface in a popup window and ignores this field on the server. Accepted
+     * now so partners can pass it without an SDK upgrade later.
+     */
+    domain?: string;
+}
+interface CoinbaseApplePaySessionResponse {
+    id: string;
+    external_id: string;
+    /** URL to load in a webview/iframe — renders the Apple Pay button. */
+    url: string;
+    service_provider: string;
+    status: string;
+    wallet_address: string;
+    source_currency: string;
+    source_amount: string;
+    destination_currency: string;
+    destination_network: string;
+    destination_amount?: string;
+    total_fee?: number;
+}
+/**
+ * Create an Apple Pay onramp session. Requires a fresh `onrampToken` from
+ * `exchangeOnrampVerificationToken`.
+ *
+ * Pass `signal` from an `AbortController` when calling from a debounced /
+ * race-prone code path (e.g. the amount-screen create-on-input loop) so a
+ * superseded in-flight request can be cancelled and its response can't
+ * overwrite a newer one.
+ */
+declare function createCoinbaseApplePaySession(request: CreateCoinbaseApplePaySessionRequest, onrampToken: string, publishableKey?: string, signal?: AbortSignal): Promise<CoinbaseApplePaySessionResponse>;
 
 /**
  * Format a stablecoin amount to 2 decimal places, ceiling any fractional
@@ -1296,12 +1750,51 @@ declare enum DepositEventType {
 declare enum WithdrawEventType {
     DIRECT_EXECUTION_SUCCEEDED = "direct_execution.succeeded"
 }
+/** Event types emitted by the checkout flow. */
+declare enum CheckoutEventType {
+    PAYMENT_INTENT_SUCCEEDED = "payment_intent.succeeded"
+}
 /** Funding method used by a deposit flow. */
-type DepositMethod = "transfer" | "card" | "cashapp" | "pay_with_exchange" | "exchange_connect" | "wallet_connect";
+type DepositMethod = 'transfer' | 'card' | 'cashapp' | 'apple_pay' | 'pay_with_exchange' | 'exchange_connect' | 'wallet_connect';
+/** Funding method used by a checkout flow. */
+type CheckoutMethod = 'transfer' | 'wallet_connect';
 /** `data.object` payload for {@link DepositEventType.ONRAMP_SESSION_CREATED} */
 interface OnrampSessionCreatedData {
     externalId: string;
 }
+/**
+ * Callback-facing payment intent object.
+ * Mirrors the field-naming conventions used by {@link DirectExecution}
+ * (camelCase, `BaseUnit` / `Usd` amount suffixes, `failureReason`, no currency
+ * code or decimals — derive those from `*TokenAddress` if needed).
+ */
+interface CheckoutPaymentIntent {
+    id: string;
+    status: 'succeeded';
+    recipientAddress: string;
+    destinationChainType: string;
+    destinationChainId: string;
+    destinationTokenAddress: string;
+    destinationAmountBaseUnit: string;
+    destinationAmountUsd: string;
+    destinationAmountReceivedBaseUnit: string;
+    destinationAmountReceivedUsd: string;
+    sourceChainType: string | null;
+    sourceChainId: string | null;
+    sourceTokenAddress: string | null;
+    sourceAmountBaseUnit: string | null;
+    sourceAmountUsd: string | null;
+    sourceAmountReceivedBaseUnit: string | null;
+    sourceAmountReceivedUsd: string | null;
+    /** Atomic payout (pool → recipient) hash. Locked-quote only; null until broadcast. */
+    transactionHash: string | null;
+    failureReason: string | null;
+}
+/**
+ * `data.object` payload for {@link CheckoutEventType.PAYMENT_INTENT_SUCCEEDED}.
+ * @deprecated Use {@link CheckoutPaymentIntent} — kept as an alias for back-compat.
+ */
+type CheckoutPaymentIntentData = CheckoutPaymentIntent;
 /**
  * Callback-facing direct execution object.
  * Intentionally separate from legacy `DirectExecutionResponse` naming.
@@ -1334,6 +1827,10 @@ interface DepositEventDataMap {
 interface WithdrawEventDataMap {
     [WithdrawEventType.DIRECT_EXECUTION_SUCCEEDED]: DirectExecution;
 }
+/** Map from event type to its `data.object` shape */
+interface CheckoutEventDataMap {
+    [CheckoutEventType.PAYMENT_INTENT_SUCCEEDED]: CheckoutPaymentIntent;
+}
 /**
  * Event envelope emitted by the deposit flow, inspired by the server-side
  * webhook payload shape: top-level metadata (`id`, `type`, `created`) with
@@ -1370,6 +1867,18 @@ type WithdrawEvent = {
         };
     };
 }[WithdrawEventType];
+/** Event envelope emitted by the checkout flow. */
+type CheckoutEvent = {
+    [K in CheckoutEventType]: {
+        id: string;
+        type: K;
+        created: number;
+        method?: CheckoutMethod;
+        data: {
+            object: CheckoutEventDataMap[K];
+        };
+    };
+}[CheckoutEventType];
 /** Convenience type for a fully-typed `onramp_session.created` event */
 type OnrampSessionCreatedEvent = Extract<DepositEvent, {
     type: DepositEventType.ONRAMP_SESSION_CREATED;
@@ -1385,6 +1894,10 @@ type DirectExecutionSucceededEvent = Extract<DepositEvent, {
 type WithdrawDirectExecutionSucceededEvent = Extract<WithdrawEvent, {
     type: WithdrawEventType.DIRECT_EXECUTION_SUCCEEDED;
 }>;
+/** Convenience type for a fully-typed `payment_intent.succeeded` checkout event */
+type CheckoutPaymentIntentSucceededEvent = Extract<CheckoutEvent, {
+    type: CheckoutEventType.PAYMENT_INTENT_SUCCEEDED;
+}>;
 
 /**
  * User IP information interface
@@ -1508,4 +2021,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type ConfirmIntegrationTransferResult, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionRequest, type OnrampSessionResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type SupportedChain, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, type UserIpInfo, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getCashAppLimits, getCashAppSessionStatus, getChainName, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, listPaymentIntentExecutions, pollDirectExecutions, queryExecutions, refreshIntegrationToken, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, useUserIp, verifyRecipientAddress };
+export { ActionType, type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type ApplePayProvider, type ApplePayProvidersResponse, type AuthenticateOAuthResult, type AutoSwapRequest, type AutoSwapResponse, type BankTransferConfig, type BankTransferProvider, type BankTransferProvidersResponse, type BlockedCountrySubdivision, type BuildHypercoreTransactionRequest, type BuildHypercoreTransactionResponse, type BuildSolanaTransactionRequest, type BuildSolanaTransactionResponse, type CashAppLimits, type CashAppSessionRequest, type CashAppSessionResponse, type CashAppSessionStatusResponse, type ChainType, type CheckoutEvent, CheckoutEventType, type CheckoutMethod, type CheckoutPaymentIntent, type CheckoutPaymentIntentData, type CheckoutPaymentIntentSucceededEvent, type CoinbaseApplePaySessionResponse, type CoinbaseLegalAgreement, type CoinbaseLegalAgreementsResponse, type ConfirmIntegrationTransferResult, type CreateCoinbaseApplePaySessionRequest, type CreateDepositAddressRequest, type CreateExchangeSessionRequest, type CreateExchangeSessionResponse, type CreateIntegrationTransferParams, type CreateIntegrationTransferResult, type CreateOnrampVerificationSessionRequest, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, type DepositEvent, DepositEventType, type DepositMethod, type DepositQuote, type DepositQuoteRequest, type DestinationToken, type DestinationTokenChain, type DirectExecution, type DirectExecutionResponse, type DirectExecutionSucceededEvent, type EvmContractCall, type ExchangeProviderInfo, type ExchangeProvidersResponse, type ExchangeSessionStartParams, type ExchangeWalletAddress, ExecutionStatus, type ExternalWalletChainType, type ExternalWalletInfo, type ExternalWalletsResponse, type FeaturedToken, type FeaturedWallet, type FiatCurrenciesResponse, type FiatCurrency, type GetBankTransferProvidersOptions, type GetExchangesQuery, type HypercoreActivationRequest, type HypercoreActivationResponse, type I18nStrings, type IconUrl, IneligibilityReason, type IntegrationAccount, type IntegrationExchangeInfo, type IntegrationExchangesResponse, type IntegrationFeeAmount, type IntegrationHoldingsResponse, IntegrationProvider, type IpAddressResponse, type LockedQuoteLimits, type LockedQuotePreview, type LockedQuotePreviewRequest, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionCreatedData, type OnrampSessionCreatedEvent, type OnrampSessionPaymentMethod, type OnrampSessionRequest, type OnrampSessionResponse, type OnrampVerificationFactor, type OnrampVerificationFactorStatus, type OnrampVerificationSession, type OnrampVerificationStatus, type OnrampVerificationTokenResponse, type PaymentIntent, type PaymentIntentDepositAddress, type PaymentIntentExecutionsResponse, type PaymentIntentStatus, type PaymentIntentType, type PaymentNetwork, type PollExecutionsRequest, type PollExecutionsResponse, type ProductType, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, type RefreshIntegrationTokenResult, SOLANA_USDC_ADDRESS, type SendHypercoreTransactionRequest, type SendHypercoreTransactionResponse, type SendSolanaTransactionRequest, type SendSolanaTransactionResponse, type SourceToken, type SourceTokenNetwork, type StartIntegrationOAuthResult, type StripeAccessTokenResponse, StripeApiResponseError, type StripeAuthIntentResponse, type StripeConfigResponse, type StripeConfirmRequest, type StripeConsumerWallet, type StripeCreateSessionRequest, type StripeCryptoCustomer, type StripeCustomerVerification, type StripeDefaultTokenResponse, type StripeListResponse, type StripeOnrampErrorType, type StripeOnrampSession, type StripeOnrampTransactionDetails, type StripePaymentToken, type StripeQuoteRequest, type StripeQuotesResponse, type StripeTransactionLimitEntry, type StripeTransactionLimitsResponse, type SupportedChain, type SupportedDepositTokensResponse, type SupportedDestinationTokensResponse, type SupportedSourceTokensQuery, type SupportedSourceTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenIconUrl, type TokenInfo, type TokenMetadata, type TransferDefaultTokenParams, type TransferDefaultTokenResult, type UserIpInfo, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, type WalletMobileDeepLinkDepositAddress, type WalletMobileDeepLinkResponse, type WalletMobileDeepLinkWallet, type WithdrawDirectExecutionSucceededEvent, type WithdrawEvent, WithdrawEventType, authenticateIntegrationOAuth, buildHypercoreTransaction, buildSolanaTransaction, checkHypercoreActivation, confirmIntegrationTransfer, createCashAppSession, createCoinbaseApplePaySession, createDepositAddress, createExchangeSession, createIntegrationTransfer, createOnrampSession, createOnrampVerificationSession, exchangeOnrampVerificationToken, formatStablecoinAmount, generateKSUID, generatePrefixedKSUID, getAddressBalance, getAddressBalances, getApiBaseUrl, getApplePayProviders, getBankTransferProviders, getCashAppLimits, getCashAppSessionStatus, getChainName, getCoinbaseLegalAgreements, getDefaultOnrampToken, getDepositAddress, getDepositQuote, getExchangeSessionStartUrl, getExchanges, getExternalWallets, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIntegrationExchanges, getIntegrationHoldings, getIntegrationTransferDefaultToken, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getOnrampVerificationSession, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getSupportedDestinationTokens, getTokenChains, getTokenMetadata, getWalletByChainType, getWalletMobileDeepLink, i18n, listPaymentIntentExecutions, pollDirectExecutions, queryExecutions, refreshIntegrationToken, retrievePaymentIntent, revokeIntegrationToken, sendHypercoreTransaction, sendOnrampVerificationOtp, sendSolanaTransaction, setApiConfig, startIntegrationOAuth, stripeConfirmSession, stripeCreateAuthIntent, stripeCreateSession, stripeExchangeTokens, stripeGetConfig, stripeGetCustomer, stripeGetDefaultToken, stripeGetQuotes, stripeGetSession, stripeGetTransactionLimits, stripeListPaymentTokens, stripeListWallets, stripeRefreshQuote, stripeRefreshToken, useUserIp, verifyOnrampVerificationOtp, verifyRecipientAddress };