Payment accounts

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

Last updated 1 month ago

List payment accounts

get

List all payment accounts

Authorizations

Query parameters

pageTokenstringOptional

Page token to fetch entries after

Example: abc

pageSizeinteger · min: 1 · max: 100Optional

Number of entries to fetch

Example: 10

customerIdstring · uuidRequired

Customer to list payment accounts for

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

Responses

200

Default Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

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-05-12T17:06:26.773Z",
      "externalBankAccount": {
        "bankAccountType": "CHECKING",
        "bankAccountOwnerName": "John Doe",
        "bankAccountOwnerEmail": "john@exmaple.com",
        "bankName": "Chase Bank",
        "bankAccountCurrency": "USD",
        "bankAccountMask": "***6789",
        "bankAccountPaymentMethod": "ACH"
      },
      "externalCryptoWallet": {
        "cryptoWalletType": "EVM",
        "chain": "base",
        "address": "0x1234567890123456789012345678901234567890"
      },
      "fernCryptoWallet": {
        "cryptoWalletType": "EVM",
        "address": "0x1234567890123456789012345678901234567890"
      },
      "isThirdParty": false
    }
  ],
  "nextPageToken": "xyz"
}

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

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-05-12T17:06:26.773Z",
  "externalBankAccount": {
    "bankAccountType": "CHECKING",
    "bankAccountOwnerName": "John Doe",
    "bankAccountOwnerEmail": "john@exmaple.com",
    "bankName": "Chase Bank",
    "bankAccountCurrency": "USD",
    "bankAccountMask": "***6789",
    "bankAccountPaymentMethod": "ACH"
  },
  "externalCryptoWallet": {
    "cryptoWalletType": "EVM",
    "chain": "base",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "fernCryptoWallet": {
    "cryptoWalletType": "EVM",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "isThirdParty": false
}

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:

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

isThirdPartybooleanOptional

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

Default: falseExample: false

Responses

201

Default Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

POST /payment-accounts HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Content-Type: application/json
Accept: */*
Content-Length: 1301

{
  "paymentAccountType": "EXTERNAL_BANK_ACCOUNT",
  "customerId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
  "nickname": "Savings Account",
  "externalBankAccount": {
    "accountNumber": "00123456789",
    "bankName": "Chase Bank",
    "bankAccountCurrency": "USD",
    "bankAddress": {
      "country": "US",
      "addressLine1": "350 5th Avenue",
      "addressLine2": "Floor 21",
      "city": "New York",
      "state": "NY",
      "postalCode": "10016",
      "locale": "en-US"
    },
    "bankAccountType": "CHECKING",
    "bankAccountPaymentMethod": "ACH",
    "bankAccountOwner": {
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "businessName": "Fern LLC",
      "address": {
        "country": "US",
        "addressLine1": "350 5th Avenue",
        "addressLine2": "Floor 21",
        "city": "New York",
        "state": "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",
    "nubanCode": "123456789012",
    "pixCode": "123456789",
    "clearingCode": "123456",
    "taxNumber": "123456789"
  },
  "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-05-12T17:06:26.773Z",
  "externalBankAccount": {
    "bankAccountType": "CHECKING",
    "bankAccountOwnerName": "John Doe",
    "bankAccountOwnerEmail": "john@exmaple.com",
    "bankName": "Chase Bank",
    "bankAccountCurrency": "USD",
    "bankAccountMask": "***6789",
    "bankAccountPaymentMethod": "ACH"
  },
  "externalCryptoWallet": {
    "cryptoWalletType": "EVM",
    "chain": "base",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "fernCryptoWallet": {
    "cryptoWalletType": "EVM",
    "address": "0x1234567890123456789012345678901234567890"
  },
  "isThirdParty": false,
  "bankAccountFormLink": "https://app.fernhq.com/bank_account/abc"
}