TrueLayer Open Banking Payments

naftiko: "1.0.0-alpha1"

info:
  label: "TrueLayer Open Banking Payments"
  description: >-
    Workflow capability for open banking payment operations via TrueLayer.
    Covers the full payment lifecycle: creating payments and mandates,
    handling payouts, processing refunds, and monitoring merchant account
    balances and transactions across UK and EU open banking rails.
    Used by fintech developers, payment teams, and financial platforms.
  tags:
    - TrueLayer
    - Open Banking
    - Payments
    - VRP
    - Payouts
    - Refunds
    - Merchant Accounts
    - UK Banking
    - EU Banking
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TRUELAYER_ACCESS_TOKEN: TRUELAYER_ACCESS_TOKEN
      TRUELAYER_SIGNING_KEY: TRUELAYER_SIGNING_KEY

capability:
  consumes:
    - import: truelayer-payments
      location: ./shared/truelayer-payments.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: truelayer-open-banking-api
      description: "Unified REST API for TrueLayer open banking payment operations."
      resources:
        - path: /v1/payments
          name: payments
          description: "Payment lifecycle management"
          operations:
            - method: POST
              name: create-payment
              description: "Create a new open banking payment"
              call: "truelayer-payments.create-payment"
              with:
                amount_in_minor: "rest.amount_in_minor"
                currency: "rest.currency"
                payment_method: "rest.payment_method"
                user: "rest.user"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{id}
          name: payment
          operations:
            - method: GET
              name: get-payment
              description: "Get payment status"
              call: "truelayer-payments.get-payment"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{id}/refunds
          name: payment-refunds
          operations:
            - method: POST
              name: create-refund
              description: "Create a refund for a payment"
              call: "truelayer-payments.create-refund"
              with:
                id: "rest.id"
                amount_in_minor: "rest.amount_in_minor"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-payment-refunds
              description: "List refunds for a payment"
              call: "truelayer-payments.list-payment-refunds"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/mandates
          name: mandates
          description: "Variable recurring payment mandates"
          operations:
            - method: POST
              name: create-mandate
              description: "Create a VRP mandate"
              call: "truelayer-payments.create-mandate"
              with:
                mandate: "rest.mandate"
                currency: "rest.currency"
                user: "rest.user"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/mandates/{id}
          name: mandate
          operations:
            - method: GET
              name: get-mandate
              description: "Get mandate details"
              call: "truelayer-payments.get-mandate"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: revoke-mandate
              description: "Revoke a VRP mandate"
              call: "truelayer-payments.revoke-mandate"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payouts
          name: payouts
          description: "Merchant account payouts"
          operations:
            - method: POST
              name: create-payout
              description: "Create a payout"
              call: "truelayer-payments.create-payout"
              with:
                merchant_account_id: "rest.merchant_account_id"
                amount_in_minor: "rest.amount_in_minor"
                currency: "rest.currency"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payouts/{id}
          name: payout
          operations:
            - method: GET
              name: get-payout
              description: "Get payout status"
              call: "truelayer-payments.get-payout"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/merchant-accounts
          name: merchant-accounts
          description: "Merchant account management"
          operations:
            - method: GET
              name: list-merchant-accounts
              description: "List merchant accounts"
              call: "truelayer-payments.list-merchant-accounts"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/merchant-accounts/{id}
          name: merchant-account
          operations:
            - method: GET
              name: get-merchant-account
              description: "Get merchant account and balance"
              call: "truelayer-payments.get-merchant-account"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/merchant-accounts/{id}/transactions
          name: merchant-account-transactions
          operations:
            - method: GET
              name: list-merchant-account-transactions
              description: "List merchant account transactions"
              call: "truelayer-payments.list-merchant-account-transactions"
              with:
                id: "rest.id"
                from: "rest.from"
                to: "rest.to"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: truelayer-open-banking-mcp
      transport: http
      description: "MCP server for AI-assisted open banking payment operations via TrueLayer."
      tools:
        - name: create-payment
          description: >-
            Create an open banking bank-transfer payment via TrueLayer.
            Supports pay-ins to merchant accounts and single payments to
            external accounts. Requires amount in minor units (pence/cents).
          hints:
            readOnly: false
          call: "truelayer-payments.create-payment"
          with:
            amount_in_minor: "tools.amount_in_minor"
            currency: "tools.currency"
            payment_method: "tools.payment_method"
            user: "tools.user"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-payment
          description: "Get the current status and details of a payment"
          hints:
            readOnly: true
            idempotent: true
          call: "truelayer-payments.get-payment"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-refund
          description: "Initiate a refund for a completed payment"
          hints:
            readOnly: false
          call: "truelayer-payments.create-refund"
          with:
            id: "tools.id"
            amount_in_minor: "tools.amount_in_minor"
            reference: "tools.reference"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-payment-refunds
          description: "List all refunds for a specific payment"
          hints:
            readOnly: true
          call: "truelayer-payments.list-payment-refunds"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-mandate
          description: >-
            Create a Variable Recurring Payment (VRP) mandate. Authorizes
            future payments within defined constraints (limits, frequency).
          hints:
            readOnly: false
          call: "truelayer-payments.create-mandate"
          with:
            mandate: "tools.mandate"
            currency: "tools.currency"
            user: "tools.user"
            constraints: "tools.constraints"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-mandate
          description: "Get VRP mandate status and details"
          hints:
            readOnly: true
            idempotent: true
          call: "truelayer-payments.get-mandate"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: revoke-mandate
          description: "Revoke an active VRP mandate"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "truelayer-payments.revoke-mandate"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-payout
          description: "Create a payout from merchant account to a user or external account"
          hints:
            readOnly: false
          call: "truelayer-payments.create-payout"
          with:
            merchant_account_id: "tools.merchant_account_id"
            amount_in_minor: "tools.amount_in_minor"
            currency: "tools.currency"
            beneficiary: "tools.beneficiary"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-payout
          description: "Get payout status"
          hints:
            readOnly: true
            idempotent: true
          call: "truelayer-payments.get-payout"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-merchant-accounts
          description: "List all TrueLayer merchant accounts with balances"
          hints:
            readOnly: true
          call: "truelayer-payments.list-merchant-accounts"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-merchant-account
          description: "Get merchant account details and current balance"
          hints:
            readOnly: true
            idempotent: true
          call: "truelayer-payments.get-merchant-account"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-merchant-account-transactions
          description: "List transactions for a merchant account with date filters"
          hints:
            readOnly: true
          call: "truelayer-payments.list-merchant-account-transactions"
          with:
            id: "tools.id"
            from: "tools.from"
            to: "tools.to"
          outputParameters:
            - type: object
              mapping: "$."