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

# List BINs

> The BINs your business can issue cards on, each with the binId that POST /cards takes. GET /bins. Requires cards:read scope.

## Overview

Returns every BIN on your account. Send a BIN's `binId` to [`POST /cards`](https://docs.fyatu.com/v3.20/api-reference/cards/create)
to issue a card on it. Only BINs with `issuable: true` can be issued on right now.

## Example

```bash cURL theme={null}
curl https://api.fyatu.com/api/v3.20/bins \
  -H "Authorization: Bearer $FYATU_API_KEY"
```

```javascript Node.js theme={null}
const resp = await fetch('https://api.fyatu.com/api/v3.20/bins', {
  headers: { Authorization: `Bearer ${process.env.FYATU_API_KEY}` },
});
const { data: bins } = await resp.json();
const binId = bins.find((b) => b.issuable && b.scheme === 'VISA')?.binId;
```

```python Python theme={null}
import os, requests

resp = requests.get(
    'https://api.fyatu.com/api/v3.20/bins',
    headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
)
bins = resp.json()['data']
bin_id = next(b['binId'] for b in bins if b['issuable'])
```

## Success Response (200)

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "BINs retrieved",
  "data": [
    {
      "binId": "TESTVISAV",
      "bin": "44444440",
      "name": "Test Visa Virtual",
      "scheme": "VISA",
      "issuingCountry": "US",
      "currency": "USD",
      "formFactor": "VIRTUAL",
      "category": "PREPAID",
      "issuable": true,
      "capabilities": {
        "applePay": false,
        "googlePay": false,
        "threeDS": true
      },
      "settings": {
        "reloadable": true,
        "maxCardsPerCardholder": 5,
        "cardValidityMonths": 36
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-11-15T10:00:00Z"
  }
}
```

## Response Fields

| Field | Type | Description |
| - | - | - |
| `binId` | string | The BIN ID to send as `binId` to `POST /cards` |
| `bin` | string \| null | The first digits every card on this BIN starts with |
| `name` | string | The BIN's name |
| `scheme` | string | `VISA` or `MASTERCARD` |
| `issuingCountry` | string \| null | Two-letter country the cards are issued in |
| `currency` | string | Card currency (`USD`) |
| `formFactor` | string | `VIRTUAL` |
| `category` | string | Card category, such as `PREPAID` |
| `issuable` | boolean | `true` when cards can be issued on this BIN right now |
| `capabilities.applePay` | boolean | Cards can be added to Apple Pay |
| `capabilities.googlePay` | boolean | Cards can be added to Google Pay |
| `capabilities.threeDS` | boolean | Cards support 3D Secure |
| `settings.reloadable` | boolean | Cards can be funded again after issuance |
| `settings.maxCardsPerCardholder` | integer \| null | Active cards one cardholder may hold on this BIN; `null` means no limit |
| `settings.cardValidityMonths` | integer \| null | How long its cards stay valid, in months |

The list is not paginated: every BIN on your account is returned in one response.

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `INSUFFICIENT_SCOPE` | 403 | Key lacks `cards:read` scope |
| `INTERNAL_ERROR` | 500 | Server error |


## OpenAPI

````yaml v3.20/openapi.json GET /bins
openapi: 3.1.0
info:
  title: FYATU CaaS API v3.20
  description: >-
    FYATU Cards-as-a-Service API â€” API key authentication, Cardholder
    lifecycle, Card issuance, Transactions, Webhooks, and Programs.
  version: 3.20.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://sandbox-api.fyatu.com/api/v3.20
    description: 'Public sandbox: free, test money only. Keys from sandbox.fyatu.com'
  - url: https://api.fyatu.com/api/v3.20
    description: >-
      Production. Keys from platform.fyatu.com; the key's environment (LIVE or
      SANDBOX) selects the data
security:
  - BearerAuth: []
tags:
  - name: Meta
    description: Liveness, account info, and supported event types
  - name: Account
    description: Account-level balance and funding status
  - name: Programs
    description: Read card program configuration
  - name: Cardholders
    description: Create and manage cardholder profiles
  - name: Cards
    description: Issue, fund, freeze, and terminate virtual cards
  - name: Transactions
    description: Read-only card transaction history
  - name: Webhooks
    description: Manage webhook endpoints for real-time event delivery
  - name: Products
    description: Read card product configurations
paths:
  /bins:
    get:
      tags:
        - Cards
      summary: List BINs
      description: >-
        The BINs your business can issue cards on, each with the `binId` that
        `POST /cards` takes. Requires `cards:read`.
      operationId: listBins
      responses:
        '200':
          description: BINs retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BinListResponse'
              example:
                success: true
                status: 200
                message: BINs retrieved
                data:
                  - binId: TESTVISAV
                    bin: '44444440'
                    name: Test Visa Virtual
                    scheme: VISA
                    issuingCountry: US
                    currency: USD
                    formFactor: VIRTUAL
                    category: PREPAID
                    issuable: true
                    capabilities:
                      applePay: false
                      googlePay: false
                      threeDS: true
                    settings:
                      reloadable: true
                      maxCardsPerCardholder: 5
                      cardValidityMonths: 36
                  - binId: TESTMCV
                    bin: '55555550'
                    name: Test Mastercard Virtual
                    scheme: MASTERCARD
                    issuingCountry: US
                    currency: USD
                    formFactor: VIRTUAL
                    category: PREPAID
                    issuable: true
                    capabilities:
                      applePay: false
                      googlePay: false
                      threeDS: true
                    settings:
                      reloadable: true
                      maxCardsPerCardholder: 5
                      cardValidityMonths: 36
                pagination:
                  total: 2
                  limit: 2
                  offset: 0
                  hasMore: false
                meta:
                  requestId: req_01HXY123456ABCDEF
                  platform: Fyatu CaaS
                  timestamp: '2026-11-15T10:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    BinListResponse:
      type: object
      properties:
        success:
          type: boolean
        status:
          type: integer
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Bin'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    Bin:
      type: object
      properties:
        binId:
          type: string
          description: >-
            The BIN ID to send as `binId` to `POST /cards`: letters and digits,
            no separators
          example: TESTVISAV
        bin:
          type: string
          nullable: true
          description: The first digits every card on this BIN starts with
          example: '44444440'
        name:
          type: string
          example: Test Visa Virtual
        scheme:
          type: string
          enum:
            - VISA
            - MASTERCARD
          example: VISA
        issuingCountry:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country the cards are issued in
          example: US
        currency:
          type: string
          example: USD
        formFactor:
          type: string
          example: VIRTUAL
        category:
          type: string
          example: PREPAID
        issuable:
          type: boolean
          description: '`true` when cards can be issued on this BIN right now'
        capabilities:
          type: object
          properties:
            applePay:
              type: boolean
            googlePay:
              type: boolean
            threeDS:
              type: boolean
        settings:
          type: object
          properties:
            reloadable:
              type: boolean
              description: Whether its cards can be funded again after issuance
            maxCardsPerCardholder:
              type: integer
              nullable: true
              description: >-
                Active cards one cardholder may hold on this BIN; `null` means
                no limit
            cardValidityMonths:
              type: integer
              nullable: true
              description: How long its cards stay valid, in months
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 47
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
        hasMore:
          type: boolean
          example: true
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6a7b8c9d0e1f2
        platform:
          type: string
          example: Fyatu CaaS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-22T15:00:00Z'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 422
        message:
          type: string
          example: Human readable message
        error:
          $ref: '#/components/schemas/ErrorBody'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        detail:
          type: string
          example: dateOfBirth must be in YYYY-MM-DD format
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: API key missing
              value:
                success: false
                status: 401
                message: API key is required
                error:
                  code: AUTH_TOKEN_MISSING
                  detail: API key is required
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
            invalid:
              summary: API key invalid
              value:
                success: false
                status: 401
                message: Invalid API key
                error:
                  code: AUTH_TOKEN_INVALID
                  detail: Invalid API key
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
    Forbidden:
      description: Scope denied or business suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 403
            message: Scope denied
            error:
              code: INSUFFICIENT_SCOPE
              detail: This endpoint requires the cards:write scope
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    RateLimitExceeded:
      description: >-
        Your business sent more requests in one second than its limit. Retry
        after `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying (always 1)
          schema:
            type: integer
            example: 1
        X-RateLimit-Limit:
          description: Your business's requests per second
          schema:
            type: integer
            example: 25
        X-RateLimit-Remaining:
          description: Requests left in the current second
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          description: Unix timestamp when the next second starts
          schema:
            type: integer
            example: 1763200801
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 429
            message: 'Rate limit exceeded: 25 requests per second'
            error:
              code: RATE_LIMIT_EXCEEDED
              detail: 'Rate limit exceeded: 25 requests per second'
            meta:
              requestId: req_01HXY123456ABCDEF
              platform: Fyatu CaaS
              timestamp: '2026-11-15T10:00:00Z'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 500
            message: Internal error
            error:
              code: INTERNAL_ERROR
              detail: An unexpected error occurred
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
        <key>`.

````

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