> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepay.global/llms.txt
> Use this file to discover all available pages before exploring further.

# List Bank Accounts

> List a user's bank accounts and see which one receives payouts

# List Bank Accounts

Returns every bank account on file for the user. Use it to see which account payouts go to (`isPrimary`) and to get the `id` you pass as `bankAccountId` on [Create Transaction](https://docs.stablepay.global/api-reference/transactions/create-transaction.md).

**userId** `string` *required*

The user ID

**externalId** `string`

Return only the account you registered with this `externalId` (your own identifier, set on [Verify Bank Account](https://docs.stablepay.global/api-reference/kyc/verify-bank.md)).

## Request

```bash theme={null}
curl https://api.stablepay.global/v2/users/usr_abc123/bank-accounts \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "3f2a9c14-6b0e-4d21-9a77-1c8e5b2f0d43",
      "instrumentId": "3f2a9c14-6b0e-4d21-9a77-1c8e5b2f0d43",
      "externalId": "pi_88213",
      "maskedAccountNumber": "XXXXXX7890",
      "ifsc": "HDFC0001234",
      "bankName": "HDFC Bank",
      "accountHolderName": "RAHUL KUMAR",
      "verified": true,
      "isPrimary": true,
      "createdAt": "2026-03-06T10:00:00.000Z"
    },
    {
      "id": "8b1d07e2-3c4f-4a90-b6d1-2e7f9a0c5b18",
      "instrumentId": "8b1d07e2-3c4f-4a90-b6d1-2e7f9a0c5b18",
      "externalId": "pi_90457",
      "maskedAccountNumber": "XXXXXX4412",
      "ifsc": "ICIC0000123",
      "bankName": "ICICI Bank",
      "accountHolderName": "RAHUL KUMAR",
      "verified": true,
      "isPrimary": false,
      "createdAt": "2026-03-09T08:30:00.000Z"
    }
  ]
}
```

`instrumentId` carries the same value as `id` under a currency-neutral name.

## Choosing where a payout goes

* **One payout:** pass `bankAccountId` on `POST /v2/transactions` (`pool_settlement`). Only that payout is affected.
* **All future payouts:** make the account primary with [Set Primary Bank Account](https://docs.stablepay.global/api-reference/users/set-primary-bank-account.md). Payouts without a `bankAccountId` go to the primary account.

## Errors

| `error` | Description |
| - | - |
| `Not Found` | User not found |
| `Internal Server Error` | Unexpected failure |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.