openapi: 3.2.0
info:
  description: REST API for communicating with Banyan's systems
  title: Banyan REST Transaction API
  version: 1.0.3
servers:
- url: https://api.banyan.com
security:
- bearerToken: []
tags:
- name: Transaction
paths:
  /v1/transaction:
    post:
      description: Submit multiple transactions for potential matching. See our Recommended Field List for more information about individual fields.
      operationId: submit-one-or-more-transactions
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/TransactionIngressJSON'
              type: array
        description: The transactions to submit.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PostTransactionIDJSON'
                    minItems: 1
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Mixed response containing the accepted transactions and errors for any transactions that had errors.
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PostTransactionIDJSON'
                    minItems: 1
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: All transactions accepted, contains the Banyan transaction ids of the accepted transactions.
        '400':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: The request was malformed.
        '401':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Bearer token expired or not correct.
        '403':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Partner does not have permissions for resource
        '408':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Request timeout
        '409':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: The request had a conflict.
        '413':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Request body is too large (4MiB limit)
        '500':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Internal server error
      summary: Submit one or more transactions
      tags:
      - Transaction
  /v1/transaction/{byn_transaction_id}:
    get:
      description: Get a transaction via its Banyan transaction ID
      operationId: fetch-a-transaction
      parameters:
      - description: The Banyan transaction ID to retrieve a transaction for.
        in: path
        name: byn_transaction_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/TransactionEgressJSON'
                    minItems: 1
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: The transaction.
        '400':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: The request was malformed.
        '401':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Bearer token expired or not correct.
        '403':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Partner does not have permissions for resource
        '404':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: The transaction was not found.
        '408':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Request timeout
        '413':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Request body is too large (4MiB limit)
        '500':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items: {}
                    maxItems: 0
                    type: array
                  errors:
                    items:
                      $ref: '#/components/schemas/ErrorJSON'
                    minItems: 1
                    type: array
                  request_id:
                    format: uuid
                    type: string
                required:
                - data
                - errors
                type: object
          description: Internal server error
      summary: Retrieve a Transaction
      tags:
      - Transaction
