Client-Side Implementation

This guide shows you how to add SEPA Direct Debit to your custom client-side integration using the Braintree JavaScript SDK.

PrerequisitesAnchorIcon

Before you implement SEPA Direct Debit on the client side, make sure you have:

  • The Braintree JavaScript SDK loaded on your page, including the sepa component.

  • 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 SDKAnchorIcon

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:

  1. 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 componentAnchorIcon

  1. Initialize a client using either a tokenization key or a client token from your server.

  2. Create a SEPA component.

  1. 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 flowAnchorIcon

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 domainAnchorIcon

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 rulesAnchorIcon

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 domainAnchorIcon

Register your sandbox domain name in the Braintree Control Panel:

  1. Log into your sandbox Control Panel.

  2. Click the gear icon in the top right corner.

  3. Click Account Settings from the drop-down menu.

  4. Scroll to the Payment Methods section.

  5. Next to PayPal, click the Options link.

  6. Click the View Domain Names button.

  7. Enter the domain of your return page in the Specify Your Domain Names section.

  8. Click the Add Domain Names button.

Register your production domainAnchorIcon

Register your production domain name in the Braintree Control Panel:

  1. Log into your production Control Panel.

  2. Click the gear icon in the top right corner.

  3. Click Account Settings from the drop-down menu.

  4. Scroll to the Payment Methods section.

  5. Next to PayPal, click the Options link.

  6. Click the View Domain Names button.

  7. Enter the domain of your return page in the Specify Your Domain Names section.

  8. Click the Add Domain Names button.

Add the redirect flow codeAnchorIcon

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.

  1. 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 errorsAnchorIcon

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 limitationAnchorIcon

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 informationAnchorIcon

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:

  • countryCode

  • billingAddress (optional)

  • customerId (customer ID in the merchant's system)

TokenizeAnchorIcon

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.

  1. 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.

  1. 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
    }
  })
}