Skip to main content
Prerequisites: Before creating external bank accounts, ensure you have:
  • A verified Fern developer account with API key configured
  • An existing customer account with appropriate KYC verification
  • Valid bank account details from your customer

​
Overview

External bank accounts allow your customers to receive fiat payments directly to their existing bank accounts. This endpoint creates a payment account linked to an external bank account that your customer owns, supporting various payment methods including ACH, Wire transfers, SEPA, and many regional payment rails.

​
Account Types

Fern supports external bank accounts for different use cases: 1. Personal Bank Accounts: Individual customer accounts (checking, savings) 2. Business Bank Accounts: Corporate accounts with business verification 3. Multi-Currency Support: Bank accounts in various supported currencies (USD, EUR, GBP, etc.)
The API flow remains consistent across all account types - only the request parameters and validation requirements change.For more details on supported countries and currencies, check the Coverage: Countries & Currencies

​
Account Setup Flow

1

Verify Customer

Ensure customer exists with required KYC/KYB verification
2

Collect Bank Details

Gather bank account information and owner details securely
3

Create Payment Account

Submit bank account details via API
4

Handle Verification

Complete additional verification if account status is PENDING

​
Implementation Guide

​
Step 1: Prerequisites

Before creating an external bank account, ensure you have:
  1. Customer Account - Create a verified customer following the Customer Creation Guide
  2. Bank Account Details - Collect all required banking information from your customer
  3. Owner Information - Gather complete beneficiary details including address
Bank account validation requirements vary by country and currency. Ensure you collect the appropriate banking identifiers for the target region.

​
Step 2: Create External Bank Account

Submit the bank account details to create a new payment account. The system will validate the bank information and create either an active account or return a form link for additional verification.

​
Request

POST /v1/payment-accounts
// Reference: CreatePaymentAccountRequestSchema
{
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "customerId": "customer_uuid",
  "nickname": "Primary Checking Account",
  "externalBankAccount": {
    "bankName": "Wells Fargo NA",
    "bankAccountCurrency": "USD",
    "bankAccountType": "CHECKING",
    "bankAccountPaymentMethod": "WIRE",
    "routingNumber": "111111111",
    "accountNumber": "1111111111",
    "bankAccountOwner": {
      "email": "johndoe@example.com",
      "type": "PERSONAL",
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "addressLine1": "111 Hope St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      }
    },
    "bankAddress": {
      "addressLine1": "420 Montgomery Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94104",
      "country": "US"
    }
  }
}

​
Response

Active Account: 
// Reference: PaymentAccountResponseSchema
{
  "paymentAccountId": "11111111-2222-3333-4444-555555555555",
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "nickname": "Wells Fargo Checking", 
  "createdAt": "2025-10-30T12:00:00Z",
  "customerId": "ad995c64-28b7-47a3-a628-e21973597186",
  "paymentAccountStatus": "ACTIVE",
  "externalBankAccount": {
    // Reference: ExternalBankAccountResponseSchema
    "bankAccountType": "CHECKING",
    "bankAccountOwnerName": "John Doe",
    "bankAccountOwnerEmail": "johndoe@example.com", 
    "bankName": "Wells Fargo NA",
    "bankAccountCurrency": { "label": "USD" },
    "bankAccountMask": "***1111",
    "bankAccountPaymentMethod": "WIRE"
  },
  "isThirdParty": false
}
Pending with Form Link: 
// Reference: CreatePaymentAccountResponseSchema  
{
  "paymentAccountId": "11111111-2222-3333-4444-555555555555",
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "nickname": "Wells Fargo Checking",
  "customerId": "ad995c64-28b7-47a3-a628-e21973597186", 
  "paymentAccountStatus": "PENDING",
  "isThirdParty": false,
  "bankAccountFormLink": "https://forms.fernhq.com/payment-account/11111111-80fa-465f-8b95-040a6c6b7470"
}

​
Step 3: Handle Verification

When the account status is PENDING, direct your customer to complete additional verification:
1

Redirect to Form

Use the bankAccountFormLink to redirect customers to our hosted verification form
2

Monitor Status

Poll the Get Payment Account API or use webhooks to monitor status changes
3

Handle Completion

Once verification is complete, the account status will change to ACTIVE

​
Step 4: Use the Account

After the account is ACTIVE, you can:

​
Additional Information

​
Banking Identifiers

Different countries require specific banking identifiers. Include the appropriate fields based on your target region: 
{
  "routingNumber": "111000025",
  "accountNumber": "1234567890",
  "wireRoutingNumber": "026009593" // Optional, for wire transfers
}

{
  "sortCode": "123456",
  "accountNumber": "12345678",
  "iban": "GB29NWBK60161331926819" // Optional
}

{
  "iban": "DE89370400440532013000",
  "bicSwift": "COBADEFFXXX"
}

{
  "transitNumber": "12345",
  "institutionNumber": "111",
  "accountNumber": "1234567"
}

{
  "bsbNumber": "123-456",
  "accountNumber": "123456789"
}
India: ifscCode
Mexico: clabeNumber
China: cnapsCode
Nigeria: nubanNumber
Brazil: pixCode, taxNumber
Hong Kong: clearingCode

​
Webhooks

Set up webhooks to receive real-time notifications about account status changes:

API Reference

Complete payment accounts API documentation

Customer Creation

Guide for onboarding customers with verification

Transactions

Create and manage transactions to bank accounts

Supported Regions

Full list of supported countries and currencies

​
Support

Use the Support page to contact us.
Please include these details to help our team debug issues faster:
  • paymentAccountId
  • customerId
  • Error response (if any)
  • Target country/currency