components:
  schemas:
    FieldTypesJSON:
      anyOf:
      - format: binary
        title: Binary Field
        type: string
      - title: Boolean Field
        type: boolean
      - format: binary
        maxLength: 1
        minLength: 1
        title: Byte Field
        type: string
      - title: Integer Field
        type: integer
      - format: int32
        title: Integer32 Field
        type: integer
      - format: int64
        title: Integer64 Field
        type: integer
      - format: double
        title: Double Field
        type: number
      - format: uuid
        title: Banyan ID
        type: string
      - format: uri
        title: URI
        type: string
      - format: date-time
        title: Timestamp
        type: string
      - format: decimal
        minLength: 1
        title: Amount
        type: string
    AddressIngressJSON:
      properties:
        address_line_one:
          description: For brick and mortar transactions only.
          example: 100 Main Street
          type: string
        address_line_two:
          description: For brick and mortar transactions only.
          example: Suite 100
          type: string
        city:
          description: For brick and mortar transactions only.
          example: Holmdel
          type: string
        country:
          description: For brick and mortar transactions only.
          example: USA
          type: string
        postal_code:
          description: For brick and mortar transactions only.
          example: '07733'
          type: string
        state:
          description: For brick and mortar transactions only.
          example: NJ
          type: string
      type: object
    TransactionIngressJSON:
      properties:
        authorization_ts:
          description: The time at which the transaction was authorized in RFC3339 format. UTC if possible.
          example: '2021-10-01T10:45:55Z'
          format: date-time
          type: string
        custom_fields:
          additionalProperties:
            type: string
          description: Set of custom fields set on the transaction.
          type: object
        description:
          description: Description of the transaction.
          example: Purchase of pickles at Tommy's Pickles.
          type: string
        finx_consumer_token:
          description: The merchant's token for the consumer.
          example: 5ASD32K2L34FA
          type: string
        finx_transaction_id:
          description: The finx's internal ID for the transaction.
          example: 5LA3LQKLR34L23L2
          type: string
        location:
          $ref: '#/components/schemas/LocationIngressJSON'
        merchant:
          $ref: '#/components/schemas/MerchantIngressJSON'
        order_type:
          $ref: '#/components/schemas/OrderType'
        payment:
          $ref: '#/components/schemas/TransactionPaymentIngressJSON'
        purchase_ts:
          description: The time at which purchase occurred in RFC3339 format. UTC if possible.
          example: '2021-10-01T10:45:55Z'
          format: date-time
          type: string
      required:
      - purchase_ts
      - finx_transaction_id
      type: object
    ValidationJSON:
      properties:
        field:
          description: The field that failed validation.
          type: string
        message:
          description: A human readable message describing the validation error.
          type: string
        value:
          $ref: '#/components/schemas/FieldTypesJSON'
      required:
      - field
      - message
      type: object
    AddressEgressJSON:
      properties:
        address_line_one:
          description: For brick and mortar transactions only.
          example: 100 Main Street
          type: string
        address_line_two:
          description: For brick and mortar transactions only.
          example: Suite 100
          type: string
        city:
          description: For brick and mortar transactions only.
          example: Holmdel
          type: string
        country:
          description: For brick and mortar transactions only.
          example: USA
          type: string
        postal_code:
          description: For brick and mortar transactions only.
          example: '07733'
          type: string
        state:
          description: For brick and mortar transactions only.
          example: NJ
          type: string
      type: object
    OrderType:
      enum:
      - in_store
      - web
      type: string
    MerchantIngressJSON:
      properties:
        name:
          description: The business name.
          example: PicklesRUS
          type: string
      type: object
    LocationEgressJSON:
      properties:
        address:
          $ref: '#/components/schemas/AddressEgressJSON'
        card_acceptor_names:
          items:
            type: string
          type: array
        display_name:
          description: The banner name of the store of the purchase.
          example: Pickles R US
          type: string
        merchant_store_id:
          description: The merchant's store identifier.
          example: '123456789'
          type: string
        name:
          description: The legal/listed name of the store of the purchase.
          example: 'Pickles R US #122333'
          type: string
        phone_number:
          description: For brick and mortar transactions only.
          example: 555-555-5555
          type: string
      type: object
    TransactionEgressJSON:
      properties:
        authorization_ts:
          description: The time at which the transaction was authorized in RFC3339 format. UTC if possible.
          example: '2021-10-01T10:45:55Z'
          format: date-time
          type: string
        byn_transaction_id:
          description: The Banyan ID generated for the transaction
          example: 218823ba-3fec-483b-8803-8c04f7e10d7f
          format: uuid
          type: string
        custom_fields:
          additionalProperties:
            type: string
          description: Set of custom fields set on the transaction.
          type: object
        description:
          description: Description of the transaction.
          example: Purchase of pickles at Tommy's Pickles.
          type: string
        finx_consumer_token:
          description: The merchant's token for the consumer.
          example: 5ASD32K2L34FA
          type: string
        finx_transaction_id:
          description: The finx's internal ID for the transaction.
          example: 5LA3LQKLR34L23L2
          type: string
        location:
          $ref: '#/components/schemas/LocationEgressJSON'
        merchant:
          $ref: '#/components/schemas/MerchantEgressJSON'
        order_type:
          $ref: '#/components/schemas/OrderType'
        payment:
          $ref: '#/components/schemas/TransactionPaymentEgressJSON'
        purchase_ts:
          description: The time at which purchase occurred in RFC3339 format. UTC if possible.
          example: '2021-10-01T10:45:55Z'
          format: date-time
          type: string
        received_ts:
          description: The time at which the receipt was received in RFC3339. UTC if possible.
          example: '2021-10-01T10:45:55Z'
          format: date-time
          type: string
      required:
      - byn_transaction_id
      - received_ts
      - finx_transaction_id
      type: object
    PostTransactionIDJSON:
      properties:
        byn_transaction_id:
          format: uuid
          type: string
        finx_transaction_id:
          type: string
      required:
      - byn_transaction_id
      - finx_transaction_id
      type: object
    MerchantEgressJSON:
      properties:
        name:
          description: The business name.
          example: PicklesRUS
          type: string
      type: object
    LocationIngressJSON:
      properties:
        address:
          $ref: '#/components/schemas/AddressIngressJSON'
        card_acceptor_names:
          items:
            type: string
          type: array
        display_name:
          description: The banner name of the store of the purchase.
          example: Pickles R US
          type: string
        merchant_store_id:
          description: The merchant's store identifier.
          example: '123456789'
          type: string
        name:
          description: The legal/listed name of the store of the purchase.
          example: 'Pickles R US #122333'
          type: string
        phone_number:
          description: For brick and mortar transactions only.
          example: 555-555-5555
          type: string
      type: object
    TransactionPaymentIngressJSON:
      properties:
        arn:
          description: A unique 23-digit number that tags a credit or debit card transaction when it goes from the merchant's bank to the cardholder's bank. Also called a trace ID.
          example: '12345678901234567890123'
          type: string
        auth_code:
          description: Six digit alphanumeric code passed between banks that signal a transaction is possible.
          example: '482920'
          type: string
        bin:
          description: Bank Identification Number associated with the card used. Some BINs will be 8 digits in the near future.
          example: '918202'
          type: string
        card_issuer:
          description: The card issuer for the card used on this payment.
          type: string
        card_last_four:
          description: Last 4 digits on the debit/credit card.
          example: '2393'
          type: string
        card_type:
          description: Card Type refers to the type of card offering from the card issuer.
          type: string
        currency:
          description: The currency of the receipt.
          example: USD
          type: string
        finx_mid:
          description: A unique ID for each POS, assigned by the finx.
          example: '1234567890'
          type: string
        payment_account_reference:
          description: A 29 character payment account reference.
          type: string
        payment_type:
          description: Credit card vs debit card transaction.
          example: debit
          type: string
        scheme:
          description: The network the card was issued on.
          example: VI
          type: string
        total_amount:
          description: Amount paid for goods/services.
          example: '34.50'
          format: decimal
          minLength: 1
          pattern: ^-?\d+(\.\d+)?$
          type: string
        virtual_card_last_four:
          description: The last four digits of the virtual card used for the transaction.
          example: '1234'
          type: string
      type: object
    ErrorJSON:
      properties:
        key:
          additionalProperties:
            description: A map of id field to id identifying the object the error is about.
            type: string
          type: object
        message:
          description: A human readable message describing the error.
          type: string
        validations:
          items:
            $ref: '#/components/schemas/ValidationJSON'
          type: array
      required:
      - message
      title: Error
      type: object
    TransactionPaymentEgressJSON:
      properties:
        arn:
          description: A unique 23-digit number that tags a credit or debit card transaction when it goes from the merchant's bank to the cardholder's bank. Also called a trace ID.
          example: '12345678901234567890123'
          type: string
        auth_code:
          description: Six digit alphanumeric code passed between banks that signal a transaction is possible.
          example: '482920'
          type: string
        bin:
          description: Bank Identification Number associated with the card used. Some BINs will be 8 digits in the near future.
          example: '918202'
          type: string
        card_issuer:
          description: The card issuer for the card used on this payment.
          type: string
        card_last_four:
          description: Last 4 digits on the debit/credit card.
          example: '2393'
          type: string
        card_type:
          description: Card Type refers to the type of card offering from the card issuer.
          type: string
        currency:
          description: The currency of the receipt.
          example: USD
          type: string
        finx_mid:
          description: A unique ID for each POS, assigned by the finx.
          example: '1234567890'
          type: string
        payment_account_reference:
          description: A 29 character payment account reference.
          type: string
        payment_type:
          description: Credit card vs debit card transaction.
          example: debit
          type: string
        scheme:
          description: The network the card was issued on.
          example: VI
          type: string
        total_amount:
          description: Amount paid for goods/services.
          example: '34.50'
          format: decimal
          minLength: 1
          pattern: ^-?\d+(\.\d+)?$
          type: string
        virtual_card_last_four:
          description: The last four digits of the virtual card used for the transaction.
          example: '1234'
          type: string
      type: object
  securitySchemes:
    basic:
      scheme: basic
      type: http
    bearerToken:
      flows:
        clientCredentials:
          refreshUrl: /oauth/refresh
          scopes: {}
          tokenUrl: /oauth/token
      type: oauth2
