Skip to main content
This guide covers Coinbase’s Apple Pay Guest Checkout for purchases under $500 without KYC. For the default Coinbase onramp experience with full features, see Default Onramps and Customizing the Onramp Experience.
This guide is for JavaScript only.

​
Overview

Coinbase onramp integration allows users to purchase cryptocurrency directly within your application using Coinbase’s payment infrastructure. This integration supports Apple Pay Guest Checkout, enabling US users without a Coinbase account to deposit up to $500 per week.

​
Dashboard setup

To enable Coinbase onramp:
  1. Go to the Funding tab in your Dynamic developer dashboard
  2. Under “Fiat on-ramps”, toggle on Coinbase
  3. Accept any additional terms and conditions
  4. Save the settings

​
Coinbase-specific functions

The following functions are specific to Coinbase onramp and provide advanced control over the onramp flow.

​
createCoinbaseOnrampOrder

Creates a Coinbase onramp order programmatically. This function is useful when you want full control over the order creation process, such as for Apple Pay Guest Checkout.
See Coinbase’s create an onramp order documentation for reference.
Call getMissingVerificationForCoinbaseOnrampOrder before creating an order to check if any user data needs to be collected or verified. If required information is missing (like a verified phone number), the order will fail.
import { createCoinbaseOnrampOrder } from '@dynamic-labs-sdk/client'

const createOrder = async () => {
  const order = await createCoinbaseOnrampOrder({
    agreementAcceptedAt: new Date(),
    destinationAddress: '0x1234567890123456789012345678901234567890',
    destinationNetwork: 'base',
    paymentCurrency: 'USD',
    paymentMethod: 'GUEST_CHECKOUT_APPLE_PAY',
    purchaseCurrency: 'USDC',
    paymentAmount: '100.00',
    isSandbox: false,
  })

  // order.paymentLink.url contains the URL to redirect the user to
  // or you can embedded the url in an iframe
  if (order.paymentLink) {
    window.open(order.paymentLink.url, '_blank')
  }
}

​
Parameters

ParameterTypeRequiredDescription
agreementAcceptedAtDateYesTimestamp when user accepted Coinbase Terms, User Agreement, and Privacy Policy
destinationAddressstringYesWallet address where purchased crypto will be sent
destinationNetworkstringYesNetwork name (e.g., “base”, “ethereum”)
paymentCurrencystringYesFiat currency code (e.g., “USD”)
paymentMethodstringYesPayment method type (e.g., “GUEST_CHECKOUT_APPLE_PAY”)
purchaseCurrencystringYesCrypto ticker or Coinbase UUID (e.g., “USDC”, “ETH”)
paymentAmountstringNoFiat amount to pay (inclusive of fees)
purchaseAmountstringNoCrypto amount to receive (exclusive of fees)
isSandboxbooleanNoCreate a sandbox order for testing
partnerUserRefstringNoUnique user identifier for transaction linking
domainstringNoDomain for Apple Pay button rendering in iframes
isQuotebooleanNoReturn a quote without creating a transaction

​
Response

type CoinbaseOnrampOrderResponse = {
  order: {
    orderId: string
    status: CoinbaseOnrampOrderStatus
    destinationAddress: string
    destinationNetwork: string
    purchaseCurrency: string
    purchaseAmount: string
    paymentCurrency: string
    paymentSubtotal: string
    paymentTotal: string
    exchangeRate: string
    fees: CoinbaseOnrampFee[]
    createdAt: Date
    updatedAt: Date
    txHash?: string
    partnerUserRef?: string
    paymentMethod: CoinbaseOnrampOrderPaymentMethod
  }
  paymentLink?: {
    paymentLinkType: CoinbaseOnrampOrderPaymentLinkType
    url: string
  }
}

​
getMissingVerificationForCoinbaseOnrampOrder

Checks if the user has the required verified credentials (email and phone number) to create a Coinbase onramp order. This is useful for pre-validating users before attempting to create an order. 
import { getMissingVerificationForCoinbaseOnrampOrder } from '@dynamic-labs-sdk/client'

const checkUserVerification = () => {
  const missingFields = getMissingVerificationForCoinbaseOnrampOrder({
    paymentMethod: 'GUEST_CHECKOUT_APPLE_PAY',
  })

  if (missingFields.length > 0) {
    missingFields.forEach((field) => {
      if (field.errorCode === 'MISSING_INFORMATION') {
        console.log(`User needs to provide ${field.field}`)
      } else if (field.errorCode === 'MISSING_VERIFICATION') {
        console.log(`User needs to verify ${field.field}: ${field.data}`)
      } else if (field.errorCode === 'VERIFICATION_EXPIRED') {
        console.log(`User needs to re-verify ${field.field}: ${field.data}`)
      }
    })
  }

  return missingFields.length === 0
}

​
Error codes

Error CodeDescription
MISSING_INFORMATIONThe data still needs to be collected from the user
MISSING_VERIFICATIONThe data has been collected but not verified
VERIFICATION_EXPIREDThe data was verified but needs re-verification (phone numbers must be verified within the last 60 days)

​
addCoinbaseOnrampOrderEventListener

