iDEAL Bank Element Quickstart
Collect your customers’ iDEAL bank using Elements, our pre-built UI components.
The iDEAL Bank Element lets you collect your customers’ bank to create iDEAL Sources. Collecting the bank isn’t required to create iDEAL Sources, but it is strongly recommended. If you collect the bank, you can redirect a customer directly to their bank’s payment page instead of an interstitial bank selection page.
<script src="https://js.stripe.com/v3/"></script>
<form id="payment-form">
<div class="form-row">
<label for="name">
Name
</label>
<input id="name" name="name" placeholder="Jenny Rosen" required>
</div>
<div class="form-row">
<label for="ideal-bank-element">
iDEAL Bank
</label>
<div id="ideal-bank-element">
<!-- A Stripe Element will be inserted here. -->
</div>
</div>
<button>Submit Payment</button>
<!-- Used to display form errors. -->
<div id="error-message" role="alert"></div>
</form>/**
* The CSS shown here will not be introduced in the Quickstart guide, but
* shows how you can use CSS to style your Element's container.
*/
input,
.StripeElement {
height: 40px;
color: #32325d;
background-color: white;
border: 1px solid transparent;
border-radius: 4px;
box-shadow: 0 1px 3px 0 #e6ebf1;
-webkit-transition: box-shadow 150ms ease;
transition: box-shadow 150ms ease;
}
input {
padding: 10px 12px;
}
input:focus,
.StripeElement--focus {
box-shadow: 0 1px 3px 0 #cfd7df;
}
.StripeElement--invalid {
border-color: #fa755a;
}// Create a Stripe client.
// Note: this merchant has been set up for demo purposes.
var stripe = Stripe('pk_test_6pRNASCoBOKtIshFeQd4XMUh');
// Create an instance of Elements.
var elements = stripe.elements();
// Custom styling can be passed to options when creating an Element.
// (Note that this demo uses a wider set of styles than the guide below.)
var style = {
base: {
padding: '10px 12px',
color: '#32325d',
fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
fontSmoothing: 'antialiased',
fontSize: '16px',
'::placeholder': {
color: '#aab7c4'
},
},
invalid: {
color: '#fa755a',
}
};
// Create an instance of the idealBank Element.
var idealBank = elements.create('idealBank', {style: style});
// Add an instance of the idealBank Element into the `ideal-bank-element` <div>.
idealBank.mount('#ideal-bank-element');Additional features of the iDEAL Bank Element include:
- Constantly up-to-date list of iDEAL-member banks, along with their logos
- Keyboard shortcuts and screen-reader accessibility
- Cross-browser support and mobile optimization
- Localization in 15 languages
Building a custom payment form with Elements to create ideal Sources
requires four steps:
Step 1: Set up Stripe Elements
Elements is available as part of Stripe.js. To get started, include the following script on your pages. This script must always load directly from js.stripe.com in order to remain PCI compliant—you can’t include it in a bundle or host a copy of it yourself.
<script src="https://js.stripe.com/v3/"></script>To best leverage Stripe’s advanced fraud functionality, include this script on every page on your site, not just the checkout page. Including the script on every page allows Stripe to detect anomalous behavior that may be indicative of fraud as users browse your website.
Next, create an instance of Elements:
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
var elements = stripe.elements();const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements();We've placed a random API key in the code. Replace it with your actual publishable API key to test this code through your Stripe account.
When you’re ready to accept live iDEAL payments, replace the test key with your live key. Learn more about how the keys play into test and live modes.
Step 2: Create your payment form
To collect the iDEAL bank from your customers, Elements creates a UI component for you that is hosted by Stripe. It is then placed into your payment form, rather than you creating it directly.
To determine where to insert these components, create empty DOM elements
(containers) with unique IDs within your payment form. We recommend placing
your container within a <label> or next to a <label> with a for
attribute that matches the unique id of the Element container. By doing
so, the Element automatically gains focus when the customer clicks on the
corresponding label.
For example:
<form id="payment-form">
<div class="form-row">
<label for="name">
Name
</label>
<input name="name">
</div>
<div class="form-row">
<label for="ideal-bank-element">
iDEAL Bank
</label>
<div id="ideal-bank-element">
<!-- A Stripe Element will be inserted here. -->
</div>
</div>
<button>Submit Payment</button>
<!-- Used to display form errors. -->
<div id="error-message" role="alert"></div>
</form>When the form above has loaded,
create an instance of an
idealBank Element and mount it to the Element container created above:
var options = {
// Custom styling can be passed to options when creating an Element.
style: {
base: {
// Add your base input styles here. For example:
fontSize: '16px',
color: '#32325d',
padding: '10px 12px',
},
}
}
// Create an instance of the idealBank Element.
var idealBank = elements.create('idealBank', options);
// Add an instance of the idealBank Element into
// the `ideal-bank-element` <div>.
idealBank.mount('#ideal-bank-element');const options = {
// Custom styling can be passed to options when creating an Element.
style: {
base: {
// Add your base input styles here. For example:
fontSize: '16px',
color: '#32325d',
padding: '10px 12px',
},
}
}
// Create an instance of the idealBank Element.
const idealBank = elements.create('idealBank', options);
// Add an instance of the idealBank Element into
// the `ideal-bank-element` <div>.
idealBank.mount('#ideal-bank-element');You can update the configuration options (e.g., the style) of the
idealBank Element at any point using
element.update(options).
The iDEAL Bank Element emits the customer’s selected bank as it changes. If you would like to perform additional logic with the bank value (such as requiring the field for form validation, for example), you can listen to the change event:
idealBank.on('change', function(event) {
var bank = event.value;
// Perform any additional logic here...
});idealBank.on('change', ({value}) => {
const bank = value;
// Perform any additional logic here...
});The change event also contains a few other helpful properties:
|
elementType
string
|
idealBank, the name of the Element. |
|
empty
Boolean
|
true if the value is empty. |
|
complete
Boolean
|
true if the value has been picked by the customer.complete can be used to progressively disclose the next parts of your form or to enable form submission. |
|
value
string
|
The iDEAL bank that the customer picked from the Element. The full list of banks can be found in the iDEAL guide. |
Step 3: Create a Source object
The payment details collected using Elements can then be converted into a
source. Create an event handler that handles the submit event on the
form. The handler sends the fields to Stripe for source creation and
prevents the form’s submission. The resulting source is used to redirect the
customer for payment authorization (in the next step.)
// Create a source or display an error when the form is submitted.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
event.preventDefault();
var sourceData = {
type: 'ideal',
amount: 1099,
currency: 'eur',
owner: {
name: document.querySelector('input[name="name"]').value,
},
// Specify the URL to which the customer should be redirected
// after paying.
redirect: {
return_url: 'https://shop.example.com/crtA6B28E1',
},
};
// Call `stripe.createSource` with the idealBank Element and
// additional options.
stripe.createSource(idealBank, sourceData).then(function(result) {
if (result.error) {
// Inform the customer that there was an error.
var errorElement = document.getElementById('error-message');
errorElement.textContent = error.message;
} else {
// Redirect the customer to the authorization URL.
stripeSourceHandler(result.source);
}
});
});// Create a source or display an error when the form is submitted.
const form = document.getElementById('payment-form');
form.addEventListener('submit', async (event) => {
event.preventDefault();
const sourceData = {
type: 'ideal',
amount: 1099,
currency: 'eur',
owner: {
name: document.querySelector('input[name="name"]').value,
},
// Specify the URL to which the customer should be redirected
// after paying.
redirect: {
return_url: 'https://shop.example.com/crtA6B28E1',
},
};
// Call `stripe.createSource` with the idealBank Element and
// additional options.
const {source, error} = await stripe.createSource(idealBank, sourceData);
if (error) {
// Inform the customer that there was an error.
const errorElement = document.getElementById('error-message');
errorElement.textContent = error.message;
} else {
// Redirect the customer to the authorization URL.
stripeSourceHandler(source);
}
});The stripe.createSource method takes two arguments:
element, the Element containing the payment information. If applicable, the Element pulls data from other Elements you’ve created on the same instance ofelements.sourceData, a required object containing the type of Source you want to create, and any additional payment information that you have collected. See the Sources API reference for details.
It returns a Promise which resolves with a result object. This object
has either:
result.source, a Source was created successfully.result.error, there was an error. This includes client-side validation errors. Refer to the iDEAL guide for more information on errors.
Optional: Providing a custom statement descriptor
iDEAL requires a statement descriptor
before the customer is redirected to authenticate the payment. By default,
your Stripe account’s statement descriptor is used (you can review this in
the Dashboard).
You can provide a custom descriptor by specifying statement_descriptor
when creating a source.
var sourceData = {
type: 'ideal',
amount: 1099,
currency: 'eur',
// Specify a custom statement descriptor.
statement_descriptor: 'ORDER AT11990',
owner: {
name: document.querySelector('input[name="name"]').value,
},
redirect: {
return_url: 'https://shop.example.com/crtA6B28E1',
},
};const sourceData = {
type: 'ideal',
amount: 1099,
currency: 'eur',
// Specify a custom statement descriptor.
statement_descriptor: 'ORDER AT11990',
owner: {
name: document.querySelector('input[name="name"]').value,
},
redirect: {
return_url: 'https://shop.example.com/crtA6B28E1',
},
};Providing a custom statement descriptor within a subsequent charge request has no effect.
Step 4: Redirect the customer to authorize payment
The last step is to redirect the customer to the URL specified in the Source.
function stripeSourceHandler(source) {
// Redirect the customer to the authorization URL.
document.location.href = source.redirect.url;
}const stripeSourceHandler = (source) => {
// Redirect the customer to the authorization URL.
document.location.href = source.redirect.url;
}More details about having the customer authorize payment can be found in the iDEAL guide.
Next steps
Congrats! You now have a custom payment form to create ideal sources.
You can continue with Step 2 of the iDEAL guide
to learn more about having the customer authorize the payment, and charging
the source.