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>
Payload('test_client_key_....')
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: 'customer@email.com'
        }
    }
}).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).

Status Description
not-verified Verification was not performed or not available
verified Verification was successful
owner-verified Verification and owner match was successful

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

Name Description
account_number secure The bank account number
routing_number secure The ACH routing number for the account
account_type Either checking or savings
account_class optional Either personal or business
account_holder optional Name of business or individual owner of the account
transfer_type optional Either send-only, receive-only, or two-way

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

Attribute Value Result
routing_number 011111111 Returns a verification_status of not-verified
account_number 0009903 Raises error for invalid account number
account_holder Valid Owner Returns a verification_status of owner-verified

Error handling

<script>
Payload('test_client_key_....')
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.