Client-Side Implementation

JavaScript v3SDK

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• iOS v5
• JavaScript v2

availability

SEPA Direct Debit is available to eligible merchants using a custom client-side integration. It is only available in Android v4.13+, iOS v5.11+, and JavaScript v3 SDK. It's not currently available in Drop-in.

If you meet the criteria, Contact us to enable SEPA Direct Debit in your Sandbox or Production account.

Installation

To set up the Braintree JavaScript v3 SDK, see the installation guide.

Then, load the sepa component. If you are using script tags to load files, be sure to at least include:

<script src="https://js.braintreegateway.com/web/3.90.0/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.90.0/js/sepa.min.js"></script>

Initialization

1. Initialize a client using either a tokenization key or a client token from your server
2. Create a SEPA component

braintree.client.create({
  client: clientInstance,
}, function (sepaErr, sepaInstance) {

  if (sepaErr) {
    console.error('Error creating client:', sepaErr);
    return;
  }

  // create a SEPA component
  return braintree.sepa.create({
    client: clientInstance,
    merchantId: "merchant-id",
  });
});

Redirect Flow

availability

SEPA Direct Debit redirect flow is available in the Braintree JS SDK starting in version 3.110.0

We've heard about several issues from merchants about popups being blocked, which has led to users not being able to complete payments. To enhance the user experience and ensure seamless payment processing, we are introducing a new redirect flow. This feature enables merchants to provide a redirectUrl which will redirect users on the current page instead of opening a new popup window. The new flow maintains the same functionality as the existing popup flow which ensures a seamless transition for your users.

Domain Registration

In order 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 using the instructions below. You will have to do this in both your sandbox and production environments.

Rules for domain names

A domain name:

• Must not start with a scheme (e.g. "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 etc. a.b.example.com where example is the top-level domain, com is the second-level domain, and a and b are subdomains.
• The top-level domain must consist of 2 to 63 letters.
• Each subdomain and the second-level domain must consist of 1 to 63 alphanumeric characters and or hyphens.
• Each subdomain and the second-level domain can not start or end with a hyphen.
• The top-level domain, second-level domain, and the subdomains must be separated by a dot(.).
• Can end with a trailing dot.

Sandbox Environment

Register your sandbox domain name in the Braintree Control Panel:

1. Log into your sandbox Control Panel

2. Click on 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. Client the View Domain Names button

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

8. Click Add Domain Names button

Production environment

Register your production domain name in the Braintree Control Panel:

1. Log into your production Control Panel

2. Click on 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. Client the View Domain Names button

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

8. Click Add Domain Names button

Code examples for redirect flow

To utilize the new redirect flow, you need to pass the redirectUrl parameter when calling braintree.sepa.create. This redirectUrl should point to the same page of your merchant website where you redirect the user from, so that when redirected back, the Braintree SDK can finish tokenizing and provide you with a nonce.

braintree.client.create({
  client: clientInstance,
}, function (clientErr, clientInstance) {

  if (clientErr) {
    console.error('Error creating client:', clientErr);
    return;
  }

  // create a SEPA component
  return braintree.sepa.create({
    client: clientInstance,
    merchantId: "merchant-id",
    // Passing this redirectUrl will initiate the redirect flow
    redirectUrl: "https://www.merchant-site.com/redirect-page.html"
  }, function (sepaErr, sepaInstance) {
    if (sepaErr) {
      console.error("There was an error: ", sepaErr);
      return;
    }

    if (sepaInstance.tokenizePayload) {
      console.log("Got a nonce: ", sepaInstance.tokenizePayload.nonce);
    }
  });
});

After redirecting back from the mandate page, if tokenization was successful, you will be able to access a nonce on the sepaInstance (see example above). The 3 other values available in the tokenizePayload are ibanLastFour, customerId, and mandateType.

Error Handling

If the payment was successful, the redirect URL will have the param success=true. In the case where the user cancels out of the payment flow, the redirect URL will have the params cancel=1 as well as error_code=USER_DECLINED.

Tokenization Key Limitation

Please note that the redirect flow will not work with a tokenization key as tokenization keys have reduced authorization. If using a tokenization key is a requirement for your integration, please reach out to a Braintree representative.

Collect 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:

• countryCode
• billingAddress (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. The call to tokenize is then set up to be invoked as a result of a customer action, such as a button click.

For the specifics around tokenize, check out our reference documentation.

// These values come from the input fields of your own definition.
var accountHolderName = document.getElementById("account-holder-name").value;
var customerId = document.getElementById("customer-id").value;
var iban = document.getElementById("iban").value;
var mandateType = document.getElementById("mandate-type").value;
var countryCode = document.getElementById("country-code").value;

// This value is whatever element you want to use to trigger tokenization.
var sepaButton = document.getElementById("sepa-button")
// create a SEPA component
braintree.sepa.create({
    client: clientInstance,
    merchantId: "merchant-id",
}, function (sepaErr, sepaInstance) {
  if (sepaErr) {
    console.log("Error creating SEPA:", sepaErr)
    return
  }

  sepaButton.addEventListener('click', function() {
      sepaInstance.tokenize({
        accountHolderName: accountHolderName,
        customerId: customerId,
        iban: iban,
        mandateType: mandateType, // ONE_OFF OR "RECURRENT"
        countryCode: countryCode,
        merchantAccountId: "MERCHANT-ACCOUNT-ID",
      }, function (tokenizationErr, payload) {
        if (tokenizationErr) {
          // handle error
        }

        // Authorization complete, nonce retrieved successfully
        console.log("Nonce recieved:", payload.nonce)
      });
    })
})

Example of tokenize call with buyer's billing address.

// These values come from the input fields of your own definition.
var accountHolderName = document.getElementById("account-holder-name").value;
var customerId = document.getElementById("customer-id").value;
var iban = document.getElementById("iban").value;
var mandateType = document.getElementById("mandate-type").value;
var countryCode = document.getElementById("country-code").value;
var addressLine1 = document.getElementById("address-line1").value;
var addressLine2 = document.getElementById("address-line2").value;
var adminArea1 = document.getElementById("admin-area1").value;
var adminArea2 = document.getElementById("admin-area2").value;
var postalCode = document.getElementById("postal-code").value;

// This value is whatever element you want to use to trigger tokenization.
var sepaButton = document.getElementById("sepa-button")
// create a SEPA component
braintree.sepa.create({
    client: clientInstance,
    merchantId: "merchant-id",
}, function (sepaErr, sepaInstance) {
  if (sepaErr) {
    console.log("Error creating SEPA:", sepaErr)
    return
  }

  sepaButton.addEventListener('click', function() {
      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,
        }
      }, function (tokenizationErr, payload) {
        if (tokenizationErr) {
          // handle error
        }

        // Authorization complete, nonce retrieved successfully
        console.log("Nonce recieved:", payload.nonce)
      });
    })
})