Switstack

Switstack Payment API

The Payment API from Switstack — 4 operation(s) for payment.

GitHub OpenAPI

Operations 9

GET /api/payment/payments List Payments #
POST /api/payment/payments Create Payment #
GET /api/payment/payments/{id} Get Payment #
PUT /api/payment/payments/{id} Update Payment #
PATCH /api/payment/payments/{id} Partial Update Payment #
GET /api/payment/logs List Log Data Sets #
GET /api/payment/logs/{id} Get Log Data Set #
PUT /api/payment/logs/{id} Update Log Data Set #
PATCH /api/payment/logs/{id} Partial Update Log Data Set #

Documentation

📖
APIReference
https://docs.switstack.io/api/switcloud/api/switcloud-srv/
📖
Documentation
https://docs.switstack.io/switcloud/
📖
GettingStarted
https://docs.switstack.io/switcloud/getting_started/
📖
Authentication
https://docs.switstack.io/switcloud/security_authentication/
📖
APIReference
https://docs.switstack.io/api/swittest/api/swittest-srv/
📖
Documentation
https://docs.switstack.io/swittest/
📖
GettingStarted
https://docs.switstack.io/swittest/setup/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/switstack/refs/heads/main/openapi/switstack-payment-api-openapi.yml

Other Resources

🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/switstack/refs/heads/main/data-model/switstack-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/switstack-payment-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

switstack-payment-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Switcloud API 🚀 Payment API
  description: '

    ### Prerequisites

    To use this API, you must have an active organization, an active admin user, and either a basic user or a machine user. If you don''t have an account yet, please contact us at [contact@switstack.io](mailto:contact@switstack.io).


    ### Roles

    - **Admin user**: Can manage users, merchants, stores, and POI configurations but cannot create payments.

    - **Basic user**: Can only manage payments.


    ### Authentication

    To make authenticated requests, call `/auth/token` with your credentials and the appropriate grant type. An access token will be returned, which must be included in the request''s Authorization header using the Bearer prefix (`Authorization: Bearer <access_token>`).


    ### Before Creating a Payment


    1. Log in as an admin user.

    2. Using the BOM sub-API, create a merchant, store, and POI, if applicable.

    3. Using the config sub-API, create a POI configuration, if applicable.


    The minimum required POI configuration includes:

    - An EMV.

    - An EMV list containing the previously created EMV.

    - An EMV config using the EMV list as the nominal list.

    - A POI config containing the EMV config.


    ### Creating a Payment

    1. Log in as a basic or machine user.

    2. Create a payment with at least a POI ID and a POI config ID.

    '
  version: 2.28.0
