naftiko: 1.0.0-alpha2
info:
  label: Visa Acceptance Payment Acceptance Workflow
  description: Workflow capability for the complete payment acceptance lifecycle on the Visa Acceptance platform. Covers merchant
    payment processing (authorize, capture, refund, void), invoice-based payment collection, and pay-by-link generation for
    online merchants, ISVs, and AI agents.
  tags:
  - Credit Cards
  - E-Commerce
  - Fintech
  - Invoicing
  - Payment Links
  - Payments
  - Visa
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VISA_ACCEPTANCE_JWT_TOKEN: VISA_ACCEPTANCE_JWT_TOKEN
capability:
  consumes:
  - type: http
    namespace: visa-acceptance-payments
    baseUri: https://apitest.visaacceptance.com
    description: Visa Acceptance Payments REST API
    authentication:
      type: bearer
      token: '{{VISA_ACCEPTANCE_JWT_TOKEN}}'
    resources:
    - name: payments
      path: /pts/v2/payments
      description: Payment authorization and sale
      operations:
      - name: authorize-payment
        method: POST
        description: Authorize a payment transaction
        inputParameters:
        - name: capture
          in: body
          type: boolean
          required: false
          description: Combine auth and capture
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-captures
      path: /pts/v2/payments/{paymentId}/captures
      description: Capture a previously authorized payment
      operations:
      - name: capture-payment
        method: POST
        description: Capture a previously authorized payment
        inputParameters:
        - name: paymentId
          in: path
          type: string
          required: true
          description: Payment ID from authorization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-refunds
      path: /pts/v2/payments/{paymentId}/refunds
      description: Refund a captured payment
      operations:
      - name: refund-payment
        method: POST
        description: Refund a captured payment
        inputParameters:
        - name: paymentId
          in: path
          type: string
          required: true
          description: Payment ID to refund
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-voids
      path: /pts/v2/payments/{paymentId}/voids
      description: Void a payment before settlement
      operations:
      - name: void-payment
        method: POST
        description: Void a payment transaction
        inputParameters:
        - name: paymentId
          in: path
          type: string
          required: true
          description: Payment ID to void
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-reversals
      path: /pts/v2/payments/{paymentId}/reversals
      description: Reverse an authorization
      operations:
      - name: reverse-authorization
        method: POST
        description: Reverse an authorization to release held funds
        inputParameters:
        - name: paymentId
          in: path
          type: string
          required: true
          description: Authorization payment ID to reverse
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoices
      path: /pts/v2/invoices
      description: Invoice creation and management
      operations:
      - name: create-invoice
        method: POST
        description: Create an invoice for payment collection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-invoices
        method: GET
        description: List invoices with optional status filter
        inputParameters:
        - name: status
          in: query
          type: string
          required: false
          description: Filter by invoice status
        - name: limit
          in: query
          type: integer
          required: false
          description: Max results to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: invoice-by-id
      path: /pts/v2/invoices/{invoiceId}
      description: Invoice management by ID
      operations:
      - name: get-invoice
        method: GET
        description: Get invoice details by ID
        inputParameters:
        - name: invoiceId
          in: path
          type: string
          required: true
          description: Invoice ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-invoice
        method: PATCH
        description: Update a draft invoice
        inputParameters:
        - name: invoiceId
          in: path
          type: string
          required: true
          description: Invoice ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: paybylinks
      path: /pts/v2/paybylinks
      description: Payment link creation and management
      operations:
      - name: create-pay-by-link
        method: POST
        description: Generate a shareable payment link
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-pay-by-links
        method: GET
        description: List payment links with optional status filter
        inputParameters:
        - name: status
          in: query
          type: string
          required: false
          description: Filter by link status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: paybylink-by-id
      path: /pts/v2/paybylinks/{linkId}
      description: Payment link management by ID
      operations:
      - name: get-pay-by-link
        method: GET
        description: Get payment link details
        inputParameters:
        - name: linkId
          in: path
          type: string
          required: true
          description: Payment link ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cancel-pay-by-link
        method: DELETE
        description: Cancel an active payment link
        inputParameters:
        - name: linkId
          in: path
          type: string
          required: true
          description: Payment link ID to cancel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: payment-acceptance-api
    description: Unified REST API for the Visa Acceptance payment lifecycle.
    resources:
    - path: /v1/payments
      name: payments
      description: Payment authorization and sale
      operations:
      - method: POST
        name: authorize-payment
        description: Authorize a payment transaction
        call: visa-acceptance-payments.authorize-payment
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{paymentId}/captures
      name: payment-captures
      description: Capture authorized payments
      operations:
      - method: POST
        name: capture-payment
        description: Complete a previously authorized payment
        call: visa-acceptance-payments.capture-payment
        with:
          paymentId: rest.paymentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{paymentId}/refunds
      name: payment-refunds
      description: Refund captured payments
      operations:
      - method: POST
        name: refund-payment
        description: Refund a captured payment (partial or full)
        call: visa-acceptance-payments.refund-payment
        with:
          paymentId: rest.paymentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{paymentId}/voids
      name: payment-voids
      description: Void payments before settlement
      operations:
      - method: POST
        name: void-payment
        description: Void a payment before it settles
        call: visa-acceptance-payments.void-payment
        with:
          paymentId: rest.paymentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{paymentId}/reversals
      name: payment-reversals
      description: Reverse authorization holds
      operations:
      - method: POST
        name: reverse-authorization
        description: Release an authorization hold
        call: visa-acceptance-payments.reverse-authorization
        with:
          paymentId: rest.paymentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices
      name: invoices
      description: Invoice management
      operations:
      - method: POST
        name: create-invoice
        description: Create an invoice for a customer
        call: visa-acceptance-payments.create-invoice
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: list-invoices
        description: List invoices
        call: visa-acceptance-payments.list-invoices
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/invoices/{invoiceId}
      name: invoice-by-id
      description: Invoice access by ID
      operations:
      - method: GET
        name: get-invoice
        description: Get invoice details
        call: visa-acceptance-payments.get-invoice
        with:
          invoiceId: rest.invoiceId
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: update-invoice
        description: Update a draft invoice
        call: visa-acceptance-payments.update-invoice
        with:
          invoiceId: rest.invoiceId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pay-by-links
      name: pay-by-links
      description: Payment link management
      operations:
      - method: POST
        name: create-pay-by-link
        description: Generate a shareable payment link
        call: visa-acceptance-payments.create-pay-by-link
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: list-pay-by-links
        description: List payment links
        call: visa-acceptance-payments.list-pay-by-links
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pay-by-links/{linkId}
      name: pay-by-link-by-id
      description: Payment link access by ID
      operations:
      - method: GET
        name: get-pay-by-link
        description: Get payment link details
        call: visa-acceptance-payments.get-pay-by-link
        with:
          linkId: rest.linkId
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: cancel-pay-by-link
        description: Cancel a payment link
        call: visa-acceptance-payments.cancel-pay-by-link
        with:
          linkId: rest.linkId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: payment-acceptance-mcp
    transport: http
    description: MCP server for AI-assisted payment acceptance and invoice management.
    tools:
    - name: authorize-payment
      description: Authorize a payment to place a hold on customer funds
      hints:
        readOnly: false
        idempotent: false
      call: visa-acceptance-payments.authorize-payment
      outputParameters:
      - type: object
        mapping: $.
    - name: capture-payment
      description: Complete a payment by capturing previously authorized funds
      hints:
        readOnly: false
        idempotent: true
      call: visa-acceptance-payments.capture-payment
      with:
        paymentId: tools.paymentId
      outputParameters:
      - type: object
        mapping: $.
    - name: refund-payment
      description: Refund a customer for a captured payment (partial or full)
      hints:
        readOnly: false
        idempotent: false
      call: visa-acceptance-payments.refund-payment
      with:
        paymentId: tools.paymentId
      outputParameters:
      - type: object
        mapping: $.
    - name: void-payment
      description: Cancel a payment before it settles to release funds back to the customer
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: visa-acceptance-payments.void-payment
      with:
        paymentId: tools.paymentId
      outputParameters:
      - type: object
        mapping: $.
    - name: reverse-authorization
      description: Release an authorization hold without completing the payment
      hints:
        readOnly: false
        idempotent: true
      call: visa-acceptance-payments.reverse-authorization
      with:
        paymentId: tools.paymentId
      outputParameters:
      - type: object
        mapping: $.
    - name: create-invoice
      description: Create an invoice with line items and due date for a customer
      hints:
        readOnly: false
        idempotent: false
      call: visa-acceptance-payments.create-invoice
      outputParameters:
      - type: object
        mapping: $.
    - name: list-invoices
      description: List invoices filtered by status (CREATED, SENT, PAID, etc.)
      hints:
        readOnly: true
        idempotent: true
      call: visa-acceptance-payments.list-invoices
      outputParameters:
      - type: object
        mapping: $.
    - name: get-invoice
      description: Get the status and details of a specific invoice
      hints:
        readOnly: true
        idempotent: true
      call: visa-acceptance-payments.get-invoice
      with:
        invoiceId: tools.invoiceId
      outputParameters:
      - type: object
        mapping: $.
    - name: create-pay-by-link
      description: Generate a shareable payment link to collect a payment
      hints:
        readOnly: false
        idempotent: false
      call: visa-acceptance-payments.create-pay-by-link
      outputParameters:
      - type: object
        mapping: $.
    - name: list-pay-by-links
      description: List payment links filtered by status
      hints:
        readOnly: true
        idempotent: true
      call: visa-acceptance-payments.list-pay-by-links
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-pay-by-link
      description: Cancel an active payment link so it can no longer accept payments
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: visa-acceptance-payments.cancel-pay-by-link
      with:
        linkId: tools.linkId
      outputParameters:
      - type: object
        mapping: $.