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

# Bank Network Status

> How transfers to each Nigerian bank are going right now: usually instant, slow, having problems, or no recent data. Use it to warn your customer before they send to a bank that is struggling, or to explain a slow payout. It never blocks a payout. Answers are cached for 60 seconds; polling faster returns the same answer.

## Overview

How transfers to each Nigerian bank are going right now. When a bank is slow or having problems, tell your customer before they send, and let them choose: send anyway, or pay into another account. A status never blocks a payout.

| `level` | What it means | Suggested label |
| - | - | - |
| `green` | Transfers arrive as usual (`expected_minutes` is the typical time) | Usually instant, or "Usually \~N min" when `expected_minutes` is over 1 |
| `amber` | Slow right now; `expected_minutes` says how slow | Slow right now |
| `red` | Having problems; a transfer may be delayed | Having problems |
| `grey` | No recent transfer data | No recent data |

Show `message` to your customer as it is. It is written for them and never names a payment provider.

Pass `bank_code` for one bank, as you hold it: the code from [List banks](https://docs.platnova.com/api-reference/banks/list.md), or one saved on a beneficiary. `banks` is empty when we know nothing about that code. Without `bank_code` you get every bank we have a status for; a bank can appear under more than one code.

[Verify a bank account](https://docs.platnova.com/api-reference/banks/verify.md) returns the same object as `bank_status` for Nigerian accounts, so you can show it right after the account name.

## Caching

The status is recomputed every few minutes. Answers are cached for 60 seconds (`Cache-Control: public, max-age=60`), so polling more often than once a minute returns the same answer. A status older than 10 minutes is reported as `grey`.

If the status can't be read, the endpoint answers 503. Treat that as "no status" and carry on with the payout.


## OpenAPI

````yaml GET /v1/banks/status
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
  description: >-
    Platnova's Business API: collect payments with hosted checkout, issue
    virtual accounts and cards, send payouts, and receive webhooks.


    # Authentication


    Send your API key in the `X-API-Key` header on every request. Do not send it
    as `Authorization: Bearer`, and do not send a dashboard session token
    alongside it. The `api_key` query parameter is deprecated.


    # Base URLs


    - Live: https://api.platnova.com

    - Sandbox: https://sandbox.api.platnova.co


    # Errors


    Most responses are `{status: boolean, data, error: [], message}`; branch on
    the HTTP status and `data.code`. Validation failures are HTTP 422 `{status:
    "error", message: "Validation failed", errors: {field: [messages]}}`. A
    missing or invalid key is 401 `un-authorized access`. See
    https://docs.platnova.com/errors.
servers:
  - url: https://api.platnova.com
    description: Production server
  - url: https://sandbox.api.platnova.co
    description: Development server
security:
  - apiKeyAuth: []
tags:
  - name: Customer
    description: Create and manage customers
  - name: Virtual Account
    description: Create and manage virtual accounts
  - name: Card
    description: Create and manage cards
  - name: Wallet
    description: List and manage wallets
  - name: Payment
    description: Send and verify payments
  - name: Transaction
    description: List transactions and generate receipts
  - name: Checkout
    description: Create and retrieve checkout sessions
  - name: Payment Link
    description: Create and manage payment links
  - name: Invoice
    description: Create and manage invoices
  - name: Bank
    description: Bank lists and account verification for bank transfers
  - name: Bills
    description: Betting wallet top-ups
  - name: Refunds
paths:
  /v1/banks/status:
    get:
      tags:
        - Bank
      summary: Bank network status
      description: >-
        How transfers to each Nigerian bank are going right now: usually
        instant, slow, having problems, or no recent data. Use it to warn your
        customer before they send to a bank that is struggling, or to explain a
        slow payout. It never blocks a payout. Answers are cached for 60
        seconds; polling faster returns the same answer.
      operationId: getBankNetworkStatus
      parameters:
        - name: bank_code
          in: query
          required: false
          description: >-
            One bank's code, as you hold it (from List banks or a beneficiary
            you saved). Omit it for every bank.
          schema:
            type: string
            maxLength: 16
          example: '000015'
      responses:
        '200':
          description: >-
            Status of every bank, or of the one asked for. `banks` is empty when
            we know nothing of that code.
          headers:
            Cache-Control:
              description: Always `public, max-age=60`
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    type: object
                    properties:
                      as_of:
                        type:
                          - string
                          - 'null'
                        format: date-time
                        description: When the newest status in the answer was computed
                      banks:
                        type: array
                        items:
                          $ref: '#/components/schemas/BankStatus'
                  error:
                    type: array
                    items: {}
                  message:
                    type: string
                example:
                  status: true
                  data:
                    as_of: '2026-11-11T08:10:00Z'
                    banks:
                      - bank_code: '000015'
                        bank_name: Zenith Bank
                        level: amber
                        message: >-
                          Zenith Bank is slow right now. Transfers are taking
                          about 8 minutes.
                        expected_minutes: 8
                        as_of: '2026-11-11T08:10:00Z'
                  error: []
                  message: operation was successful
        '400':
          description: bank_code is longer than any bank code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Status could not be read just now; try again in a minute. Never a
            reason to hold a payout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BankStatus:
      type: object
      description: >-
        How transfers to one bank are going right now. Show `message` to your
        customer as it is; it never names a payment provider. A warning never
        blocks a payout: you decide whether to send.
      properties:
        bank_code:
          type: string
          description: The code you asked about
          example: '000015'
        bank_name:
          type: string
          example: Zenith Bank
        level:
          type: string
          enum:
            - green
            - amber
            - red
            - grey
          description: >-
            green: transfers arrive as usual. amber: slow right now. red: having
            problems; a transfer may be delayed. grey: no recent transfer data.
        message:
          type: string
          description: One sentence for your customer
          example: Zenith Bank is slow right now. Transfers are taking about 8 minutes.
        expected_minutes:
          type:
            - integer
            - 'null'
          description: Typical arrival time in minutes; null for red and grey
          example: 8
        as_of:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When this status was computed; null when we hold no data for the
            bank
      required:
        - bank_code
        - bank_name
        - level
        - message
        - expected_minutes
        - as_of
    Error:
      type: object
      properties:
        status:
          type: boolean
          example: false
        data:
          type: object
          description: Often empty. On coded errors holds `code` and details.
          properties:
            code:
              type: string
              example: request_in_progress
        error:
          type: array
          items:
            type: string
        message:
          type: string
          description: For people; don't parse.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication.

````

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