Medusa Payment Providers API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Storefront Payment Providers API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/master/LICENSE
  description: 'Each region has a set of payment providers enabled.


    During checkout, you retrieve the available payment providers in the customer''s region to show them to the customer. Customers then choose their preferred provider to authorize their payment and place their order.


    These API routes allow customers to view available payment providers in their region.

    '
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Payment Providers
  description: 'Each region has a set of payment providers enabled.


    During checkout, you retrieve the available payment providers in the customer''s region to show them to the customer. Customers then choose their preferred provider to authorize their payment and place their order.


    These API routes allow customers to view available payment providers in their region.

    '
  externalDocs:
    description: How to implement payment during checkout.
    url: https://docs.medusajs.com/resources/storefront-development/checkout/payment
  x-associatedSchema:
    $ref: '#/components/schemas/StorePaymentProvider'
paths:
  /store/payment-providers:
    get:
      operationId: GetPaymentProviders
      summary: List Payment Providers
      description: Retrieve a list of payment providers. You must provide the `region_id` query parameter to retrieve the payment providers enabled in that region.
      x-authenticated: false
      externalDocs:
        url: https://docs.medusajs.com/resources/storefront-development/checkout/payment
        description: 'Storefront guide: How to implement payment during checkout.'
      parameters:
      - name: x-publishable-api-key
        in: header
        description: Publishable API Key created in the Medusa Admin.
        required: true
        schema:
          type: string
          externalDocs:
            url: https://docs.medusajs.com/api/store#publishable-api-key
      - name: x-medusa-locale
        in: header
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: region_id
        in: query
        description: Filter by a region ID to get the payment providers enabled in that region.
        required: true
        schema:
          type: string
          title: region_id
          description: Filter by a region ID.
      - name: with_deleted
        in: query
        description: Whether to include deleted records in the result.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: Whether to include deleted records in the result.
      - name: locale
        in: query
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nlet MEDUSA_BACKEND_URL = \"http://localhost:9000\"\n\nif (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {\n  MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL\n}\n\nexport const sdk = new Medusa({\n  baseUrl: MEDUSA_BACKEND_URL,\n  debug: process.env.NODE_ENV === \"development\",\n  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\n})\n\nsdk.store.payment.listPaymentProviders({\n  region_id: \"reg_123\"\n})\n.then(({ payment_providers, count, offset, limit }) => {\n  console.log(payment_providers)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/store/payment-providers'' \

          -H ''x-publishable-api-key: {your_publishable_api_key}'''
      tags:
      - Payment Providers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The list of payment providers.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items returned.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before retrieving the returned items.
                    count:
                      type: number
                      title: count
                      description: The total number of items.
                - type: object
                  description: The list of payment providers.
                  required:
                  - payment_providers
                  properties:
                    payment_providers:
                      type: array
                      description: The list of payment providers.
                      items:
                        $ref: '#/components/schemas/StorePaymentProvider'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
components:
  examples:
    invalid_data_error:
      summary: Invalid Data Error
      value:
        message: first_name must be a string
        type: invalid_data
    not_allowed_error:
      summary: Not Allowed Error
      value:
        message: Discount must be set to dynamic
        type: not_allowed
    database_error:
      summary: Database Error
      value:
        code: api_error
        message: An error occured while hashing password
        type: database_error
    default_error:
      summary: Default Error
      value:
        code: unknown_error
        message: An unknown error occurred.
        type: unknown_error
    invalid_argument_error:
      summary: Invalid Argument Error
      value:
        message: cart.total must be defined
        type: unexpected_state
    unexpected_state_error:
      summary: Unexpected State Error
      value:
        message: cart.total must be defined
        type: unexpected_state
  schemas:
    Error:
      title: Response Error
      type: object
      properties:
        code:
          type: string
          description: A slug code to indicate the type of the error.
          enum:
          - invalid_state_error
          - invalid_request_error
          - api_error
          - unknown_error
        message:
          type: string
          description: Description of the error that occurred.
          example: first_name must be a string
        type:
          type: string
          description: A slug indicating the type of the error.
          enum:
          - QueryRunnerAlreadyReleasedError
          - TransactionAlreadyStartedError
          - TransactionNotStartedError
          - conflict
          - unauthorized
          - payment_authorization_error
          - duplicate_error
          - not_allowed
          - invalid_data
          - not_found
          - database_error
          - unexpected_state
          - invalid_argument
          - unknown_error
    StorePaymentProvider:
      type: object
      description: The payment provider's details
      x-schemaName: StorePaymentProvider
      required:
      - id
      properties:
        id:
          type: string
          title: id
          description: The payment provider's ID.
  responses:
    invalid_request_error:
      description: Invalid Request Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: invalid_request_error
            message: Discount with code TEST already exists.
            type: duplicate_error
    unauthorized:
      description: User is not authorized. Must log in first
      content:
        text/plain:
          schema:
            type: string
            default: Unauthorized
            example: Unauthorized
    400_error:
      description: Client Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_allowed:
              $ref: '#/components/examples/not_allowed_error'
            invalid_data:
              $ref: '#/components/examples/invalid_data_error'
    500_error:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            database:
              $ref: '#/components/examples/database_error'
            unexpected_state:
              $ref: '#/components/examples/unexpected_state_error'
            invalid_argument:
              $ref: '#/components/examples/invalid_argument_error'
            default_error:
              $ref: '#/components/examples/default_error'
    invalid_state_error:
      description: Invalid State Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unknown_error
            message: The request conflicted with another request. You may retry the request with the provided Idempotency-Key.
            type: QueryRunnerAlreadyReleasedError
    not_found_error:
      description: Not Found Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Entity with id 1 was not found
            type: not_found
  securitySchemes:
    jwt_token:
      type: http
      x-displayName: JWT Token
      scheme: bearer
    cookie_auth:
      type: apiKey
      x-displayName: Cookie Session ID
      in: cookie
      name: connect.sid
    reset_password:
      type: http
      x-displayName: Reset Password Token
      scheme: bearer
      x-is-auth: false