servers:
- url: https://switcloud.switstack.io/
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Payment
paths:
  /api/payment/payments:
    get:
      tags:
      - Payment
      summary: List Payments
      operationId: list_payments
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: order_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Order By
      - name: poi_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Poi Id
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/State'
          - type: 'null'
          title: State
      - name: outcome_status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/OutcomeStatus'
          - type: 'null'
          title: Outcome Status
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_TypeVar_Customized_PaymentReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Payment
      summary: Create Payment
      operationId: create_payment
      security:
      - OAuth2PasswordBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreateSchema'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payment/payments/{id}:
    get:
      tags:
      - Payment
      summary: Get Payment
      operationId: get_payment
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Payment
      summary: Update Payment
      operationId: update_payment
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentUpdateSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Payment
      summary: Partial Update Payment
      operationId: partial_update_payment
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPartialUpdateSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payment/logs:
    get:
      tags:
      - Payment
      summary: List Log Data Sets
      operationId: list_log_data_sets
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
      - name: order_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Order By
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_TypeVar_Customized_LogDataSetReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/payment/logs/{id}:
    get:
      tags:
      - Payment
      summary: Get Log Data Set
      operationId: get_log_data_set
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDataSetReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Payment
      summary: Update Log Data Set
      operationId: update_log_data_set
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDataSetUpdateSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDataSetReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Payment
      summary: Partial Update Log Data Set
      operationId: partial_update_log_data_set
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDataSetPartialUpdateSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogDataSetReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OutcomeStatus:
      type: string
      enum:
      - UNDEFINED
      - APPROVED
      - DECLINED
      - ONLINE_REQUEST
      - END_APPLICATION
      - SELECT_NEXT
      - TRY_ANOTHER_INTERFACE
      - TRY_AGAIN
      - NA
      title: OutcomeStatus
    PaymentPartialUpdateSchema:
      properties:
        state:
          anyOf:
          - $ref: '#/components/schemas/State'
          - type: 'null'
        outcome_status:
          anyOf:
          - $ref: '#/components/schemas/OutcomeStatus'
          - type: 'null'
        trd:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - 9F02060000000015009F7C1411223344556677889900112233445566778899009F5301465F2A0209785F3601029A032505069C01009F2103105929
          - type: 'null'
          title: Trd
        authorization:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Authorization
        completion:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Completion
        pin_block:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Pin Block
      additionalProperties: false
      type: object
      title: PaymentPartialUpdateSchema
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LogDataSetUpdateSchema:
      properties:
        meta_data:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Meta Data
        telemetry:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Telemetry
        config:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Config
        trd:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trd
        all_tags:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: All Tags
        apdus:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Apdus
        trace:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trace
        signals:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Signals
      additionalProperties: false
      type: object
      title: LogDataSetUpdateSchema
    State:
      type: string
      enum:
      - UNDEFINED
      - CREATED
      - READY
      - INITIATED
      - REQUESTED
      - COMPLETED
      title: State
    Page_TypeVar_Customized_PaymentReadSchema_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PaymentReadSchema'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0
          title: Total
        page:
          type: integer
          minimum: 1
          title: Page
        size:
          type: integer
          minimum: 1
          title: Size
        pages:
          type: integer
          minimum: 0
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - size
      - pages
      title: Page[TypeVar]Customized[PaymentReadSchema]
    LogDataSetPartialUpdateSchema:
      properties:
        meta_data:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Meta Data
        telemetry:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Telemetry
        config:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Config
        trd:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trd
        all_tags:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: All Tags
        apdus:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Apdus
        trace:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trace
        signals:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Signals
      additionalProperties: false
      type: object
      title: LogDataSetPartialUpdateSchema
    PaymentUpdateSchema:
      properties:
        state:
          $ref: '#/components/schemas/State'
          default: UNDEFINED
        outcome_status:
          $ref: '#/components/schemas/OutcomeStatus'
          default: UNDEFINED
        trd:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - 9F02060000000015009F7C1411223344556677889900112233445566778899009F5301465F2A0209785F3601029A032505069C01009F2103105929
          - type: 'null'
          title: Trd
        authorization:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Authorization
        completion:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Completion
        pin_block:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Pin Block
      additionalProperties: false
      type: object
      title: PaymentUpdateSchema
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Page_TypeVar_Customized_LogDataSetReadSchema_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/LogDataSetReadSchema'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0
          title: Total
        page:
          type: integer
          minimum: 1
          title: Page
        size:
          type: integer
          minimum: 1
          title: Size
        pages:
          type: integer
          minimum: 0
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - size
      - pages
      title: Page[TypeVar]Customized[LogDataSetReadSchema]
    PaymentReadSchema:
      properties:
        state:
          $ref: '#/components/schemas/State'
          default: UNDEFINED
        outcome_status:
          $ref: '#/components/schemas/OutcomeStatus'
          default: UNDEFINED
        trd:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - 9F02060000000015009F7C1411223344556677889900112233445566778899009F5301465F2A0209785F3601029A032505069C01009F2103105929
          - type: 'null'
          title: Trd
        authorization:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Authorization
        completion:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Completion
        pin_block:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Pin Block
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        poi_id:
          type: string
          format: uuid
          title: Poi Id
        poi_config_id:
          type: string
          format: uuid
          title: Poi Config Id
        log_data_set_id:
          type: string
          format: uuid
          title: Log Data Set Id
      type: object
      required:
      - id
      - organization_id
      - poi_id
      - poi_config_id
      - log_data_set_id
      title: PaymentReadSchema
    PaymentCreateSchema:
      properties:
        state:
          $ref: '#/components/schemas/State'
          default: UNDEFINED
        outcome_status:
          $ref: '#/components/schemas/OutcomeStatus'
          default: UNDEFINED
        trd:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - 9F02060000000015009F7C1411223344556677889900112233445566778899009F5301465F2A0209785F3601029A032505069C01009F2103105929
          - type: 'null'
          title: Trd
        authorization:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Authorization
        completion:
          anyOf:
          - type: string
            minLength: 1
            examples:
            - DF81290840F0F00098F0FF00FF81060ADF81150600030000001CDF81160D1C00000013656E646566720000E721DFA0090A00000000000000000000DFA028050402000000DFA02006000000030000
          - type: 'null'
          title: Completion
        pin_block:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Pin Block
        organization_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
        poi_id:
          type: string
          format: uuid
          title: Poi Id
        poi_config_id:
          type: string
          format: uuid
          title: Poi Config Id
      additionalProperties: false
      type: object
      required:
      - poi_id
      - poi_config_id
      title: PaymentCreateSchema
    LogDataSetReadSchema:
      properties:
        meta_data:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Meta Data
        telemetry:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Telemetry
        config:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Config
        trd:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trd
        all_tags:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: All Tags
        apdus:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Apdus
        trace:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Trace
        signals:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Signals
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
      additionalProperties: false
      type: object
      required:
      - id
      - organization_id
      title: LogDataSetReadSchema
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: auth/token