Skip to main content

Process Bank Payments

Storing your customers' bank accounts with Basis Theory platform grants you the ability to seamlessly shift between payment processors, giving you competitive advantages including payment flexibility, reliability, cost savings, increased acceptance rates, and future-proofing your business against processor downtime or shutdown.

This guide will explore how to forward stored bank account information to any third-party API endpoint, with minimal configuration requirements. The steps below take into consideration NACHA's sensitive financial information requirements related to Data Security, Data Transmission, Audit Trails and Access Controls.

Process Bank Payments Flowchart

If you are not yet storing your customers' bank accounts with Basis Theory, here are a few guides you can explore:

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Make sure to use your work email (e.g., john.doe@yourcompany.com)

Creating a Private Application​

Next, you will need a Private Application using our NACHA-compliant template Use Bank Tokens. Click here to create one.

This will create an application with the following Access Controls:

  • Permissions: token:use
  • Containers: /bank/
  • Transform: reveal
Save the API Key from the created Private Application as it will be used in the next steps of this guide.

Send the Data​

We will use Basis Theory Ephemeral Proxy, a tool that transparently performs detokenization, to share the sensitive banking data with the Payments Processor or Acquirer API. To do this, we will formulate our HTTPS request as if we were directly connecting to the target endpoint, with the following variations:

  1. Use the previously-created Private Application Key as the value of the BT-API-KEY header;
  2. Specify the target API endpoint as the value for the BT-PROXY-URL header;
  3. Pass any additional headers you need the target API to receive, for example Authorization, X-API-KEY, etc.;
  4. Replace the plaintext sensitive account information in the expected payload contents with detokenization expressions that contain token identifiers.

For example, given you have a previously stored bank token with the following identifier:

{
  "id": "f910b9aa-a4a6-4f24-9ec4-2de1a5731d0b",
  "type": "bank",
  "tenantId": "4aee08b9-5557-474b-a120-252e01fc7b0f",
  "data": {
    "routing_number": "021000021",
    "account_number": "XXXXX3123"
  },
  "createdBy": "f5c44560-8433-4dcc-b67f-53594c397a5e",
  "createdAt": "2023-10-26T14:27:10.6126956+00:00",
  "mask": {
    "routingNumber": "{{ data.routing_number }}",
    "accountNumber": "{{ data.account_number | reveal_last: 4 }}"
  },
  "privacy": {
    "classification": "bank",
    "impactLevel": "high",
    "restrictionPolicy": "mask"
  },
  "searchIndexes": [],
  "containers": [
    "/bank/high/"
  ]
}

Here are a few integration examples of how to send the detokenized banking information to third party APIs.

Create a Payment Method
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://api.stripe.com/v1/payment_methods' \
-H 'Authorization: Bearer sk_test_51KMGNYGuvJF9SIWEW0y4rKcaQwLVLck2rGB8UEPHzSp1utx7gXKAfZ3DVgjMfAuvBIT42pQhg0sIx2PepEJkXv9g00yIrUwhI4' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'type=us_bank_account' \
--data-urlencode 'us_bank_account[account_holder_type]=individual' \
--data-urlencode 'us_bank_account[routing_number]={{ f910b9aa-a4a6-4f24-9ec4-2de1a5731d0b | json: "$.routing_number" }}' \
--data-urlencode 'us_bank_account[account_number]={{ f910b9aa-a4a6-4f24-9ec4-2de1a5731d0b | json: "$.account_number" }}' \
--data-urlencode 'billing_details[name]=John Doe'

Stripe Payment Method Docs

Key Considerations​

You are not restricted to the Payment Processors listed above. As long as your partner can accept banking information through an API endpoint, you can invoke it using the Ephemeral Proxy.

If you find that the HTTPS response from your processor contains sensitive data, you can use a Pre-Configured Proxy to redact or tokenize the sensitive data points using a Response Transform.

It's important to note that for some acquirers, inbound connections are only accepted from whitelisted IP addresses provided by the client. To help with this, here you can find a compiled list of our IP addresses that you can send to your acquirer. In cases of more restrictive integrations, Basis Theory can provide dedicated IPs upon request. If you're interested in this option, please don't hesitate to contact us.

During testing phase, make sure to create tokens using test bank accounts documented by your payment processor, following the desired test scenario. Passing incorrect data to test/sandbox endpoints may lead to hard-to-debug rejected transactions.

Conclusion​

By using our Ephemeral Proxy, you can confidently transmit banking data to Payment Processors via API requests without ever touching the account details yourself. This approach not only improves security and reduces compliance risks but also provides the flexibility to establish your own relationships with Payment Processors and the latest payment technologies.

Learn More​