> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jupico.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bank account tokenization

> Exchange a customer's bank account and routing numbers for a permanent Jupico token that you can use on eCheck sales.

Bank account tokenization replaces a customer's account and routing numbers with a Jupico token. You send the token on eCheck sales instead of the bank details.

You can tokenize a bank account in two ways:

| Option | Where the bank data goes | Use it when |
| - | - | - |
| Bank account web component (`<echeck-form>`) | Straight from the browser to Jupico | You collect bank details in your own checkout |
| Bank account tokenization API | Through your servers to Jupico | You already hold the bank details on your servers |

For the web component, see [ACH and eCheck](https://docs.jupico.com/docs/payments/ach-echeck.md). The rest of this page covers the API.

## Before you start

* Bank account tokenization must be enabled for your product and for the submerchant. Ask your Jupico contact to enable it.
* The submerchant must be active.
* Authenticate with your API user, as for any other platform call. See [Authentication](https://docs.jupico.com/api-reference/authentication.md).

## Tokenize a bank account

Call [`POST /v1/tokenization/bankaccount/raw`](https://docs.jupico.com/api-reference/tokenization/tokenize-raw-bank-account-data) from your server.

```bash theme={null}
curl --location 'https://sandbox-platform.jupico.com/v1/tokenization/bankaccount/raw' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <base64 of apiUser:password>' \
  --data '{
    "subMerchantId": "jpt-sim-md-1",
    "accountType": "checking",
    "accountHolderName": "John Doe",
    "accountNumber": "12312311",
    "routingNumber": "122187238"
  }'
```

### Request fields

All fields are required. The endpoint rejects any other field with `invalid_payload`.

| Field | Type | Rules |
| - | - | - |
| `subMerchantId` | string | Submerchant that owns the bank account. Up to 100 characters. |
| `accountType` | string | `checking` or `savings`. |
| `accountHolderName` | string | Name on the account, up to 100 characters. Can be a person or a business. Letters, digits, spaces, and `- _ ' . , @ & : # % ( )` only. Accents are removed before the check, so `José` is stored as `Jose`. |
| `accountNumber` | string | 4 to 17 digits. |
| `routingNumber` | string | 9-digit ABA routing number. |

### Response

```json theme={null}
{
  "success": true,
  "code": "0",
  "message": "Tokenization success",
  "data": {
    "paymentToken": {
      "type": "echeck",
      "token": {
        "provider": "jupico",
        "token": "8b728fb4-976c-43c1-8402-04c23ac18861",
        "accountType": "checking",
        "routingLast4Digits": "7238",
        "accountLast4Digits": "2311",
        "accountHolderName": "John Doe"
      }
    }
  }
}
```

The token is permanent. Store it with the customer record and keep it on your backend.

> [!NOTE]
>
> Tokenizing the same account number, routing number, and account type again returns the existing token. The response shows the details stored when the token was first created, including the original `accountHolderName`.

## Use the token

Send the whole `paymentToken` object on an [eCheck sale](https://docs.jupico.com/api-reference/echeck-transactions/process-an-echeck-sale.md):

```json theme={null}
"paymentToken": {
  "type": "echeck",
  "token": {
    "provider": "jupico",
    "token": "8b728fb4-976c-43c1-8402-04c23ac18861"
  }
}
```

## Errors

Errors return `success: false` with a `code` and a `message`.

| HTTP | Code | Cause |
| - | - | - |
| `400` | `invalid_payload` | A field is missing or invalid, or the body includes a field this endpoint doesn't accept. The `errors` array lists each field (`path`) and the rule it broke (`msg`). |
| `401` | `auth_invalid_submerchant` | `subMerchantId` doesn't exist or isn't active. |
| `401` | `auth_submerchant_disabled` | The submerchant is disabled. |
| `401` | `auth_invalid_product` | The submerchant belongs to another product, or your product isn't active. |
| `401` | `auth_service_provider_feature_disabled` | Bank account tokenization isn't enabled for your product. |
| `401` | `auth_submerchant_feature_disabled` | Bank account tokenization isn't enabled for the submerchant. |
| `401` | `auth_invalid_role` | Your API user isn't allowed to call this endpoint. |
| `500` | `internal_server_error` | Something went wrong on Jupico's side. Retry later. |

Example of a validation error:

```json theme={null}
{
  "success": false,
  "message": "Invalid payload.",
  "code": "invalid_payload",
  "errors": [
    {
      "type": "field",
      "msg": "routingNumber must be a valid routing number",
      "path": "routingNumber",
      "location": "body"
    }
  ]
}
```

See [Error handling](https://docs.jupico.com/api-reference/error-handling.md) for how to handle each HTTP status.

## Migrate from the deprecated endpoint

`POST /v1/transactions/echeck/tokenize` is deprecated. Move to `POST /v1/tokenization/bankaccount/raw`. The response is the same. The request differs:

| | Deprecated `/v1/transactions/echeck/tokenize` | New `/v1/tokenization/bankaccount/raw` |
| - | - | - |
| `subMerchantId` | Optional | Required |
| `alias` | Optional | Not accepted. Sending it returns `invalid_payload`. |
| Feature check | None | Bank account tokenization must be enabled for the product and submerchant |
| `accountHolderName` | Accents rejected | Accents removed before the check |

Tokens from the deprecated endpoint keep working. If you tokenize the same account on the new endpoint, you get the same token back.

## What's next

> [card] [Verification](https://docs.jupico.com/docs/payments/bank-account/verification.md)
>
> Check a bank account before you debit it. Coming soon.

> [card] [ACH and eCheck](https://docs.jupico.com/docs/payments/ach-echeck.md)
>
> Collect bank details in the browser and run eCheck sales.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.