Accept an iDEAL payment
Learn how to accept iDEAL, a common payment method in the Netherlands.
Caution
We recommend that you follow the Accept a payment guide unless you need to use manual server-side confirmation, or your integration requires presenting payment methods separately. If you’ve already integrated with Elements, see the Payment Element migration guide.
Accepting iDEAL in your app consists of displaying a webview that sends your customer to their bank’s online portal to authorise the payment. Your customer then returns to your app and you’re immediately notified about whether the payment succeeded or failed.
Note
To accept iDEAL, you must comply with our iDEAL Terms of Service.
Set up StripeServer-sideClient-side
Server-side
This integration requires endpoints on your server that talk to the Stripe API. Use our official libraries for access to the Stripe API from your server:
Client-side
The React Native SDK is open source and fully documented. Internally, it uses the native iOS and Android SDKs. To install Stripe’s React Native SDK, run one of the following commands in your project’s directory (depending on which package manager you use):
Next, install some other necessary dependencies:
- For iOS, go to the ios directory and run
pod install
to ensure that you also install the required native dependencies. - For Android, there are no more dependencies to install.
Note
We recommend following the official TypeScript guide to add TypeScript support.
Stripe initialisation
To initialise Stripe in your React Native app, either wrap your payment screen with the StripeProvider
component, or use the initStripe
initialisation method. Only the API publishable key in publishableKey
is required. The following example shows how to initialise Stripe using the StripeProvider
component.
import { useState, useEffect } from 'react'; import { StripeProvider } from '@stripe/stripe-react-native'; function App() { const [publishableKey, setPublishableKey] = useState(''); const fetchPublishableKey = async () => { const key = await fetchKey(); // fetch key from your server here setPublishableKey(key); }; useEffect(() => { fetchPublishableKey(); }, []); return ( <StripeProvider publishableKey={publishableKey} merchantIdentifier="merchant.identifier" // required for Apple Pay urlScheme="your-url-scheme" // required for 3D Secure and bank redirects > {/* Your app code here */} </StripeProvider> ); }
Create a PaymentIntentServer-sideClient-side
A PaymentIntent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.
Server-side
First, create a PaymentIntent
on your server and specify the amount to collect and the eur
currency (iDEAL doesn’t support other currencies). iDEAL doesn’t have a minimum charge amount, so the payment amount
value can be as low as 1. If you already have an integration using the Payment Intents API, add ideal
to the list of payment method types for your PaymentIntent
.
Instead of passing the entire PaymentIntent object to your app, return its client secret. The PaymentIntent’s client secret is a unique key that lets you confirm the payment and update payment details on the client, without allowing manipulation of sensitive information, such as payment amount.
Client-side
On the client, request a PaymentIntent from your server and store its client secret.
const fetchPaymentIntentClientSecret = async () => { const response = await fetch(`${API_URL}/create-payment-intent`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ email, currency: 'eur', payment_method_types: ['ideal'], }), }); const {clientSecret, error} = await response.json(); return {clientSecret, error}; };
Collect payment method detailsClient-side
In your app, collect your customer’s full name.
export default function IdealPaymentScreen() { const [name, setName] = useState(); const handlePayPress = async () => { // ... }; return ( <Screen> <TextInput placeholder="Name" onChange={(value) => setName(value.nativeEvent.text)} /> </Screen> ); }
Submit the payment to StripeClient-side
Retrieve the client secret from the PaymentIntent you created and call confirmPayment
. This presents a webview where the customer can complete the payment on their bank’s website or app. Afterwards, the promise resolves with the result of the payment.
export default function IdealPaymentScreen() { const [name, setName] = useState(); const handlePayPress = async () => { const {clientSecret} = await fetchPaymentIntentClientSecret(); const {error, paymentIntent} = await confirmPayment(clientSecret, { paymentMethodType: 'Ideal', paymentMethodData: { billingDetails: { name, }, }, }); if (error) { Alert.alert(`Error code: ${error.code}`, error.message); } else if (paymentIntent) { Alert.alert( 'Success', `The payment was confirmed successfully! currency: ${paymentIntent.currency}`, ); } }; return <Screen>{/* ... */}</Screen>; }
Test your integration
Use your test API keys to confirm the PaymentIntent. After confirming, you’re redirected to a test page with options to authorise or fail the payment.
- Click Authorize test payment to test the case when the payment is successful. The PaymentIntent transitions from
requires_
toaction succeeded
. - Click Fail test payment to test the case when the customer fails to authenticate. The PaymentIntent transitions from
requires_
toaction requires_
.payment_ method
OptionalHandle post-payment events
Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.
Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.
Handle events manually in the Dashboard
Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts or retry failed payments.
Build a custom webhook
Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.
Integrate a prebuilt app
Handle common business events, such as automation or marketing and sales, by integrating a partner application.
OptionalHandle deep linking
When a customer exits your app (for example to authenticate in Safari or their banking app), provide a way for them to automatically return to your app. Many payment method types require a return URL. If you don’t provide one, we can’t present payment methods that require a return URL to your users, even if you’ve enabled them.
To provide a return URL:
- Register a custom URL. Universal links aren’t supported.
- Configure your custom URL.
- Set up your root component to forward the URL to the Stripe SDK as shown below.
Note
If you’re using Expo, set your scheme in the app.
file.
import { useEffect, useCallback } from 'react'; import { Linking } from 'react-native'; import { useStripe } from '@stripe/stripe-react-native'; export default function MyApp() { const { handleURLCallback } = useStripe(); const handleDeepLink = useCallback( async (url: string | null) => { if (url) { const stripeHandled = await handleURLCallback(url); if (stripeHandled) { // This was a Stripe URL - you can return or add extra handling here as you see fit } else { // This was NOT a Stripe URL – handle as you normally would } } }, [handleURLCallback] ); useEffect(() => { const getUrlAsync = async () => { const initialUrl = await Linking.getInitialURL(); handleDeepLink(initialUrl); }; getUrlAsync(); const deepLinkListener = Linking.addEventListener( 'url', (event: { url: string }) => { handleDeepLink(event.url); } ); return () => deepLinkListener.remove(); }, [handleDeepLink]); return ( <View> <AwesomeAppComponent /> </View> ); }
For more information on native URL schemes, refer to the Android and iOS docs.
Bank reference
Bank name | Value |
---|---|
ABN AMRO | abn_ |
ASN Bank | asn_ |
Bunq | bunq |
ING | ing |
Knab | knab |
N26 | n26 |
Nationale-Nederlanden | nn |
Rabobank | rabobank |
Revolut | revolut |
RegioBank | regiobank |
SNS Bank (De Volksbank) | sns_ |
Triodos Bank | triodos_ |
Van Lanschot | van_ |
Yoursafe | yoursafe |