Overview
Enable native Apple Pay onramp in your React Native app, allowing users to purchase crypto directly without leaving your app. This provides the fastest onramp experience available, with a fully native feel on iOS devices.Native Apple Pay onramp is currently available for US users only on iOS devices via the React Native SDK.
For web users, or to support other payment methods, see Cross-Platform Onramp.
Prerequisites
- A free CDP Portal account and project
- A React Native app using the CDP React Native SDK
- iOS development environment (Xcode 16.1+, iOS 15.1+)
- Users must be located in the United States with a valid US phone number
Testing and Production Access
User Verification Requirements
Apple Pay onramp requires users to have verified contact information:- Email verification: Users must have a verified email address
- SMS verification: Users must have a verified US phone number (a real mobile number, not VoIP).
useApplePay hook returns an error with a specific code when verification is required, allowing you to display the appropriate verification flow.
Integration
The React Native SDK provides three main components for Apple Pay integration:| Component | Description |
|---|---|
ApplePayProvider | Context provider that manages Apple Pay state and order creation |
ApplePayButton | Renders the Apple Pay payment WebView when an order is created |
useApplePay | Hook that provides order creation, payment status, and error handling |
Installation
Install the@coinbase/cdp-react-native package, along with its peer dependency on react-native-webview (tested on version 13.13.5):
Setup
Wrap your app or the relevant screen with theApplePayProvider:
Using the useApplePay Hook
TheuseApplePay hook provides access to order creation and payment status:
Hook Return Values
TheuseApplePay hook returns the following:
| Property | Type | Description |
|---|---|---|
createOrder | (options: CreateOrderOptions) => Promise<void> | Creates an Apple Pay onramp order |
data | EndUserApplePayOnrampOrderCreateResponse | undefined | The created order data, including the payment link |
status | 'idle' | 'pending' | 'error' | 'success' | Current status of the onramp flow |
error | OnrampError | undefined | Error details if status is 'error' |
reset | () => void | Resets the state back to 'idle' |
CreateOrderOptions
| Property | Type | Description |
|---|---|---|
destination.address | string | The blockchain address receiving the purchased crypto |
destination.network | Network | The blockchain network (e.g., 'base', 'ethereum') |
purchase.amount | string | The crypto amount to purchase, exclusive of fees (e.g., '10.00') |
purchase.currency | string | The cryptocurrency to purchase (e.g., 'usdc') |
payment.currency | string | The fiat currency for payment (e.g., 'usd') |
isSandbox | boolean | Set to true for sandbox testing (default: false) |
Error Codes
Whenstatus is 'error', check the error.code to determine the appropriate action:
| Error Code | Description | Action Required |
|---|---|---|
requires_email | User needs to verify their email | Display email verification UI |
requires_sms | User needs to verify their phone number | Display SMS verification UI |
user_not_authenticated | User is not logged in | Redirect to authentication flow |
api_error | API error occurred | Display error message and retry option |
Rendering the Apple Pay Button
TheApplePayButton component automatically reads the payment URL from the ApplePayProvider context and renders the Apple Pay WebView. It only renders when order data is available:
The
ApplePayButton returns null on non-iOS platforms. You should check Platform.OS === 'ios' and display an appropriate message for Android users.Handling Verification
When theuseApplePay hook returns an error indicating missing verification, guide users through the verification process. You can use the CDP hooks to handle email and SMS verification:
useLinkEmail- Link and verify an email addressuseLinkSms- Link and verify a phone number
Complete Example
Complete Example
Here’s a complete example showing the full Apple Pay onramp flow with verification handling:
Legal Requirements
Your users must accept Coinbase’s legal agreements before using Apple Pay onramp: Ensure your app clearly informs users that by proceeding with payment, they are agreeing to these policies.Reference Implementation
For a complete React Native reference implementation showcasing the Apple Pay integration with CDP Embedded Wallets, check out the example app on GitHub.What to read next
- React Native Quickstart: Get started with embedded wallets in React Native
- Apple Pay Onramp API: Learn about the underlying API and advanced configuration
- Cross-Platform Onramp: Explore other onramp options including the FundModal component