Client-Side Implementation
This guide shows you how to add SEPA Direct Debit to your custom client-side integration using the Braintree JavaScript SDK.
SEPA Direct Debit is available to eligible merchants using a custom client-side integration. It's only available in Android v4.13+, iOS v5.11+, and the JavaScript SDK. It's not currently available in the Drop-in UI.
If you meet the criteria, contact us to enable SEPA Direct Debit in your Sandbox or Production account.
Prerequisites
Before you implement SEPA Direct Debit on the client side, make sure you have:
The Braintree JavaScript SDK loaded on your page, including the
sepacomponent.A client authorization: a tokenization key or a client token generated on your server.
A Sandbox or Production account enabled for SEPA Direct Debit. Contact us if SEPA Direct Debit isn't yet enabled for your account.
Install the SDK
To set up the Braintree JavaScript SDK, see the installation guide.
Then, load the sepa component. If you're using script tags to load files, be sure to at least include:
- HTML
<script src="https://js.braintreegateway.com/web/4.0.0-alpha.0/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/4.0.0-alpha.0/js/sepa.min.js"></script>Initialize the client and create a SEPA component
Initialize a
clientusing either a tokenization key or a client token from your server.Create a SEPA component.
- Async/Await
// create a client
async function setupSepa() {
try {
const clientInstance = await braintree.client.create({
authorization: 'CLIENT-AUTHORIZATION'
});
// create a SEPA component
const sepaInstance = await braintree.sepa.create({
client: clientInstance,
merchantId: 'MERCHANT-ID',
});
// ...
} catch (err) {
// handle component creation error
}
}Set up the redirect flow
Merchants have reported issues with popups being blocked, which stops users from completing payments. To improve the user experience, the redirect flow lets you provide a redirectUrl that redirects users on the current page instead of opening a new popup window. The redirect flow works the same way as the existing popup flow, so your users get a seamless experience either way.
Register your domain
To use the redirect flow, you'll need to register any domains you plan to use as a redirectUrl with PayPal. You can do this through the Braintree Control Panel. You need to complete this step in both your sandbox and production environments.
Follow the domain name rules
A domain name:
Must not start with a scheme, for example, "https://".
Must be between 4 and 255 characters.
Cannot contain spaces or wildcards (*).
Can consist of a top-level domain, a second-level domain, and 0 or more subdomains, for example, a.b.example.com, where "example" is the top-level domain, "com" is the second-level domain, and "a" and "b" are subdomains.
Must have a top-level domain of 2 to 63 letters.
Must have a subdomain and second-level domain of 1 to 63 alphanumeric characters or hyphens.
Cannot have a subdomain or second-level domain that starts or ends with a hyphen.
Must separate the top-level domain, second-level domain, and subdomains with a dot (.).
Can end with a trailing dot.
Register your sandbox domain
Register your sandbox domain name in the Braintree Control Panel:
Log into your sandbox Control Panel.
Click the gear icon in the top right corner.
Click Account Settings from the drop-down menu.
Scroll to the Payment Methods section.
Next to PayPal, click the Options link.
Click the View Domain Names button.
Enter the domain of your return page in the Specify Your Domain Names section.
Click the Add Domain Names button.
Register your production domain
Register your production domain name in the Braintree Control Panel:
Log into your production Control Panel.
Click the gear icon in the top right corner.
Click Account Settings from the drop-down menu.
Scroll to the Payment Methods section.
Next to PayPal, click the Options link.
Click the View Domain Names button.
Enter the domain of your return page in the Specify Your Domain Names section.
Click the Add Domain Names button.
Add the redirect flow code
To use the redirect flow, pass the redirectUrl parameter when calling braintree.sepa.create. This redirectUrl should point to the same page of your merchant website that redirected the user, so that when the SDK redirects the user back, it can finish tokenizing and provide you with a nonce.
- Async/Await
async function setupSepa() {
try {
const clientInstance = await braintree.client.create({
// only client tokens are usable with the redirect flow
authorization: 'CLIENT-TOKEN'
});
// create a SEPA component
const sepaInstance = await braintree.sepa.create({
client: clientInstance,
merchantId: 'MERCHANT-ID',
// Pass redirect url
redirectUrl: "https://www.merchant-site.com/redirect-page.html"
});
// ...
if (sepaInstance.tokenizePayload) {
console.log("Got a nonce: ", sepaInstance.tokenizePayload.nonce);
}
} catch (err) {
// handle component creation error
}
}After the SDK redirects the user back from the mandate page, if tokenization was successful, you can access a nonce on the sepaInstance (see the example above). The three other values available in the tokenizePayload are ibanLastFour, customerId, and mandateType.
Handle errors
If the payment was successful, the redirect URL has the param success=true. If the user cancels out of the payment flow, the redirect URL has the params cancel=1 and error_code=USER_DECLINED.
Understand the tokenization key limitation
The redirect flow doesn't work with a tokenization key, because tokenization keys have reduced authorization. If your integration requires a tokenization key, contact a Braintree representative.
Collect customer information
Once your component is ready, collect the required bank account information from the customer.
Bank information:
accountHolderName(the name of the account owner)iban(International Bank Account Number)
Customer information:
countryCodebillingAddress(optional)customerId(customer ID in the merchant's system)
Tokenize
Collect the required information from the customer, and pass it to your newly created SEPA component to call tokenize. Set up the call to tokenize to run as a result of a customer action, such as a button click.
For the specifics around tokenize, check out our reference documentation.
- Async/Await
// These values come from the input fields of your own definition.
const accountHolderName = document.getElementById("account-holder-name").value;
const customerId = document.getElementById("customer-id").value;
const iban = document.getElementById("iban").value;
const mandateType = document.getElementById("mandate-type").value;
const countryCode = document.getElementById("country-code").value;
// This value is whatever element you want to use to trigger tokenization.
const sepaButton = document.getElementById("sepa-button")
// create a SEPA component
async function setupSepa() {
const sepaInstance = await braintree.sepa.create({
client: clientInstance,
merchantId: 'MERCHANT-ID',
});
// tokenize
sepaButton.addEventListener('click', async function() {
try {
const payload = await sepaInstance.tokenize({
accountHolderName: accountHolderName,
customerId: customerId,
iban: iban,
mandateType: mandateType, // "ONE_OFF" OR "RECURRENT"
countryCode: countryCode,
merchantAccountId: 'MERCHANT-ACCOUNT-ID',
});
// Authorization complete, nonce retrieved successfully
console.log("Nonce received:", payload.nonce)
} catch (err) {
// handle component creation error
}
})
}Here's an example of a tokenize call with the buyer's billing address.
- Async/Await
// These values come from the input fields of your own definition.
const accountHolderName = document.getElementById("account-holder-name").value;
const customerId = document.getElementById("customer-id").value;
const iban = document.getElementById("iban").value;
const mandateType = document.getElementById("mandate-type").value;
const countryCode = document.getElementById("country-code").value;
const addressLine1 = document.getElementById("address-line1").value;
const addressLine2 = document.getElementById("address-line2").value;
const adminArea1 = document.getElementById("admin-area1").value;
const adminArea2 = document.getElementById("admin-area2").value;
const postalCode = document.getElementById("postal-code").value;
// This value is whatever element you want to use to trigger tokenization.
const sepaButton = document.getElementById("sepa-button")
// create a SEPA component
async function setupSepa() {
const sepaInstance = await braintree.sepa.create({
client: clientInstance,
merchantId: 'MERCHANT-ID',
});
// tokenize
sepaButton.addEventListener('click', async function() {
try {
const payload = await sepaInstance.tokenize({
accountHolderName: accountHolderName,
customerId: customerId,
iban: iban,
mandateType: mandateType, // "ONE_OFF" OR "RECURRENT"
countryCode: countryCode,
merchantAccountId: 'MERCHANT-ACCOUNT-ID',
billingAddress: {
addressLine1: addressLine1,
addressLine2: addressLine2,
adminArea1: adminArea1,
adminArea2: adminArea2,
postalCode: postalCode,
}
});
// Authorization complete, nonce retrieved successfully
console.log("Nonce received:", payload.nonce)
} catch (err) {
// handle component creation error
}
})
}