Coinbase Onramp (Apple Pay, No KYC)

Enable users to purchase up to $500 in cryptocurrency using Coinbase’s Apple Pay Guest Checkout without KYC

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

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

Parameter	Type	Required	Description
agreementAcceptedAt	Date	Yes	Timestamp when user accepted Coinbase Terms, User Agreement, and Privacy Policy
destinationAddress	string	Yes	Wallet address where purchased crypto will be sent
destinationNetwork	string	Yes	Network name (e.g., “base”, “ethereum”)
paymentCurrency	string	Yes	Fiat currency code (e.g., “USD”)
paymentMethod	string	Yes	Payment method type (e.g., “GUEST_CHECKOUT_APPLE_PAY”)
purchaseCurrency	string	Yes	Crypto ticker or Coinbase UUID (e.g., “USDC”, “ETH”)
paymentAmount	string	No	Fiat amount to pay (inclusive of fees)
purchaseAmount	string	No	Crypto amount to receive (exclusive of fees)
isSandbox	boolean	No	Create a sandbox order for testing
partnerUserRef	string	No	Unique user identifier for transaction linking
domain	string	No	Domain for Apple Pay button rendering in iframes
isQuote	boolean	No	Return 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 Code	Description
MISSING_INFORMATION	The data still needs to be collected from the user
MISSING_VERIFICATION	The data has been collected but not verified
VERIFICATION_EXPIRED	The 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 Name	Description
onramp_api.cancel	User canceled the order
onramp_api.commit_success	Payment was authorized successfully, waiting for transaction to complete
onramp_api.commit_error	Payment authorization failed
onramp_api.polling_success	Transaction completed successfully
onramp_api.polling_failed	Transaction 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

Status	Description
ONRAMP_ORDER_STATUS_CREATED	Order has been created
ONRAMP_ORDER_STATUS_IN_PROGRESS	Order is being processed
ONRAMP_ORDER_STATUS_COMPLETED	Order completed successfully
ONRAMP_ORDER_STATUS_FAILED	Order failed
ONRAMP_ORDER_STATUS_CANCELLED	Order 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: '[e-mail]',
    },
  })

  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.

Related

• Default Onramps - General onramp setup
• Customizing the Onramp Experience - Customize onramp options