Bank account tokenization

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. 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.

Tokenize a bank account

Call POST /v1/tokenization/bankaccount/raw from your server.

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

{
  "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.

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:

"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:

{
  "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 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.

Get Started

Onboard Merchants

Accept Payments

Hosted Products

Payouts

Security & Operations

Bank account tokenization

Before you start

Tokenize a bank account

Request fields

Response

Use the token

Errors

Migrate from the deprecated endpoint

What’s next

Verification

ACH and eCheck

​Before you start

​Tokenize a bank account

​Request fields

​Response

​Use the token

​Errors

​Migrate from the deprecated endpoint

​What’s next

Verification

ACH and eCheck

Before you start

Tokenize a bank account

Request fields

Response

Use the token

Errors

Migrate from the deprecated endpoint

What’s next