Payment accounts

Use this API to add, update and get payment accounts for an existing customer.

Create payment account

post

Create an account for a customer

Authorizations
Body
paymentAccountTypeany ofRequired

Type of payment account to create

Example: EXTERNAL_BANK_ACCOUNT
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
customerIdstring · uuidRequired

Customer to create payment account

Example: 072a8b7b-38c7-429a-a6cf-35dae7f2fb77
nicknamestringOptional

Nickname for customer to use for the payment account

Example: Savings Account
organizationIdstring · uuidOptional

Organization to create payment account

Example: 24ab9fdd-5042-4d96-a616-4bef2877dd01
isThirdPartybooleanOptional

Whether the payment account is a third-party account. Defaults to false.

Default: falseExample: false
Responses
201
Default Response
application/json
post
POST /payment-accounts HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Content-Type: application/json
Accept: */*
Content-Length: 1555

{
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "customerId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
  "nickname": "Savings Account",
  "organizationId": "24ab9fdd-5042-4d96-a616-4bef2877dd01",
  "externalBankAccount": {
    "accountNumber": "00123456789",
    "bankName": "Chase Bank",
    "bankAccountCurrency": "USD",
    "bankAddress": {
      "country": "US",
      "addressLine1": "350 5th Avenue",
      "addressLine2": "Floor 21",
      "city": "New York",
      "state": "New York",
      "stateCode": "NY",
      "postalCode": "10016",
      "locale": "en-US"
    },
    "bankAccountType": "CHECKING",
    "bankAccountPaymentMethod": "ACH",
    "bankAccountOwner": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "businessName": "Fern LLC",
      "address": {
        "country": "US",
        "addressLine1": "350 5th Avenue",
        "addressLine2": "Floor 21",
        "city": "New York",
        "state": "New York",
        "stateCode": "NY",
        "postalCode": "10016",
        "locale": "en-US"
      },
      "type": "INDIVIDUAL"
    },
    "routingNumber": "11110000",
    "sortCode": "123456",
    "iban": "GB29NWBK60161331926819",
    "bicSwift": "SMCOGB2LXXX",
    "transitNumber": "12345",
    "institutionNumber": "111",
    "bsbNumber": "123-456",
    "ifscCode": "IFSC0001234",
    "clabeNumber": "123456789012345678",
    "bankCode": "123456",
    "cnapsCode": "123456789",
    "nubanNumber": "123456789012",
    "pixCode": "123456789",
    "clearingCode": "123456",
    "taxNumber": "123456789"
  },
  "fernAutoFiatAccount": {
    "bankAccountCurrency": "USD",
    "destinationPaymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
    "destinationCurrency": "USDC"
  },
  "externalCryptoWallet": {
    "cryptoWalletType": "EVM",
    "chain": "base",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "fernCryptoWallet": {
    "cryptoWalletType": "EVM"
  },
  "isThirdParty": false
}
{
  "paymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "nickname": "Savings Account",
  "createdAt": "2025-07-13T15:46:05.970Z",
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "externalBankAccount": {
    "bankAccountType": "CHECKING",
    "bankAccountOwnerName": "John Doe",
    "bankAccountOwnerEmail": "[email protected]",
    "bankName": "Chase Bank",
    "bankAccountCurrency": {
      "label": "text"
    },
    "bankAccountMask": "***6789",
    "bankAccountPaymentMethod": "ACH"
  },
  "fernAutoFiatAccount": {
    "bankAccountOwnerName": "John Doe",
    "bankName": "Chase Bank",
    "bankAccountCurrency": {
      "label": "text"
    },
    "bankAccountPaymentMethods": [
      "ACH",
      "WIRE"
    ],
    "bankAccountNumber": "12346789",
    "routingNumber": "12346789",
    "iban": "GB29NWBK60161331926819",
    "bicSwift": "SMCOGB2LXXX",
    "destinationPaymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
    "destinationCurrency": {
      "label": "USDC",
      "chain": "ETHEREUM",
      "contractAddress": "0x123456789abcd123456789abcd123456789abcd",
      "currencyDecimals": 18
    }
  },
  "externalCryptoWallet": {
    "cryptoWalletType": "EVM",
    "chain": "base",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "fernCryptoWallet": {
    "cryptoWalletType": "EVM",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "isThirdParty": false,
  "bankAccountFormLink": "https://app.fernhq.com/bank_account/abc"
}

Get payment account

get

Get details about a specific payment account

Authorizations
Path parameters
paymentAccountIdstring · uuidRequired

Unique identifier of the payment account

Example: 072a8b7b-38c7-429a-a6cf-35dae7f2fb77
Responses
200
Default Response
application/json
get
GET /payment-accounts/{paymentAccountId} HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

{
  "paymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "nickname": "Savings Account",
  "createdAt": "2025-07-13T15:46:05.970Z",
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "externalBankAccount": {
    "bankAccountType": "CHECKING",
    "bankAccountOwnerName": "John Doe",
    "bankAccountOwnerEmail": "[email protected]",
    "bankName": "Chase Bank",
    "bankAccountCurrency": {
      "label": "text"
    },
    "bankAccountMask": "***6789",
    "bankAccountPaymentMethod": "ACH"
  },
  "fernAutoFiatAccount": {
    "bankAccountOwnerName": "John Doe",
    "bankName": "Chase Bank",
    "bankAccountCurrency": {
      "label": "text"
    },
    "bankAccountPaymentMethods": [
      "ACH",
      "WIRE"
    ],
    "bankAccountNumber": "12346789",
    "routingNumber": "12346789",
    "iban": "GB29NWBK60161331926819",
    "bicSwift": "SMCOGB2LXXX",
    "destinationPaymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
    "destinationCurrency": {
      "label": "USDC",
      "chain": "ETHEREUM",
      "contractAddress": "0x123456789abcd123456789abcd123456789abcd",
      "currencyDecimals": 18
    }
  },
  "externalCryptoWallet": {
    "cryptoWalletType": "EVM",
    "chain": "base",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "fernCryptoWallet": {
    "cryptoWalletType": "EVM",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "isThirdParty": false
}

List payment accounts

get

List all payment accounts

Authorizations
Query parameters
pageTokenstringOptional

Token for forward pagination

Example: ZDE4YmViMjYtYjRkMS00N2VlLThlNWQtMGQzOTA1ZjIwMGM3
pageSizeinteger · min: 1Optional

Number of items per page (default: 10, max: 100)

Default: 10Example: 10
customerIdstring · uuidRequired

Customer to list payment accounts for

Example: 072a8b7b-38c7-429a-a6cf-35dae7f2fb77
Responses
200
Default Response
application/json
get
GET /payment-accounts HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

{
  "paymentAccounts": [
    {
      "paymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
      "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
      "nickname": "Savings Account",
      "createdAt": "2025-07-13T15:46:05.970Z",
      "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
      "externalBankAccount": {
        "bankAccountType": "CHECKING",
        "bankAccountOwnerName": "John Doe",
        "bankAccountOwnerEmail": "[email protected]",
        "bankName": "Chase Bank",
        "bankAccountCurrency": {
          "label": "text"
        },
        "bankAccountMask": "***6789",
        "bankAccountPaymentMethod": "ACH"
      },
      "fernAutoFiatAccount": {
        "bankAccountOwnerName": "John Doe",
        "bankName": "Chase Bank",
        "bankAccountCurrency": {
          "label": "text"
        },
        "bankAccountPaymentMethods": [
          "ACH",
          "WIRE"
        ],
        "bankAccountNumber": "12346789",
        "routingNumber": "12346789",
        "iban": "GB29NWBK60161331926819",
        "bicSwift": "SMCOGB2LXXX",
        "destinationPaymentAccountId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
        "destinationCurrency": {
          "label": "USDC",
          "chain": "ETHEREUM",
          "contractAddress": "0x123456789abcd123456789abcd123456789abcd",
          "currencyDecimals": 18
        }
      },
      "externalCryptoWallet": {
        "cryptoWalletType": "EVM",
        "chain": "base",
        "address": "0x1234567890123456789012345678901234567890"
      },
      "fernCryptoWallet": {
        "cryptoWalletType": "EVM",
        "address": "0x1234567890123456789012345678901234567890"
      },
      "isThirdParty": false
    }
  ],
  "nextPageToken": "xyz"
}

Get payment account balance

get

Get the balance of a payment account

Authorizations
Path parameters
paymentAccountIdstring · uuidRequired

Unique identifier of the payment account

Example: 072a8b7b-38c7-429a-a6cf-35dae7f2fb77
Query parameters
chainany ofRequired

The chain the wallet is on. case-sensitive

Example: BASE
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
or
string · enumOptionalPossible values:
currencystringRequired

The currency to get the balance for

Example: {"value":"USD"}
Responses
200
Default Response
application/json
get
GET /payment-accounts/{paymentAccountId}/balance HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

{
  "paymentAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
  "currency": {
    "label": "USDC",
    "chain": "base",
    "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "currencyDecimals": "18"
  },
  "balance": "1000.00",
  "usdValue": "1000.00"
}

Delete payment account

delete

Delete all details about a specific payment account

Authorizations
Path parameters
paymentAccountIdstring · uuidRequired

Unique identifier of the payment account

Example: 072a8b7b-38c7-429a-a6cf-35dae7f2fb77
Responses
200
Default Response
application/json
Responseany
delete
DELETE /payment-accounts/{paymentAccountId} HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

No content

Last updated