Capturing a Bank Account

Capturing bank account details through the Zai platform is a straightforward task, which can be accomplished by utilising the Hosted Forms and Hosted Fields packages. Through this integration, it is possible to capture bank account details and generate an accompanying token through a variety of different measures, including secure iFrame transport layers and custom forms.

Before you start

Capturing bank account information utilises the Hosted Forms and Hosted Fields packages. Please make sure that you have properly set up the integration with the Hosted Forms and Hosted Fields packages on your platform before continuing.

If you have not yet set up the Hosted Forms and Hosted Fields packages within your platform, please follow the instructions laid out in our guide for Hosted Forms and Hosted Fields.

Capturing bank account details

Capturing bank account details through the front-end will mean data can be securely sent to Zai with minimal PCI compliance impact.

There are a couple of methods which can be used to capture bank account details.

Generating a bank account token

A bank account token is used to authorise the passing of bank account details through the client-side libraries. The generating of the bank account token occurs server-side so that the generated token can be passed into the client-side for authentication. There are two use cases for generating a bank account token:

• Capturing bank account details of an existing user. This will involve passing the user_id parameter when generating the bank account token. This token will expire as soon as a valid bank account is added or after 2 hours.
• Capturing bank account details for an anonymous or new user (using the Charge API). This will involve not passing the user_id parameter when generating the bank account token. This token will expire as soon as a valid bank account is added or after 2 hours

Use Generate Token to generate the card token.

Direct Javascript

Capturing bank account details using the Direct Javascript has two steps:

1. Generating a bank account token to authenticate the creation of a bank account in Zai.
2. Sending the bank account details to Zai through the Javascript method.

Sending the bank account information to Zai will return a successful or failure response. You may wish to provide feedback once the request has been made. Webhooks will need to be created to handle these.

If the request is successful, you will receive a JSON response just as if you had created the bank account using the Create Bank Account method. This will provide a bank account id that can be used to make a payment. This account ID can also be fetched using the Show Bank Account User method in the API.

// Create your callback methods
success = function(data) {
	console.log(data);
}
 
fail = function(data) {
	console.log(data);
}

/**
* @param {string} bankToken
* @param {string} bankData
* @param {string} successFunction
* @param {string} failFunction
*/
 
promisepay.createBankAccount("BANK_TOKEN", {
	bank_name: 'Bank of Australia',
  account_name: 'Samuel Seller',
  routing_number: '123123',
  account_number: '12341234',
  account_type: 'checking',
  holder_type: 'personal',
  country: 'AUS',
  payout_currency: 'AUD'
}, success, fail)

Creating a custom HTML form

Capturing bank account details using a Custom Form has three steps;

1. Generating a bank account token to authenticate the creation of a bank account in Zai.
2. Setting up your bank account form.
3. Sending the bank account details to Zai through your form.

Sending the bank account information to Zai will return a successful or failure response. You may wish to provide feedback once the request has been made. Webhooks will need to be created to handle these.

If the request is successful, you will receive a JSON response just as if you had created the bank account using the Create Bank Account method. This will provide a bank account id that can be used to make a payment. This account ID can also be fetched using the Show Bank Account User method in the API.

Creating the HTML Form

<form  id="promisepay-form">
   <input type="hidden" data-promisepay-bank-token="0c3efa044686cd4d17fe624aebca3b74" > <br>
   <input type="text" data-promisepay-encrypted-name="userId" placeholder="user id" value="3646150a87aebe1ac32172773f986e34"> <br>
   <input type="text" data-promisepay-encrypted-name="bankName" placeholder="Bank Name" value="Bank of Australia"> <br>
   <input type="text" data-promisepay-encrypted-name="bankAccountName" placeholder="Account Name" value="Samuel Seller"> <br>
   <input type="text" data-promisepay-encrypted-name="bankAccountNumber" placeholder="Bank account number" value="12341234"> <br>
   <input type="text" data-promisepay-encrypted-name="bankRoutingNumber" placeholder="Routing Number" value="123123"> <br>
   <input type="text" data-promisepay-encrypted-name="bankAccountType" placeholder="Account Type" value="checking"> <br>
   <input type="text" data-promisepay-encrypted-name="bankHolderType" placeholder="Holder Type" value="personal"> <br>
   <input type="text" data-promisepay-encrypted-name="bankCountry" placeholder="Bank Country" value="AUS"> <br>
   <input type="text" data-promisepay-encrypted-name="payoutCurrency" placeholder="Payout Currency" value="AUD"> <br>
   <p class="promisepay-server-error" style="display: none"></p>
   <input type="submit" >
</form>

Ensure no name attributes are passed through for any bank account inputs. This is to avoid any of the information being passed to your back-end service.

📘

Key notes

• The element with class promisepay-server-error can be used to return any server errors with bank account creation.
• Upon successful submission, the form will submit with a new hidden input which contains the bank account id.

Sending the data to Zai

$(document).ready(function () {
	promisepay.createBankAccountForm("promisepay-form", success, fail);
})

Webhook functions

createBankAccountForm(formId, successFunction, failFunction, errorStrings);

Error strings

{
  "CARD_NAME": "<span class='promisepay-form-error'> Please enter a valid name </span>",
  "CARD_NUMBER": "<span class='promisepay-form-error'> Please enter a valid card number </span>",
  "CARD_DATE": "<span class='promisepay-form-error'> Please enter a valid credit card expiry date </span>",
  "CARD_CVC": "<span class='promisepay-form-error'> Please enter a valid CVC </span>",
  "BANK_NAME":"<span class='promisepay-form-error'> Please enter a valid Bank Name </span>",
  "BANK_ACCOUNT_NAME":"<span class='promisepay-form-error'> Please enter a valid Account Name </span>",
  "BANK_ROUTING_NUMBER":"<span class='promisepay-form-error'> Please enter a valid Routing Number </span>",
  "BANK_ACCOUNT_NUMBER":"<span class='promisepay-form-error'> Please enter a valid Account Number </span>",
  "BANK_ACCOUNT_TYPE":"<span class='promisepay-form-error'> Please enter a valid Account Type </span>",
  "BANK_HOLDER_TYPE":"<span class='promisepay-form-error'> Please enter a valid Holder Type </span>",
  "BANK_COUNTRY":"<span class='promisepay-form-error'> Please enter a valid Country </span>",
  "PAYOUT_CURRENCY":"<span class='promisepay-form-error'> Please enter a valid Currency </span>",
  "CARD_TOKEN": {
      "UNAUTHORIZED": "Card Token unauthorized"
  },
  "BANK_TOKEN":{
      "UNAUTHORIZED": "Bank Token unauthorized",
      "RECORD":"Bank Token not authorized to access that record"
  },
  "BASE": {
      "PAYMENT_FAILED": "Credit card payment failed: Unable to process the purchase transaction."
  },
};

Diagnosing Issues

Pass the following function into the “promisepay.createBankAccountForm” method as the failFunction parameter. Errors should be descriptive enough to provide a diagnosis.

fail = function (data) {
	console.log(data);
}

At this point, if the card token was attached to a user, they will have a bank account attached to their user in Zai.