Store a bank account

Prerequisites

A valid API key — see Obtain API credentials
The person's bank account details (routing number, account number, account type) and a customer_id

Step 1: Build the request

Field	Required	Description
`customer_id`	Yes	Your internal customer identifier
`nickname`	No	A friendly label (for example, "Business Checking")
`bank_account.routing_number`	Yes	9-digit ABA routing number
`bank_account.account_number`	Yes	Bank account number (4–17 digits)
`bank_account.account_type`	Yes	`checking` or `savings`
`bank_account.name`	Yes	Account holder name
`bank_account.email`	Yes	Account holder email

Step 2: Send the request

curl -X POST \
  https://api.dev.paradisegateway.net/v1/payment_tokens \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
    "nickname": "Business Checking",
    "bank_account": {
      "routing_number": "021000021",
      "account_number": "123456789012",
      "account_type": "checking",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Step 3: Handle the response

A 201 Created response returns the token and masked bank details.

{
  "payment_token": "PAYMENT_TOKEN-02LGEHBA0BZSPA6WRY1T3H4CD",
  "object": "payment_token",
  "type": "bank_account",
  "status": "active",
  "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
  "nickname": "Business Checking",
  "bank_account": {
    "last_four": "9012",
    "routing_number_last_four": "0021",
    "account_type": "checking"
  },
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

The response only contains masked details — the full account and routing numbers are never returned.

Bank account verification

Some use cases require verifying that the person owns the bank account before processing payments. Common verification methods include:

Method	How it works	Timeline
Micro-deposits	Two small deposits (for example, $0.05 and $0.12) are sent to the account. The person confirms the amounts.	2–3 business days
Instant verification	A third-party service confirms ownership in real time via bank login	Seconds

Token status during verification

If verification is required, the token status may be verification_pending until the person confirms ownership. Only active tokens can be used in transactions.

Token statuses for bank accounts

Status	Description	Can transact
`active`	Verified and ready	Yes
`verification_pending`	Awaiting verification	No
`verification_failed`	Verification did not pass	No
`inactive`	Soft-deleted	No

Next steps

Process an ACH payment — use the token for a bank debit
Process an ACH payout — use the token for a bank credit
Update stored payment method
About ACH/bank account payments