Telnyx Pay Connectors API

openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Pay Connectors API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Pay Connectors
  description: Generic payment connector configuration.
paths:
  /pay_connectors:
    get:
      operationId: listPayConnectors
      summary: List Pay connectors
      description: List connectors belonging to the authenticated organization, including connectors created by other users in that organization. Set filter[type]=generic to restrict results to the type covered here. Results default to newest created_at first. Use meta.end_cursor as page[after] for the next page, or meta.start_cursor as page[before] for the preceding page. Omit both cursors for the first page; if both are supplied, page[after] takes precedence. Responses omit passwords and tokens.
      tags:
      - Pay Connectors
      parameters:
      - name: page[size]
        in: query
        description: Number of records per page.
        schema:
          type: integer
          minimum: 1
          maximum: 249
          default: 25
      - name: page[after]
        in: query
        description: Opaque cursor from meta.end_cursor.
        schema:
          type: string
      - name: page[before]
        in: query
        description: Opaque cursor from meta.start_cursor.
        schema:
          type: string
      - name: sort
        in: query
        description: Comma-separated created_at or updated_at fields, optionally prefixed with - for descending order.
        schema:
          type: string
          default: -created_at
          example: -created_at
      - name: filter[name]
        in: query
        description: Exact match on name.
        schema:
          type: string
          example: my-payment-connector
      - name: filter[type]
        in: query
        description: Exact match on type.
        schema:
          type: string
          example: generic
      - name: filter[mode]
        in: query
        description: Exact match on mode.
        schema:
          type: string
          example: test
      - name: filter[created_at][eq]
        in: query
        description: Equal to this created_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[created_at][gt]
        in: query
        description: After this created_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[created_at][gte]
        in: query
        description: At or after this created_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[created_at][lt]
        in: query
        description: Before this created_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[created_at][lte]
        in: query
        description: At or before this created_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[updated_at][eq]
        in: query
        description: Equal to this updated_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[updated_at][gt]
        in: query
        description: After this updated_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[updated_at][gte]
        in: query
        description: At or after this updated_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[updated_at][lt]
        in: query
        description: Before this updated_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      - name: filter[updated_at][lte]
        in: query
        description: At or before this updated_at timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
      responses:
        '200':
          description: Organization connectors and cursor metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorListResponse'
              example:
                data: []
                meta:
                  page_size: 25
                  start_cursor: null
                  end_cursor: null
        '422':
          description: Invalid filter, sort or cursor parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - code: '10000'
                  title: Invalid request
                  detail: Provided cursor is invalid.
                  source:
                    pointer: /after
    post:
      operationId: createPayConnector
      summary: Create a Pay connector
      description: Create a generic payment connector in the authenticated organization. The name must be unique in that organization. Authentication supplies ownership; do not send user_id or organization_id. Config is encrypted at rest; passwords and tokens are omitted from responses. This operation stores configuration and does not initiate a payment. See the processor contract.
      tags:
      - Pay Connectors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGenericPayConnectorRequest'
            examples:
              none:
                summary: None processor authentication
                value:
                  name: my-payment-connector
                  type: generic
                  mode: test
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: none
              basic:
                summary: Basic processor authentication
                value:
                  name: my-payment-connector
                  type: generic
                  mode: test
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: basic
                    username: merchant-example
                    password: <processor-password>
              bearer:
                summary: Bearer processor authentication
                value:
                  name: my-payment-connector
                  type: generic
                  mode: test
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: bearer
                    token: <processor-bearer-token>
      responses:
        '201':
          description: Connector created. Credentials are omitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorResponse'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  record_type: pay_connector
                  name: my-payment-connector
                  type: generic
                  mode: test
                  user_id: user-example
                  organization_id: organization-example
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: bearer
                  created_at: '2026-10-01T12:00:00.000000Z'
                  updated_at: '2026-10-01T12:00:00.000000Z'
        '422':
          description: Invalid fields or duplicate name in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - code: '10000'
                  title: Invalid request
                  detail: The 'config' parameter is invalid. Please consult the documentation.
                  source:
                    pointer: /config
  /pay_connectors/{name}:
    delete:
      operationId: deletePayConnector
      summary: Delete a Pay connector
      description: Delete a connector by name in the authenticated organization. Both test and live connectors can be deleted. Returns no response body on success; a missing name or a connector in another organization returns 404.
      tags:
      - Pay Connectors
      parameters:
      - name: name
        in: path
        required: true
        description: Connector name, not its UUID. URL-encode the name as a path segment.
        schema:
          type: string
          example: my-payment-connector
      responses:
        '204':
          description: Connector deleted. No response body.
        '404':
          description: Connector not found in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - detail: Resource not found
    get:
      operationId: getPayConnector
      summary: Retrieve a Pay connector
      description: Retrieve a connector by name within the authenticated organization. Password and token are omitted. A missing name or a connector owned by another organization returns 404.
      tags:
      - Pay Connectors
      parameters:
      - name: name
        in: path
        required: true
        description: Connector name, not its UUID. URL-encode the name as a path segment.
        schema:
          type: string
          example: my-payment-connector
      responses:
        '200':
          description: Connector details with credentials omitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorResponse'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  record_type: pay_connector
                  name: my-payment-connector
                  type: generic
                  mode: test
                  user_id: user-example
                  organization_id: organization-example
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: bearer
                  created_at: '2026-10-01T12:00:00.000000Z'
                  updated_at: '2026-10-01T12:00:00.000000Z'
        '404':
          description: Connector not found in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - detail: Resource not found
    patch:
      operationId: updatePayConnector
      summary: Update a Pay connector
      description: Update a generic connector by name in the authenticated organization. Both test and live connectors can be updated through the API. Omitted fields remain unchanged. Supplying config replaces the entire config; it does not merge keys. Include endpoint_url and the credentials required for the selected auth_type on every config replacement. Omitting config preserves existing credentials, allowing a mode-only update. The path name cannot be renamed. Public updates use PATCH.
      tags:
      - Pay Connectors
      parameters:
      - name: name
        in: path
        required: true
        description: Connector name, not its UUID. URL-encode the name as a path segment.
        schema:
          type: string
          example: my-payment-connector
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGenericPayConnectorRequest'
            examples:
              modeOnly:
                summary: Change mode without re-sending credentials
                value:
                  mode: live
              replaceConfig:
                summary: Replace all config and re-send the bearer token
                value:
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: bearer
                    token: <processor-bearer-token>
                    timeout: 15000
      responses:
        '200':
          description: Updated connector after the modeOnly example, with credentials omitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorResponse'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  record_type: pay_connector
                  name: my-payment-connector
                  type: generic
                  mode: live
                  user_id: user-example
                  organization_id: organization-example
                  config:
                    endpoint_url: https://processor.example.com/pay
                    auth_type: bearer
                  created_at: '2026-10-01T12:00:00.000000Z'
                  updated_at: '2026-10-01T12:00:00.000000Z'
        '404':
          description: Connector not found in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - detail: Resource not found
        '422':
          description: Invalid fields or duplicate name in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayConnectorErrors'
              example:
                errors:
                - code: '10000'
                  title: Invalid request
                  detail: The 'config' parameter is invalid. Please consult the documentation.
                  source:
                    pointer: /config
