Add a Debit Card

Overview

You can provide the ability for workers to have payments made to an existing debit card, instead of the Branch Wallet, by embedding the Branch-customized TabaPay SSO Card Widget. This will let a worker securely input card details, returning a token to access the card data in a PCI-compliant manner.

Implementation

Ensure security when adding a debit card by having workers login using Multi-Factor Authentication
Develop a new endpoint called AddDebitCard for your backend server
1. Accept a POST request containing the worker's details (see step 5 for example request)
2. Forward the worker's details to Branch's Add External Card endpoint
3. Save the returned External Card's ID to the company database, to be used for future API calls
Add HTML to contain the Card Widget iFrame:

<div><iframe id="card-widget"></iframe></div>

Add JavaScript to load the Card Widget into the iFrame
1. Production URL: https://direct-embed.branchapp.com/card-widget.html
2. Sandbox URL: https://direct-embed-sandbox.branchapp.com/card-widget.html

// The URL below is for the Branch Sandbox, choose the production or sandbox URL accordingly  
var iFrameURL = "https://direct-embed-sandbox.branchapp.com/card-widget.html";  
document.getElementById("card-widget").src = iFrameURL;

Create a JavaScript function to extract the Card Widget iFrame data upon completion and forward them to your backend server endpoint

function extractCardWidgetData( event ) {  
  if ( event.data != "Close" ) {  
    if ( event.data.slice( 0, 7 ) == "Error: " ) {  
			// Error  
    } else {  
      var asData = event.data.split( "|" );  
      if ( asData.length == 9 ) {  
        // asData[ 0 ] contains the First Name  
        // asData[ 1 ] contains the Last Name  
        // asData[ 2 ] contains the Card BIN+Last4  
        // asData[ 3 ] contains the expiration in YYYYMM format  
        // asData[ 4 ] contains the token  
        // asData[ 5 ] contains the address  
        // asData[ 6 ] contains the city  
        // asData[ 7 ] contains the state 2 char ISO code  
        // asData[ 8 ] contains the zip code
        
        const firstName = asData[0]; // "John"
        const lastName = asData[1]; // "Larson"
        const cardBinAndLast4 = asData[2]; // "4111111111"
        const expiration = asData[3]; // "202605"
        const token = asData[4]; // "80BLD07rSYbG6u..."
        const address = asData[5]; // "1234 Any Street"
        const city = asData[6]; // "Kalispell"
        const state = asData[7]; // "MT"
        const zipCode = asData[8]; // "59901"

        // Forward the extracted worker details to your backend server endpoint 
        fetch("https://www.your-backend-server.com/add-debit-card", {
          method: "POST",
          body: JSON.stringify({
            firstName: firstName, 
            lastName: lastName, 
            cardBinAndLast4: cardBinAndLast4, 
            expiration: expiration, 
            token: token, 
            address: address, 
            city: city, 
            state: state, 
            zipCode: zipCode 
          }),
          headers: {
            "Content-type": "application/json; charset=UTF-8"
          }
        });

      } else {  
        // Data Error  
      }  
    }  
  } else {  
    // Close or Cancel  
  }  
}

Use JavaScript to bind the data extraction function to a listener on the Card Widget iFrame completion event

window.addEventListener( "message", extractCardWidgetData, false );

Testing Cards

Enter sample card numbers from here to test the functionality of extractCardWidgetData
Card type must be debit for a successful response
Using a CVV of 999 will generate an invalid CVV response

Overview

Implementation

Testing Cards

Example Card Widget iFrame - Sandbox