x-provenance:
  method: searched
  source: https://developers.banyan.com/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://developers.banyan.com/reference/create-webhook-application.md
  - https://developers.banyan.com/reference/create-webhook-endpoint.md
  - https://developers.banyan.com/reference/delete-webhook-application.md
  - https://developers.banyan.com/reference/delete-webhook-endpoint.md
  - https://developers.banyan.com/reference/execute-tag-counter-query.md
  - https://developers.banyan.com/reference/fetch-a-transaction.md
  - https://developers.banyan.com/reference/get-webhook-endpoints-all.md
  - https://developers.banyan.com/reference/get-webhook-event-types.md
  - https://developers.banyan.com/reference/oauth-token.md
  - https://developers.banyan.com/reference/receipt-search.md
  - https://developers.banyan.com/reference/retrieve-a-campaign.md
  - https://developers.banyan.com/reference/retrieve-a-receipt.md
  - https://developers.banyan.com/reference/retrieve-all-campaigns.md
  - https://developers.banyan.com/reference/retrieve-all-offers-under-a-campaign.md
  - https://developers.banyan.com/reference/retrieve-an-offer-activation.md
  - https://developers.banyan.com/reference/retrieve-an-offer.md
  - https://developers.banyan.com/reference/retrieve-history.md
  - https://developers.banyan.com/reference/retrieve-match-merchant-service-provider.md
  - https://developers.banyan.com/reference/retrieve-match.md
  - https://developers.banyan.com/reference/retrieve-offer-activations-for-offer-id.md
  - https://developers.banyan.com/reference/retrieve-offer-redemption-history.md
  - https://developers.banyan.com/reference/retrieve-offer-redemption.md
  - https://developers.banyan.com/reference/retrieve-webhook-application.md
  - https://developers.banyan.com/reference/retrieve-webhook-endpoint.md
  - https://developers.banyan.com/reference/search-offer-activations.md
  - https://developers.banyan.com/reference/search-offer.md
  - https://developers.banyan.com/reference/submit-a-campaign.md
  - https://developers.banyan.com/reference/submit-an-offer-activation.md
  - https://developers.banyan.com/reference/submit-an-offer.md
  - https://developers.banyan.com/reference/submit-hotel-receipts.md
  - https://developers.banyan.com/reference/submit-one-or-more-transactions.md
  - https://developers.banyan.com/reference/submit-retail-receipts.md
  - https://developers.banyan.com/reference/update-a-campaign.md
  - https://developers.banyan.com/reference/update-an-offer-activation.md
  - https://developers.banyan.com/reference/update-an-offer.md
  - https://developers.banyan.com/reference/update-webhook-endpoint.md
  - https://developers.banyan.com/reference/version.md
  merge:
    pages: 37
    deduped: 288
    conflicts_kept_first: 0