components:
  schemas:
    GenericPayConnectorConfig:
      type: object
      description: Configuration for a generic connector. A config update replaces the complete object, not individual keys. Unknown config keys are discarded. Authentication credentials must be nonblank strings when required by the selected auth_type.
      required:
      - endpoint_url
      properties:
        endpoint_url:
          type: string
          description: HTTP or HTTPS processor URL with a host. Use HTTPS to protect payment data in transit.
          pattern: ^https?://\S+
          example: https://processor.example.com/pay
        auth_type:
          type: string
          description: Processor authentication, separate from the Telnyx API key. If omitted, validation requires basic credentials but no Basic Authorization header is added. Explicitly set basic or bearer to send its corresponding Authorization header, or none for no processor authentication.
          enum:
          - none
          - basic
          - bearer
        username:
          type: string
          description: Nonblank string required for basic authentication. Returned in connector responses.
        password:
          type: string
          description: Nonblank string required for basic authentication. Write-only; omitted from responses. Re-send when replacing a basic-auth config.
          writeOnly: true
        token:
          type: string
          description: Nonblank string required for bearer authentication. Write-only; omitted from responses. Re-send when replacing a bearer-auth config.
          writeOnly: true
        timeout:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 4294967295
          default: 10000
          description: Processor HTTP timeout in milliseconds. Omitted or null uses 10000; null is removed before storage. Not the IVR digit-gather timeout.
      oneOf:
      - title: Basic authentication (also the validation default)
        properties:
          auth_type:
            const: basic
          username:
            type: string
            description: Basic username.
            minLength: 1
            pattern: \S
          password:
            type: string
            description: Basic password.
            minLength: 1
            pattern: \S
        required:
        - username
        - password
      - title: Bearer authentication
        properties:
          auth_type:
            const: bearer
          token:
            type: string
            description: Processor bearer token.
            minLength: 1
            pattern: \S
        required:
        - auth_type
        - token
      - title: No processor authentication
        properties:
          auth_type:
            const: none
        required:
        - auth_type
    PayConnector:
      type: object
      description: Organization-owned connector. Examples and config properties here describe generic connectors; listing is not restricted to that type unless filter[type]=generic is supplied. Passwords and bearer tokens are omitted, not masked. Defaults for auth_type and timeout need not appear in stored config.
      properties:
        id:
          type: string
          description: Connector identifier.
          format: uuid
        name:
          type: string
          description: Connector name used for retrieval, update, deletion and Pay.
        record_type:
          type: string
          description: Resource type.
          enum:
          - pay_connector
        user_id:
          type: string
          description: Creating user; assigned from authentication, not request input.
        organization_id:
          type: string
          description: Owning organization; assigned from authentication, not request input.
        type:
          type: string
          description: Connector type; generic is covered by this reference. Other types may appear in unfiltered lists.
        mode:
          type: string
          enum:
          - test
          - live
          description: Configured mode.
        config:
          type: object
          description: Redacted stored configuration. Generic connector fields are shown here. Unknown config keys are discarded. Password and token are never returned.
          properties:
            endpoint_url:
              type: string
              description: HTTP or HTTPS processor URL with a host. Use HTTPS to protect payment data in transit.
              pattern: ^https?://\S+
              example: https://processor.example.com/pay
            auth_type:
              type: string
              description: Stored processor authentication selection. Omitted if it was not explicitly configured.
              enum:
              - none
              - basic
              - bearer
            username:
              type: string
              description: Stored username, when supplied. Required to be a nonblank string for basic authentication.
            timeout:
              type: integer
              minimum: 1
              maximum: 4294967295
              description: Stored processor HTTP timeout in milliseconds. Omitted when no timeout was configured; the effective runtime default is 10000.
        created_at:
          type: string
          description: Creation time.
          format: date-time
        updated_at:
          type: string
          description: Last update time.
          format: date-time
    PayConnectorErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Telnyx error code.
              title:
                type: string
                description: Error title.
              detail:
                type: string
                description: Error detail.
              source:
                type: object
                properties:
                  pointer:
                    type: string
                    description: Invalid field pointer.
    PayConnectorResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PayConnector'
    CreateGenericPayConnectorRequest:
      type: object
      required:
      - name
      - config
      properties:
        name:
          type: string
          description: Unique within the authenticated organization. Used in resource paths and as connector_name in the Call Control Pay request. Cannot be renamed by update.
          minLength: 1
          maxLength: 255
          pattern: \S
          example: my-payment-connector
        type:
          type: string
          description: Connector type covered by this reference.
          enum:
          - generic
          default: generic
        mode:
          type: string
          description: Defaults to test on creation. Test restricts collected card numbers but still contacts the configured processor; use a processor sandbox URL and sandbox credentials. Live removes the test-card restriction. Neither mode locks API updates.
          enum:
          - test
          - live
          default: test
        config:
          $ref: '#/components/schemas/GenericPayConnectorConfig'
    PayConnectorListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PayConnector'
        meta:
          type: object
          description: Cursor pagination metadata. No total_count, page_count or page_number is returned.
          properties:
            page_size:
              type: integer
              description: Page size.
            start_cursor:
              type:
              - string
              - 'null'
              description: Cursor for requesting the preceding page.
            end_cursor:
              type:
              - string
              - 'null'
              description: Cursor for requesting the following page.
    UpdateGenericPayConnectorRequest:
      type: object
      description: Only type, mode and config are updated; the connector name is selected by the path. Omit config to preserve existing configuration and credentials. If supplied, send the entire replacement config including required credentials.
      properties:
        type:
          type: string
          enum:
          - generic
          description: Generic connector type. Omit to preserve the existing value.
        mode:
          type: string
          enum:
          - test
          - live
          description: Omit to preserve the existing mode. Use an explicit test or live value.
        config:
          $ref: '#/components/schemas/GenericPayConnectorConfig'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt