openapi: 3.0.3
info:
  title: Astrada bank-accounts bin-lookup API
  version: '2024-02-28'
  contact:
    email: developer@astrada.co
  description: 'Welcome to our API Reference. 👋

    '
servers:
- url: https://api.astrada.co
security: null
tags:
- name: bin-lookup
  description: BIN Lookup
paths:
  /bin-lookup:
    parameters:
    - $ref: '#/components/parameters/bin-required'
    get:
      tags:
      - bin-lookup
      summary: Lookup card information by BIN
      description: Retrieve card information such as network, type, and issuing bank by providing the card's BIN (Bank Identification Number).
      security:
      - main-auth:
        - cards:read
      operationId: BinLookup
      responses:
        '200':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/bin-lookup'
              examples:
                Example Bin Lookup Response:
                  $ref: '#/components/examples/bin-lookup'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/server-error'
components:
  schemas:
    bin-lookup:
      type: object
      properties:
        bin:
          type: string
          description: The Bank Identification Number (BIN) of the card
          example: '411111'
        network:
          type: string
          description: The card network (e.g., VISA, MASTERCARD, AMEX)
          example: VISA
        type:
          type: string
          description: The card type (e.g., COMMERCIAL, CORPORATE, CONSUMER, SMALL_BUSINESS )
          enum:
          - COMMERCIAL
          - CORPORATE
          - CONSUMER
          - SMALL_BUSINESS
        fundingType:
          type: string
          description: The card funding type (e.g., prepaid, debit, credit)
          enum:
          - CREDIT
          - DEBIT
          - PREPAID
        issuerName:
          type: string
          description: The name of the issuing bank
          example: Bank of America
        issuerCountry:
          type: string
          description: The country of the issuing bank following ISO 3166 alpha-3
          example: USA
        issuerRegion:
          type: string
          description: The region of the issuing bank
          example: NA, LATAM, EMEA, APAC
      required:
      - bin
      - network
      - fundingType
  responses:
    not-found:
      description: The requested resource was not found on the server
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
              instance:
                type: string
              detail:
                type: string
              title:
                type: string
                enum:
                - Not Found
            required:
            - detail
            - title
          example:
            title: Not Found
            detail: The requested resource was not found on the server.
    unauthorized:
      description: Authentication credentials were either missing or incorrect
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Unauthorized
            required:
            - detail
            - title
          example:
            title: Unauthorized
            detail: Authentication credentials were either missing or incorrect.
    forbidden:
      description: Authentication credentials used do not have have permissions to perform the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Forbidden
            required:
            - detail
            - title
          example:
            title: Forbidden
            detail: You do not have permission to access the requested resource.
    server-error:
      description: The server encountered an unexpected condition that prevented it from fulfilling the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Internal Server Error
            required:
            - detail
            - title
          example:
            title: Internal Server Error
            detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
    bad-request:
      description: The server cannot or will not process the request due to something that is perceived to be a client error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Bad Request
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    detail:
                      type: string
                  required:
                  - title
                  - detail
            required:
            - detail
            - title
          examples:
            Example Generic Bad Request Payload Response:
              value:
                title: Bad Request
                detail: Request object failed validation.
            Example Generic Bad Request Parameters Response:
              value:
                title: Bad Request
                detail: Request parameters are invalid.
  parameters:
    bin-required:
      in: query
      name: bin
      required: true
      schema:
        type: string
        pattern: ^\d{6,11}$
      description: The card's Bank Identification Number (BIN), consisting of the first 6 to 11 digits of the card number.
  examples:
    bin-lookup:
      description: Example response for BIN lookup request
      value:
        bin: '411111'
        network: VISA
        type: COMMERCIAL
        fundingType: CREDIT
        issuerName: Example Bank
        issuerCountry: USA
        issuerRegion: NA
  securitySchemes:
    main-auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          scopes:
            accounts:write: Accounts write resource
            accounts:read: Accounts read resource
            subaccounts:write: Subaccounts write resource
            subaccounts:read: Subaccounts read resource
            card-connector-data-links:write: card-connector-data-link resource
            card-connector-consents:read: Card Consent read resource
            card-connector-consents:write: Card Consent write resource
            webhooks:read: Read Webhook resources
            webhooks:write: Write Webhook resources
            card-subscriptions:write: Create card subscription
            card-subscriptions:read: Read card subscription
            card-verifications:write: Create card verification
            card-verifications:read: Read Card verification
            cards:read: Read Card resources
            cardholder:read: Read Cardholder resources
            cardholder:write: Write Cardholder resources
            transactions:read: Read Transaction resources
            transaction-messages:read: Read Transaction Message resources
            network-bulk-feeds:read: Read network bulk feed
            network-bulk-feeds:write: Write network bulk feed
            network-links:write: Write network link
            enrollment-methods:write: Write enrollment methods
            simulation:write: Write sandbox simulations
            banking:read: Read banking resources
            banking:write: Write banking resources
            banking:admin: Admin banking operations
            appstore:enrollment:write: Enroll cards via the appstore B2C flow
            appstore:cards:read: View enrolled cards in the appstore
            appstore:transactions:read: View synced transactions in the appstore
            appstore:transactions:sync: Trigger transaction sync in the appstore
            appstore:sessions:read: Read appstore session state
            appstore:sessions:write: Write or delete appstore session state
            appstore:tokens:read: Read appstore stored tokens and connections
            appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
  description: Find out more about Astrada API.
  url: https://docs.astrada.co/reference