openapi: 3.1.0
info:
  title: 'Admin Payments: Payment Methods V3'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/payments/methods:
    get:
      operationId: getPaymentMethods
      summary: List Accepted Payment Methods
      description: >-
        Returns a list of accepted payment methods based on the `order_id` or `checkout_id`.


        **Notes**

        * Use the [Create an Order](/developer/api-reference/rest/admin/management/orders/create-order) endpoint to
        generate the `order_id`.

        * Orders created will be set to incomplete order status.

        * The cart ID and checkout ID are the same.


        **Required Fields**

        * `order_id` or `checkout_id`
      tags:
        - methods
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: order_id
          in: query
          description: The ID of the subject order.
          required: false
          schema:
            type: integer
        - name: checkout_id
          in: query
          description: The ID of the subject checkout; identical to the cart ID.
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Create Payments | create | `store_payments_access_token_create` |

            |  Get Payment Methods | read-only | `store_payments_methods_read` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Methods_getPaymentMethods_Response_200'
        '400':
          description: Request has been rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentMethodsRequestBadRequestError'
        '401':
          description: Valid authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentMethodsRequestUnauthorizedError'
        '404':
          description: Request has been rejected due to resource not being found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentMethodsRequestNotFoundError'
        '422':
          description: Request has been rejected due to missing or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentMethodsRequestUnprocessableEntityError'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    paymentMethodStoredInstrument:
      type: object
      properties:
        brand:
          type: string
          description: Brand of this card such as VISA or Mastercard
        expiry_month:
          type: integer
          description: Expiry month of this card
        expiry_year:
          type: integer
          description: Expiry year of this card
        issuer_identification_number:
          type: string
          description: Issuer identification number of this card. This is extracted from the card when the order is paid for.
        last_4:
          type: string
          description: Last four numbers of this card
        token:
          type: string
          description: A BigCommerce-generated identifier that represents the stored card.
        is_default:
          type: boolean
          default: false
          description: Whether this instrument is a default instrument
        type:
          type: string
          default: stored_card
          description: Type to classify this stored card
      required:
        - brand
        - expiry_month
        - expiry_year
        - issuer_identification_number
        - last_4
        - token
        - is_default
        - type
      title: paymentMethodStoredInstrument
    PaymentMethodFullSupportedInstrumentsItemsInstrumentType:
      type: string
      enum:
        - VISA
        - MASTERCARD
        - DISCOVER
        - AMEX
        - DINERS_CLUB
        - JCB
        - DANKORT
        - MAESTRO
        - STORED_CARD
      description: Type of this instrument
      title: PaymentMethodFullSupportedInstrumentsItemsInstrumentType
    PaymentMethodFullSupportedInstrumentsItems:
      type: object
      properties:
        instrument_type:
          $ref: '#/components/schemas/PaymentMethodFullSupportedInstrumentsItemsInstrumentType'
          description: Type of this instrument
        verification_value_required:
          type: boolean
          description: Whether verification value is required for payment
      required:
        - instrument_type
      title: PaymentMethodFullSupportedInstrumentsItems
    paymentMethod_Full:
      type: object
      properties:
        id:
          type: string
          description: Identifier for this payment method
        name:
          type: string
          description: Name of this payment method
        stored_instruments:
          type: array
          items:
            $ref: '#/components/schemas/paymentMethodStoredInstrument'
        supported_instruments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodFullSupportedInstrumentsItems'
        test_mode:
          type: boolean
          default: false
          description: Whether this payment method is on test mode
        type:
          type: string
          default: card
          description: Type to classify this payment method
      required:
        - id
        - name
        - supported_instruments
        - test_mode
        - type
      title: paymentMethod_Full
    PaymentsMethodsGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      description: Response metadata.
      title: PaymentsMethodsGetResponsesContentApplicationJsonSchemaMeta
    Methods_getPaymentMethods_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/paymentMethod_Full'
        meta:
          $ref: '#/components/schemas/PaymentsMethodsGetResponsesContentApplicationJsonSchemaMeta'
          description: Response metadata.
      title: Methods_getPaymentMethods_Response_200
    PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors:
      type: object
      properties: {}
      title: PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors
    GetPaymentMethodsRequestBadRequestError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: GetPaymentMethodsRequestBadRequestError
    GetPaymentMethodsRequestUnauthorizedError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: GetPaymentMethodsRequestUnauthorizedError
    GetPaymentMethodsRequestNotFoundError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: GetPaymentMethodsRequestNotFoundError
    GetPaymentMethodsRequestUnprocessableEntityError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsMethodsGetResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: GetPaymentMethodsRequestUnprocessableEntityError
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        |  Create Payments | create | `store_payments_access_token_create` |

        |  Get Payment Methods | read-only | `store_payments_methods_read` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to
        API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
