Stitch Open Banking and Payments

naftiko: 1.0.0-alpha2
info:
  label: Stitch Open Banking and Payments
  description: Unified open banking and payments workflow for African fintech applications. Combines pay-in payment initiation,
    bank account data access, and outbound disbursements into a single integration covering South Africa and Nigeria. Designed
    for e-commerce platforms, marketplaces, and financial applications that need to accept payments, access account data,
    and send payouts.
  tags:
  - Africa
  - Open Banking
  - Payments
  - Financial Data
  - South Africa
  - Nigeria
  - Fintech
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    STITCH_CLIENT_ID: STITCH_CLIENT_ID
    STITCH_CLIENT_SECRET: STITCH_CLIENT_SECRET
    STITCH_ACCESS_TOKEN: STITCH_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: stitch
    baseUri: https://api.stitch.money
    description: Stitch GraphQL API for payments and financial data.
    authentication:
      type: bearer
      token: '{{STITCH_ACCESS_TOKEN}}'
    resources:
    - name: graphql
      path: /graphql
      description: Stitch GraphQL endpoint for all operations.
      operations:
      - name: initiate-payment
        method: POST
        description: Initiate a Pay By Bank payment request.
        body:
          type: json
          data:
            query: 'mutation InitiatePayment($input: PaymentInitiationRequestInput!) { clientPaymentInitiationRequestCreate(input:
              $input) { paymentInitiationRequest { id url status } } }'
            variables:
              input:
                amount:
                  quantity: '{{tools.amount}}'
                  currency: '{{tools.currency}}'
                payerReference: '{{tools.payerReference}}'
                beneficiaryReference: '{{tools.beneficiaryReference}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.data.clientPaymentInitiationRequestCreate
      - name: get-payment-status
        method: POST
        description: Get the current status of a payment initiation request.
        body:
          type: json
          data:
            query: 'query GetPaymentStatus($paymentRequestId: ID!) { node(id: $paymentRequestId) { ... on PaymentInitiationRequest
              { id status amount { quantity currency } } } }'
            variables:
              paymentRequestId: '{{tools.paymentRequestId}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.data.node
      - name: list-bank-accounts
        method: POST
        description: List bank accounts linked by the user.
        body:
          type: json
          data:
            query: query ListBankAccounts { user { bankAccounts { id name accountNumber bankId availableBalance { quantity
              currency } currentBalance { quantity currency } } } }
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.data.user.bankAccounts
      - name: get-account-transactions
        method: POST
        description: Retrieve transactions for a linked bank account.
        body:
          type: json
          data:
            query: 'query GetTransactions($accountId: ID!, $first: Int, $after: String) { node(id: $accountId) { ... on BankAccount
              { transactions(first: $first, after: $after) { edges { node { id amount { quantity currency } date description
              reference } } pageInfo { hasNextPage endCursor } } } } }'
            variables:
              accountId: '{{tools.accountId}}'
              first: '{{tools.first}}'
              after: '{{tools.after}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.data.node.transactions
      - name: create-disbursement
        method: POST
        description: Create an outbound payment disbursement.
        body:
          type: json
          data:
            query: 'mutation CreateDisbursement($input: DisbursementCreateInput!) { disbursementCreate(input: $input) { disbursement
              { id status amount { quantity currency } } } }'
            variables:
              input:
                amount:
                  quantity: '{{tools.amount}}'
                  currency: '{{tools.currency}}'
                beneficiaryAccountNumber: '{{tools.beneficiaryAccountNumber}}'
                beneficiaryBankId: '{{tools.beneficiaryBankId}}'
                reference: '{{tools.reference}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.data.disbursementCreate
  exposes:
  - type: rest
    port: 8080
    namespace: open-banking-api
    description: Unified REST API for African open banking payments, account data, and disbursements via Stitch.
    resources:
    - path: /v1/payments
      name: payments
      description: Payment initiation requests.
      operations:
      - method: POST
        name: initiate-payment
        description: Initiate a Pay By Bank payment for a customer.
        call: stitch.initiate-payment
        with:
          amount: rest.amount
          currency: rest.currency
          payerReference: rest.payerReference
          beneficiaryReference: rest.beneficiaryReference
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{paymentRequestId}
      name: payment
      description: Payment status retrieval.
      operations:
      - method: GET
        name: get-payment-status
        description: Get current status of a payment initiation request.
        call: stitch.get-payment-status
        with:
          paymentRequestId: rest.paymentRequestId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/bank-accounts
      name: bank-accounts
      description: Linked user bank accounts.
      operations:
      - method: GET
        name: list-bank-accounts
        description: List bank accounts linked by the user.
        call: stitch.list-bank-accounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/bank-accounts/{accountId}/transactions
      name: transactions
      description: Bank account transactions.
      operations:
      - method: GET
        name: get-account-transactions
        description: Get transactions for a linked bank account.
        call: stitch.get-account-transactions
        with:
          accountId: rest.accountId
          first: rest.first
          after: rest.after
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/disbursements
      name: disbursements
      description: Outbound payment disbursements.
      operations:
      - method: POST
        name: create-disbursement
        description: Create an outbound disbursement to a bank account.
        call: stitch.create-disbursement
        with:
          amount: rest.amount
          currency: rest.currency
          beneficiaryAccountNumber: rest.beneficiaryAccountNumber
          beneficiaryBankId: rest.beneficiaryBankId
          reference: rest.reference
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: open-banking-mcp
    transport: http
    description: MCP server for AI-assisted African open banking operations including payment initiation, account data retrieval,
      and payout management.
    tools:
    - name: initiate-payment
      description: Initiate a Pay By Bank payment in South Africa or Nigeria. Returns a payment URL to redirect the customer
        for bank authorization.
      hints:
        readOnly: false
      call: stitch.initiate-payment
      with:
        amount: tools.amount
        currency: tools.currency
        payerReference: tools.payerReference
        beneficiaryReference: tools.beneficiaryReference
      outputParameters:
      - type: object
        mapping: $.
    - name: get-payment-status
      description: Check the status of a payment initiation request (Pending, Complete, Cancelled, or Error). Use to poll
        for payment completion.
      hints:
        readOnly: true
        idempotent: true
      call: stitch.get-payment-status
      with:
        paymentRequestId: tools.paymentRequestId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-bank-accounts
      description: List bank accounts linked by the user. Use to show available accounts for payment or data analysis.
      hints:
        readOnly: true
        idempotent: true
      call: stitch.list-bank-accounts
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-transactions
      description: Retrieve transaction history for a linked bank account. Supports Relay-style cursor pagination via first/after
        parameters.
      hints:
        readOnly: true
        idempotent: true
      call: stitch.get-account-transactions
      with:
        accountId: tools.accountId
        first: tools.first
        after: tools.after
      outputParameters:
      - type: object
        mapping: $.
    - name: create-disbursement
      description: Send an outbound payment disbursement to a beneficiary bank account. Use for marketplace payouts, refunds,
        or mass payments.
      hints:
        readOnly: false
      call: stitch.create-disbursement
      with:
        amount: tools.amount
        currency: tools.currency
        beneficiaryAccountNumber: tools.beneficiaryAccountNumber
        beneficiaryBankId: tools.beneficiaryBankId
        reference: tools.reference
      outputParameters:
      - type: object
        mapping: $.