Listens to Coinbase onramp order events to track when an order is canceled, confirmed, completed, or fails. Use this after triggering an order to provide real-time feedback to users. 
import { 
  addCoinbaseOnrampOrderEventListener,
  createCoinbaseOnrampOrder 
} from '@dynamic-labs-sdk/client'

const createOrderWithListener = async () => {
  const order = await createCoinbaseOnrampOrder({
    agreementAcceptedAt: new Date(),
    destinationAddress: '0x1234567890123456789012345678901234567890',
    destinationNetwork: 'base',
    paymentCurrency: 'USD',
    paymentMethod: 'GUEST_CHECKOUT_APPLE_PAY',
    purchaseCurrency: 'USDC',
    paymentAmount: '100.00',
  })

  // Set up event listener after order is created
  const removeListener = addCoinbaseOnrampOrderEventListener({
    listener: (event) => {
      if (event.eventName === 'onramp_api.cancel') {
        console.log('Order was canceled')
      }

      if (event.eventName === 'onramp_api.commit_success') {
        console.log('Payment authorized successfully')
      }

      if (event.eventName === 'onramp_api.commit_error') {
        console.log(`Payment failed: ${event.data.errorMessage}`)
      }

      if (event.eventName === 'onramp_api.polling_success') {
        console.log('Transaction completed successfully')
      }

      if (event.eventName === 'onramp_api.polling_failed') {
        console.log(`Transaction failed: ${event.data.errorMessage}`)
      }
    },
  })

  // Clean up the listener when done
  // removeListener()
}

​
Event types

Event NameDescription
onramp_api.cancelUser canceled the order
onramp_api.commit_successPayment was authorized successfully, waiting for transaction to complete
onramp_api.commit_errorPayment authorization failed
onramp_api.polling_successTransaction completed successfully
onramp_api.polling_failedTransaction failed after authorization

​
Return value

The function returns a cleanup function that removes the event listener. Call this when you no longer need to listen for events (e.g., when the user closes the dialog or navigates away).

​
Order status values

StatusDescription
ONRAMP_ORDER_STATUS_CREATEDOrder has been created
ONRAMP_ORDER_STATUS_IN_PROGRESSOrder is being processed
ONRAMP_ORDER_STATUS_COMPLETEDOrder completed successfully
ONRAMP_ORDER_STATUS_FAILEDOrder failed
ONRAMP_ORDER_STATUS_CANCELLEDOrder was cancelled

​
Testing in sandbox

To test Coinbase onramp without real transactions:
  1. Set isSandbox: true when creating orders
  2. Or prefix your partnerUserRef with “sandbox-” (e.g., “sandbox-user-1234”)
When using sandbox mode with Apple Pay, the payment link URL will automatically include &useApplePaySandbox=true.

​
Requirements

For Apple Pay Guest Checkout, users must have:
  • A verified email address
  • A verified phone number (verified within the last 60 days)
Use getMissingVerificationForCoinbaseOnrampOrder to check these requirements before creating an order.

​
Collecting and verifying user credentials

Dynamic sends the phone number and email associated with the Dynamic user when creating an onramp order. You can use the following functions to collect and verify user credentials.

​
Collecting email and phone number

Use updateUser to store collected email or phone number in the user’s verified credentials. This function returns OTP verification details if verification is required. 
import { updateUser } from '@dynamic-labs-sdk/client'

// Update user email
const updateEmail = async () => {
  const otpVerification = await updateUser({
    userFields: {
      email: '[email protected]',
    },
  })

  if (otpVerification) {
    // Email verification required - use verifyOTP with the code sent to user
    console.log('Verification UUID:', otpVerification.verificationUUID)
  }
}

// Update user phone number
const updatePhone = async () => {
  const otpVerification = await updateUser({
    userFields: {
      phoneNumber: '5551234567',
      isoCountryCode: 'US',
    },
  })

  if (otpVerification) {
    // Phone verification required - use verifyOTP with the code sent to user
    console.log('Verification UUID:', otpVerification.verificationUUID)
  }
}

​
Verifying with OTP

After updating user credentials, use verifyOTP to complete the verification process with the code sent to the user. 
import { verifyOTP } from '@dynamic-labs-sdk/client'

const completeVerification = async (otpVerification, userEnteredCode) => {
  const response = await verifyOTP({
    otpVerification,
    verificationToken: userEnteredCode,
  })

  return response
}

​
Re-verifying expired phone numbers

Coinbase requires phone numbers to be verified within the last 60 days. If a user’s phone verification has expired, use sendSmsOTP to trigger re-verification, then complete with verifyOTP. 
import { sendSmsOTP, verifyOTP } from '@dynamic-labs-sdk/client'

const reverifyPhone = async () => {
  // Send new OTP to user's phone
  const otpVerification = await sendSmsOTP({
    isoCountryCode: 'US',
    phoneNumber: '5551234567',
  })

  // After user enters the code
  const userEnteredCode = '123456'
  await verifyOTP({
    otpVerification,
    verificationToken: userEnteredCode,
  })
}

​
Supported countries and payment methods

Coinbase onramp supports various countries and payment methods. The United States has the most comprehensive support, including Apple Pay for Guest Checkout. See the Customizing the Onramp Experience page for a complete list of supported countries and payment methods.