Validate a bank account

mutation ValidateBankAccount($input: ValidateBankAccountInput!) {
  validateBankAccount(validateBankAccountInput: $input) {
    validateBankAccountResponse {
      ... on ValidateBankAccountApproval {
        transactionId
        paymentId
        processorResponseCode
        validationProviderScore
        isDuplicateRequest
      }
      ... on ValidateBankAccountDecline {
        message
        processorAdvice
        declineType
        validationProviderScore
        transactionId
      }
    }
    errors {
      errorType: __typename
      ... on ValidationFailureError {
        message
        fieldPath
      }
      ... on RouteNotFoundError {
        message
      }
      ... on AcceptorNotFoundError {
        message
      }
    }
  }
}

{
  "input": {
    "acceptorId": "05a39b14-f29f-443b-a107-da3e3e8969fb",
    "transactionReference": "68448abe-735b-4ee3-af14-d0f50a091c9b",
    "paymentMethodDetails": {
      "bankAccountDetails": {
        "routingNumber": "123456789",
        "accountNumber": "12345678",
        "bankAccountType": "SAVINGS",
        "accountOwnerType": "CONSUMER",
        "paymentEntryMode": "KEYED",
        "recurringType": "RECURRING",
        "nameOnAccount": "Vegeta Prince"
      }
    },
    "channel": "ECOMMERCE",
    "billToAddress": {
      "firstName": "Vegeta",
      "lastName": "Prince",
      "address1": "123 Gravity Chamber",
      "city": "West City",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "USA"
    },
    "orderDetails": {
      "orderReference": "VAL-123",
      "customerDetails": {
        "email": "vegeta@capsulecorp.com",
        "phoneNumber": "555-0123"
      }
    }
  }
}

{
  "data": {
    "validateBankAccount": {
      "validateBankAccountResponse": {
        "transactionId": "02c5303b-4ab9-4696-b29a-b2ffdb7bc443",
        "paymentId": "bf1b019f-efdb-4818-9c6a-4fdd4161c00d",
        "processorResponseCode": "A0000",
        "validationProviderScore": 95,
        "isDuplicateRequest": false
      }
    }
  }
}

What is it? A validate bank account request checks the validity of a bank account without initiating any fund transfers. This can be used to verify account details before setting up future payments. When is it required? A validate bank account request is required on eCommerce bank transfers to comply with NACHA’s Supplementing Fraud Detection Standards for WEB Debits rule that became effective March 19, 2021. They’re optional on all other payment entry modes.

When to Use

You’re accepting eCommerce bank transfers and need to comply with NACHA rules.
You want to verify a bank account is valid before processing an ACH transaction.
You need to reduce the risk of bank transfer failures.

ScenarioBen wants to set up automatic payments from his checking account for a monthly subscription to Maple Street Coffee, one of Clearpath Payment’s acceptors. Before processing any transactions, Clearpath Payments validates Ben’s bank account to ensure it’s active and properly configured.

Steps

Call the validateBankAccount mutation, passing in the required and optional input fields:

Required input	Description
`acceptorId`	The unique, 36 character identifier assigned to the entity providing the goods or services to the customer. Other processors may refer to this as the Merchant ID (MID), Outlet ID, or Customer number.
`transactionReference`	The unique transaction identifier created by YOU to distinguish this transaction from another.
`paymentMethodDetails`	The bank account details or token to be validated.

The response will include a validationProviderScore which indicates the confidence level in the account’s validity. This score ranges from 0 to 1000, with higher scores indicating greater confidence.

Payment method details

You can provide bank account details in one of two ways:

Direct bank account details:

bankAccountDetails: {
  routingNumber: "123456789"
  accountNumber: "12345678"
  bankAccountType: SAVINGS
  accountOwnerType: CONSUMER
  paymentEntryMode: ECOMMERCE
  recurringType: RECURRING
  nameOnAccount: "Goku Son"
}

Using a previously tokenized bank account:

acquirerTokenDetails: {
  token: "previously-generated-token"
}

Bank account types

When providing direct bank account details, specify:

bankAccountType:
- CHECKING: A checking account for day-to-day transactions
- SAVINGS: A savings account with potential withdrawal limitations
accountOwnerType:
- CONSUMER: Individual/personal accounts
- CORPORATE: Business accounts

Channel

For consumer interaction method, specify:

channel:
- ECOMMERCE: Customer interacts through online interface
- MAIL_ORDER_TELEPHONE_ORDER: Customer interacts through mail, phone, or fax

Entry modes

Indicates how the bank account information was collected:

paymentEntryMode:
- KEYED: Manually entered
- ON_FILE: Retrieved from stored credentials

Note: For online (ECOMMERCE) or telephone entries, use the channel parameter with values ECOMMERCE or MAIL_ORDER_TELEPHONE_ORDER respectively.

Recurring type

For payment frequency, specify:

recurringType:
- SINGLE: One-time payments with no future transactions expected
- RECURRING: Subscription payments, recurring bills, or installment payments

mutation ValidateBankAccount($input: ValidateBankAccountInput!) {
  validateBankAccount(validateBankAccountInput: $input) {
    validateBankAccountResponse {
      ... on ValidateBankAccountApproval {
        transactionId
        paymentId
        processorResponseCode
        validationProviderScore
        isDuplicateRequest
      }
      ... on ValidateBankAccountDecline {
        message
        processorAdvice
        declineType
        validationProviderScore
        transactionId
      }
    }
    errors {
      errorType: __typename
      ... on ValidationFailureError {
        message
        fieldPath
      }
      ... on RouteNotFoundError {
        message
      }
      ... on AcceptorNotFoundError {
        message
      }
    }
  }
}

{
  "input": {
    "acceptorId": "05a39b14-f29f-443b-a107-da3e3e8969fb",
    "transactionReference": "68448abe-735b-4ee3-af14-d0f50a091c9b",
    "paymentMethodDetails": {
      "bankAccountDetails": {
        "routingNumber": "123456789",
        "accountNumber": "12345678",
        "bankAccountType": "SAVINGS",
        "accountOwnerType": "CONSUMER",
        "paymentEntryMode": "KEYED",
        "recurringType": "RECURRING",
        "nameOnAccount": "Vegeta Prince"
      }
    },
    "channel": "ECOMMERCE",
    "billToAddress": {
      "firstName": "Vegeta",
      "lastName": "Prince",
      "address1": "123 Gravity Chamber",
      "city": "West City",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "USA"
    },
    "orderDetails": {
      "orderReference": "VAL-123",
      "customerDetails": {
        "email": "vegeta@capsulecorp.com",
        "phoneNumber": "555-0123"
      }
    }
  }
}

{
  "data": {
    "validateBankAccount": {
      "validateBankAccountResponse": {
        "transactionId": "02c5303b-4ab9-4696-b29a-b2ffdb7bc443",
        "paymentId": "bf1b019f-efdb-4818-9c6a-4fdd4161c00d",
        "processorResponseCode": "A0000",
        "validationProviderScore": 95,
        "isDuplicateRequest": false
      }
    }
  }
}

Initiate a bank transfer Reinitiate a bank transfer

⌘I

Card transactions

Bank transfers

Managing fees

Validate a bank account

Steps

Payment method details

Bank account types

Channel

Entry modes

Recurring type

​Steps

​Payment method details

​Bank account types

​Channel

​Entry modes

​Recurring type

Steps

Payment method details

Bank account types

Channel

Entry modes

Recurring type