Forage Card Details API

openapi: 3.2.0
info:
  title: Forage Payments Card Details API
  description: The Forage Payments API is a REST API for processing Electronic Benefits Transfer (EBT) payments (SNAP and EBT Cash) in your e-commerce or in-store application.
  contact:
    name: API Support
    email: engineering@joinforage.com
  version: '2025-08-04'
servers:
- url: https://{environment}.joinforage.app
  variables:
    environment:
      default: api.sandbox
      enum:
      - api
      - api.sandbox
security: []
tags:
- name: Card Details
paths:
  /api/state_card_details:
    get:
      parameters:
      - $ref: '#/components/parameters/BearerTokenHeader'
      summary: Retrieve state card details
      description: 'This endpoint returns a predefined list of U.S. states, associated card BINs, and acceptable PAN (Primary Account Number) lengths. The data is static and designed for consumption by SDKs and partner integrations to facilitate client-side validation of state-specific card details.


        Each entry in the response includes a two-letter state code, the corresponding BIN, and an array of valid PAN lengths for that state.


        This endpoint is particularly useful for ensuring consistency and accuracy in front-end validation processes.'
      operationId: RetrieveStateCardDetails
      security:
      - OAuth2:
        - internal
        - pinpad_only
        - hosted_checkout
        - reporting
      tags:
      - Card Details
      responses:
        '200':
          description: A list of state card details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        state:
                          type: string
                          description: Two-letter state code (e.g., "MA" for Massachusetts), as defined by USPS.
                        bin:
                          type: string
                          description: A unique identifier that helps determine the issuer of a payment card and guides how transactions are processed.
                        pan_lengths:
                          type: array
                          items:
                            type: integer
                          description: A list of acceptable PAN lengths for the state.
              example:
              - state: MA
                bin: '600528'
                pan_lengths:
                - 16
                - 19
              - state: NJ
                bin: '610434'
                pan_lengths:
                - 16
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
      x-operation-id-source: normalized
      x-operation-id-original: Retrieve state card details
components:
  schemas:
    ErrorResponseObject:
      type: object
      description: An object that includes details about the error.
      properties:
        path:
          type: string
          description: The requested endpoint.
        errors:
          $ref: '#/components/schemas/ErrorsArray'
    ErrorsArray:
      type: array
      description: An array with information about the error.
      items:
        type: object
        properties:
          code:
            type: string
            description: A short string that represents the error.
          message:
            type: string
            description: A developer-facing message with more details about the error, not to be displayed to customers.
          source:
            type: object
            properties:
              resource:
                type: string
                description: The type of the Forage resource involved in the error.
              ref:
                type: string
                description: If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved.
          details:
            type: object
            description: Additional details about the error, if applicable.
      example: []
  responses:
    Error500:
      description: __Server Errors__ Something went wrong on Forage's servers. Try again.
    Error401:
      description: __Unauthorized__ Missing valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseObject'
  parameters:
    BearerTokenHeader:
      name: Authorization
      in: header
      description: An OAuth 2.0 bearer token that validates the request. You can use either a short-lived [session token](https://docs.joinforage.app/docs/authentication#session-tokens) if the request is coming from the front-end, or an [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) for server-side requests. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer <api_key>`.
      schema:
        type: string
      required: true
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'Pass the access token in the ''Authorization'' header with the format "Bearer ${token}", i.e. the word "Bearer" and your access token from the /o/token/ API, separated by whitespace.

        '
      flows:
        password:
          tokenUrl: /o/token/
          scopes:
            hosted_checkout: 'Scope for tokens used by merchant applications which allow Forage to manage split tender processing (i.e. EBT + Credit/Debit).

              '
            pinpad_only: 'Scope for tokens used by merchant applications which manage their own split tender (i.e. Forage Checkout is used only for EBT processing).

              '
        clientCredentials:
          tokenUrl: /o/token/
          scopes:
            internal: 'Scope for tokens used by Forage internal applications.

              '
            pin-protected: 'Scope for tokens which can access secure storage.

              '
            disbursement: 'Scope for tokens which can disburse money to merchants.

              '
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass the access token in the ''Authorization'' header with the format "Bearer ${token}", i.e. the word "Bearer" and your JWT bearer token from the /api/session_token/ end-point, separated by whitespace.

        '
externalDocs:
  description: Forage documentation
  url: https://docs.joinforage.app/
x-provenance:
  method: searched
  source: https://docs.joinforage.app/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.joinforage.app/reference/authorize-a-payment.md
  - https://docs.joinforage.app/reference/bulk-revoke-auth-tokens.md
  - https://docs.joinforage.app/reference/cancel-a-payment.md
  - https://docs.joinforage.app/reference/cancel-an-order-payment.md
  - https://docs.joinforage.app/reference/cancel-order.md
  - https://docs.joinforage.app/reference/capture-a-payment-during-sandbox-testing.md
  - https://docs.joinforage.app/reference/capture-a-payment.md
  - https://docs.joinforage.app/reference/create-a-payment.md
  - https://docs.joinforage.app/reference/create-authentication-token.md
  - https://docs.joinforage.app/reference/create-capture-session.md
  - https://docs.joinforage.app/reference/create-custom-balance-check-session.md
  - https://docs.joinforage.app/reference/create-payment-method.md
  - https://docs.joinforage.app/reference/create-payment-refund.md
  - https://docs.joinforage.app/reference/create-refunds-by-product.md
  - https://docs.joinforage.app/reference/create-session-token.md
  - https://docs.joinforage.app/reference/create-session.md
  - https://docs.joinforage.app/reference/delete-payment-method.md
  - https://docs.joinforage.app/reference/get-a-payment-refund.md
  - https://docs.joinforage.app/reference/get-all-order-refunds.md
  - https://docs.joinforage.app/reference/get-all-payment-refunds.md
  - https://docs.joinforage.app/reference/get-all-payments.md
  - https://docs.joinforage.app/reference/get-an-order-payment.md
  - https://docs.joinforage.app/reference/get-an-order-refund.md
  - https://docs.joinforage.app/reference/get-order-report.md
  - https://docs.joinforage.app/reference/get-order.md
  - https://docs.joinforage.app/reference/get-payment-details.md
  - https://docs.joinforage.app/reference/get-payment-method.md
  - https://docs.joinforage.app/reference/get-payout-report.md
  - https://docs.joinforage.app/reference/get-payout-transaction-report.md
  - https://docs.joinforage.app/reference/get-transaction-report.md
  - https://docs.joinforage.app/reference/patch-update-an-order-payment.md
  - https://docs.joinforage.app/reference/refund-entire-order.md
  - https://docs.joinforage.app/reference/refund-partial-order.md
  - https://docs.joinforage.app/reference/retrieve-all-payments-for-merchant-order-id.md
  - https://docs.joinforage.app/reference/retrieve-state-card-details.md
  - https://docs.joinforage.app/reference/revoke-authentication-token.md
  - https://docs.joinforage.app/reference/submit-pin-during-sandbox-testing.md
  - https://docs.joinforage.app/reference/update-a-payment.md
  - https://docs.joinforage.app/reference/update-order.md
  - https://docs.joinforage.app/reference/update-payment-method.md
  - https://docs.joinforage.app/reference/view-balance-session.md
  - https://docs.joinforage.app/reference/void-a-payment-custom-checkout.md
  - https://docs.joinforage.app/reference/void-a-refund.md
  merge:
    pages: 43
    deduped: 461
    conflicts_kept_first: 0