Verify Bank Accounts with Secure Input

Example Bank Account Verification Form

<form id="add-payment-method" pl-form="payment_method">
  <div>
    <div pl-input="account_number" placeholder="Account Number">
    </div>
    <div pl-input="account_number"
         placeholder="Retype Account Number"
         pl-confirm-only>
    </div>
  </div>
  <div>
    <div pl-input="routing_number" placeholder="000000000"></div>
  </div>
  <div>
    <select pl-input="account_type">
        <option value="checking">Checking</option>
        <option value="savings">Savings</option>
    </select>
    <select pl-input="account_class">
        <option value="personal">Personal</option>
        <option value="business">Business</option>
    </select>
  </div>
  <button type="submit">
    Save Billing Details
  </button>
</form>

<script>
// See UI Authentication on how to obtain a client token
Payload('generated_client_token')
new Payload.Form({
    form: document.getElementById('add-payment-method'),
    payment_method: {
        // Set to receive-only for payouts
        transfer_type: 'receive-only',

        // *optional* Pass customer details to verify ownership
        customer: {
            name: 'Customer Name',
            email: '[email protected]'
        }
    }
}).on('created', (evt)=>{
    console.log(evt.payment_method_id)
}).on('error', (evt)=>{
    console.log(evt.message)
})
</script>

Every new bank account linked to Payload is verified through either an external verification service, like Plaid, or through Payload's built-in verification API. In situations where a bank doesn't support Plaid or Plaid doesn't make sense for the use-case, you can use Secure Inputs to link and verify a bank account using Payload's built-in verification API.

Understanding the Verification Results

A linked bank account payment method has a verification_status field with the resulting status of the verification. There are three values that can result from the verification attempt (see the table and detailed descriptions below).

not-verified

Accounts with the verification status of not-verified indicates that verification could not be performed. This is usually due to the bank or financial institution not supporting account verification. Transactions against an unverified account can be rejected if the account details were miskeyed or incorrect.

verified

Accounts with the verification status of verified indicates the account details were confirmed with the bank or financial institution. It also means that an ownership match on the account was either unsuccessful or not able to be performed.

owner-verified

Accounts with the verification status of owner-verified indicates the account details were confirmed with the bank or financial institution and there was an ownership match found. An ownership match can only be performed if the bank account is tied to a customer, or if the account_holder field is provided.

Using Verification with Secure Inputs

To link a bank account with Payload's built-in verification API using Secure Inputs, use a standard Secure Input form for a payment method (by setting the pl-form property to payment_method) with the standard bank account fields (see table below).

Bank Account Form Fields

For more information, see the Secure Input section.

Testing and Error Handling

Use the following values with a test api key to try out the different response conditions.

Test values

Error handling

<script>
// See UI Authentication on how to obtain a client token
Payload('generated_client_token')
new Payload.Form({
    // initialize Payload.Form here
    form: document.getElementById('add-payment-method')
}).on('error', (evt)=>{
    // Listen for errors
    console.log(evt)
    alert(evt.message)
})
</script>

When attempting a verification check, the account details may be invalid or the account is unable to accept external debits or credits which will result in an error.

To watch for errors use the Payload.Form error event listener as shown in the example.