createCoinbaseOnrampOrder

createCoinbaseOnrampOrder

Creates a Coinbase onramp order for purchasing cryptocurrency with fiat. This returns a payment link URL that you can display in an iframe within your app, providing an embedded purchase experience.

This function is typically used with addCoinbaseOnrampOrderEventListener to track the order status in real-time.

Usage

import {
  createCoinbaseOnrampOrder,
  addCoinbaseOnrampOrderEventListener,
} from "@dynamic-labs-sdk/client";

// Create the order
const order = await createCoinbaseOnrampOrder({
  agreementAcceptedAt: new Date(),
  destinationAddress: "0x1234...",
  destinationNetwork: "base",
  paymentCurrency: "USD",
  paymentMethod: "GUEST_CHECKOUT_APPLE_PAY",
  purchaseAmount: "100",
  purchaseCurrency: "USDC",
  isSandbox: true, // Use true for testing
});

// Display the payment link in an iframe
const iframe = document.createElement("iframe");
iframe.src = order.paymentLink.url;
document.body.appendChild(iframe);

// Listen for order events
const removeListener = addCoinbaseOnrampOrderEventListener({
  listener: (event) => {
    console.log("Event:", event.eventName, event.data);
  },
});

Parameters

Parameter	Type	Description
agreementAcceptedAt	Date	Timestamp when user accepted Coinbase’s terms.
destinationAddress	string	The wallet address to receive the crypto.
destinationNetwork	string	The network for the purchase (e.g., base, ethereum).
paymentCurrency	string	The fiat currency (e.g., USD, EUR).
paymentMethod	string	The payment method. Currently only GUEST_CHECKOUT_APPLE_PAY is supported.
purchaseAmount	string	The amount of crypto to purchase.
purchaseCurrency	string	The crypto to purchase (e.g., USDC, ETH).
isSandbox	boolean (optional)	Set to true for testing without real transactions.
client	DynamicClient (optional)	The Dynamic client instance. Only required when using multiple clients.

Returns

Promise<CoinbaseOnrampOrderResponse> - A promise that resolves to the created order, including:

type CoinbaseOnrampOrderResponse = {
  order: {
    orderId: string;
    status: string;
    destinationAddress: string;
    destinationNetwork: string;
    purchaseAmount: string;
    purchaseCurrency: string;
    paymentCurrency: string;
    paymentTotal: string;
    fees: Array<{ type: string; amount: string; currency: string }>;
    // ... and more
  };
  paymentLink?: {
    url: string; // Display this in an iframe
    paymentLinkType: string;
  };
};

Prerequisites

This function requires the user to have verified email and phone number. Use getMissingVerificationForCoinbaseOnrampOrder to check verification status before creating an order.

Complete Example

Here’s a full implementation showing how to create an order, display it in an iframe, and handle events:

import { useState, useRef, useEffect } from "react";
import {
  createCoinbaseOnrampOrder,
  addCoinbaseOnrampOrderEventListener,
  getMissingVerificationForCoinbaseOnrampOrder,
} from "@dynamic-labs-sdk/client";

const CoinbaseOnrampWidget = ({ walletAddress }) => {
  const [paymentUrl, setPaymentUrl] = useState(null);
  const [status, setStatus] = useState("idle");
  const removeListenerRef = useRef(null);

  const handleCreateOrder = async () => {
    // Check verification requirements first
    const missing = getMissingVerificationForCoinbaseOnrampOrder({
      paymentMethod: "GUEST_CHECKOUT_APPLE_PAY",
    });

    if (missing.length > 0) {
      alert("Please verify your email and phone number first");
      return;
    }

    setStatus("creating");

    try {
      const order = await createCoinbaseOnrampOrder({
        agreementAcceptedAt: new Date(),
        destinationAddress: walletAddress,
        destinationNetwork: "base",
        paymentCurrency: "USD",
        paymentMethod: "GUEST_CHECKOUT_APPLE_PAY",
        purchaseAmount: "100",
        purchaseCurrency: "USDC",
        isSandbox: true,
      });

      if (order.paymentLink?.url) {
        setPaymentUrl(order.paymentLink.url);
        setStatus("pending");

        // Start listening for events
        removeListenerRef.current = addCoinbaseOnrampOrderEventListener({
          listener: (event) => {
            switch (event.eventName) {
              case "onramp_api.cancel":
                setStatus("cancelled");
                setPaymentUrl(null);
                break;
              case "onramp_api.commit_success":
                setStatus("processing");
                break;
              case "onramp_api.commit_error":
                setStatus("error");
                console.error("Payment error:", event.data.errorMessage);
                break;
              case "onramp_api.polling_success":
                setStatus("completed");
                setPaymentUrl(null);
                break;
              case "onramp_api.polling_failed":
                setStatus("error");
                console.error("Transaction failed:", event.data.errorMessage);
                break;
            }
          },
        });
      }
    } catch (error) {
      setStatus("error");
      console.error("Failed to create order:", error);
    }
  };

  // Cleanup listener on unmount
  useEffect(() => {
    return () => {
      removeListenerRef.current?.();
    };
  }, []);

  if (paymentUrl) {
    return (
      <iframe
        src={paymentUrl}
        width="100%"
        height="500px"
        allow="payment"
        title="Coinbase Payment"
      />
    );
  }

  return (
    <div>
      <p>Status: {status}</p>
      <button onClick={handleCreateOrder} disabled={status === "creating"}>
        {status === "creating" ? "Creating order..." : "Buy Crypto"}
      </button>
    </div>
  );
};

Related functions

• addCoinbaseOnrampOrderEventListener - Listen for order events (required for embedded flow)
• getMissingVerificationForCoinbaseOnrampOrder - Check verification requirements
• getCoinbaseBuyUrl - Simpler redirect-based flow (no event tracking)