submitCheckoutTransaction

submitCheckoutTransaction

Prepares, signs, and broadcasts a checkout transaction in one call. This is the recommended way to complete a checkout — it orchestrates the full submission flow:

1. Advances to signing state and confirms the quote is still valid.
2. Ensures the wallet is on the correct network for the transaction
3. Delegates on-chain signing to the wallet provider via executeSwapTransaction
4. Notifies the api that the transaction has been broadcasted, with the resulting transaction hash, so the api can begin confirmation/settlement processing.

Usage

import { submitCheckoutTransaction } from '@dynamic-labs-sdk/client';

const result = await submitCheckoutTransaction({
  transactionId: 'txn_abc123',
  walletAccount: connectedWallet,
  onStepChange: (step) => {
    console.log('Current step:', step);
  },
});

console.log('Transaction submitted:', result.txHash);

Parameters

Parameter	Type	Description
transactionId	string	The checkout transaction ID returned by createCheckoutTransaction.
walletAccount	WalletAccount	The connected wallet account to sign the transaction with.
onStepChange	(step: 'approval' | 'transaction') => void (optional)	Callback invoked when the signing step changes. 'approval' fires when an ERC-20 token allowance approval is needed; 'transaction' fires when the main transaction signing begins.

Returns

Promise<CheckoutTransaction> - The updated transaction object after broadcast.

Step Lifecycle

Step	Description
approval	The wallet is signing a token approval transaction (only for ERC-20 tokens when allowance is insufficient).
transaction	The wallet is signing the main swap/transfer transaction.

Examples

Basic submission

import {
  submitCheckoutTransaction,
  getWalletAccounts,
} from '@dynamic-labs-sdk/client';

const walletAccounts = getWalletAccounts();
const wallet = walletAccounts[0];

const result = await submitCheckoutTransaction({
  transactionId: 'txn_abc123',
  walletAccount: wallet,
});

console.log('Broadcast tx hash:', result.txHash);

With step progress UI

import { useState } from 'react';
import { submitCheckoutTransaction } from '@dynamic-labs-sdk/client';

const CheckoutButton = ({ transactionId, walletAccount, onComplete }) => {
  const [step, setStep] = useState(null);
  const [error, setError] = useState(null);

  const handleSubmit = async () => {
    try {
      const result = await submitCheckoutTransaction({
        transactionId,
        walletAccount,
        onStepChange: setStep,
      });
      onComplete(result);
    } catch (err) {
      setError(err.message);
    }
  };

  return (
    <div>
      <button onClick={handleSubmit} disabled={!!step}>
        {step === 'approval' && 'Approve in wallet...'}
        {step === 'transaction' && 'Sign in wallet...'}
        {!step && 'Pay Now'}
      </button>
      {error && <p className="error">{error}</p>}
    </div>
  );
};

This example uses React; the JavaScript SDK is framework-agnostic and can be used with any frontend or in Node.

Handle user rejection

If the user rejects the signing request in their wallet, the promise rejects with an error containing 'rejected':

import { submitCheckoutTransaction } from '@dynamic-labs-sdk/client';

try {
  await submitCheckoutTransaction({
    transactionId,
    walletAccount,
  });
} catch (error) {
  if (error.message.includes('rejected')) {
    console.log('User rejected the transaction');
    // Optionally cancel the transaction
  } else {
    console.error('Submission failed:', error.message);
  }
}

Related

• createCheckoutTransaction - Create a new checkout transaction
• getCheckoutTransactionQuote - Get a transaction quote
• cancelCheckoutTransaction - Cancel a pending transaction