openapi: 3.1.0
info:
  title: Thunes Money Transfer API
  description: |
    Real-time cross-border money transfer to bank accounts, mobile wallets,
    cash pickup, and cards via the Thunes global payouts network.
  version: "2.0"
  contact:
    name: Thunes Developer Portal
    url: https://docs.thunes.com/money-transfer/v2/
servers:
  - url: https://api.thunes.com/v2/money-transfer
    description: Production
  - url: https://api-pp.thunes.com/v2/money-transfer
    description: Pre-production / Sandbox
security:
  - basicAuth: []
tags:
  - name: Connectivity
  - name: Discovery
  - name: Account Management
  - name: Credit Parties
  - name: Quotations
  - name: Transactions
  - name: Simulation
paths:
  /ping:
    get:
      tags: [Connectivity]
      summary: Check API status
      operationId: ping
      responses:
        "200":
          description: API is reachable.
  /services:
    get:
      tags: [Discovery]
      summary: List available services
      operationId: listServices
      responses:
        "200":
          description: List of services.
  /payers:
    get:
      tags: [Discovery]
      summary: List available payers
      operationId: listPayers
      responses:
        "200":
          description: List of payers.
  /payers/{id}:
    get:
      tags: [Discovery]
      summary: Get payer details
      operationId: getPayer
      parameters:
        - $ref: '#/components/parameters/PayerId'
      responses:
        "200":
          description: Payer details.
  /payers/{id}/rates:
    get:
      tags: [Discovery]
      summary: Retrieve payer rates
      operationId: getPayerRates
      parameters:
        - $ref: '#/components/parameters/PayerId'
      responses:
        "200":
          description: Payer rate table.
  /countries:
    get:
      tags: [Discovery]
      summary: List countries
      operationId: listCountries
      responses:
        "200":
          description: List of countries.
  /lookups/BIC/{swift_bic_code}:
    get:
      tags: [Discovery]
      summary: BIC code lookup
      operationId: lookupBIC
      parameters:
        - name: swift_bic_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: BIC lookup result.
  /balances:
    get:
      tags: [Account Management]
      summary: Retrieve account balances
      operationId: listBalances
      responses:
        "200":
          description: List of balances.
  /balances/{balance_id}/movements:
    get:
      tags: [Account Management]
      summary: Get balance movements
      operationId: getBalanceMovements
      parameters:
        - name: balance_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Movements for the balance.
  /balances/{balance_id}/topup_instructions:
    get:
      tags: [Account Management]
      summary: Get topup instructions
      operationId: getTopupInstructions
      parameters:
        - name: balance_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Topup instructions.
  /reports:
    get:
      tags: [Account Management]
      summary: List reports
      operationId: listReports
      responses:
        "200":
          description: List of reports.
  /reports/{id}:
    get:
      tags: [Account Management]
      summary: Get report details
      operationId: getReport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Report details.
  /reports/{id}/files:
    get:
      tags: [Account Management]
      summary: List report files
      operationId: listReportFiles
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Report files.
  /reports/{report_id}/files/{id}:
    get:
      tags: [Account Management]
      summary: Get a report file
      operationId: getReportFile
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Report file content.
  /payers/{id}/{transaction_type}/credit-party-information:
    post:
      tags: [Credit Parties]
      summary: Get beneficiary credit-party information
      operationId: getCreditPartyInformation
      parameters:
        - $ref: '#/components/parameters/PayerId'
        - name: transaction_type
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Credit party info.
  /payers/{id}/{transaction_type}/credit-party-verification:
    post:
      tags: [Credit Parties]
      summary: Verify beneficiary account status
      operationId: verifyCreditParty
      parameters:
        - $ref: '#/components/parameters/PayerId'
        - name: transaction_type
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Verification result.
  /quotations:
    post:
      tags: [Quotations]
      summary: Create a quotation
      operationId: createQuotation
      responses:
        "201":
          description: Quotation created.
  /quotations/{id}:
    get:
      tags: [Quotations]
      summary: Retrieve quotation by ID
      operationId: getQuotation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Quotation.
  /quotations/ext-{external_id}:
    get:
      tags: [Quotations]
      summary: Retrieve quotation by external ID
      operationId: getQuotationByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Quotation.
  /quotations/{id}/transactions:
    post:
      tags: [Transactions]
      summary: Create transaction from quotation ID
      operationId: createTransactionFromQuotation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Transaction created.
  /quotations/ext-{external_id}/transactions:
    post:
      tags: [Transactions]
      summary: Create transaction from external quotation ID
      operationId: createTransactionFromExternalQuotation
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Transaction created.
  /transactions/{id}:
    get:
      tags: [Transactions]
      summary: Retrieve transaction by ID
      operationId: getTransaction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction.
  /transactions/ext-{external_id}:
    get:
      tags: [Transactions]
      summary: Retrieve transaction by external ID
      operationId: getTransactionByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction.
  /transactions/{id}/attachments:
    get:
      tags: [Transactions]
      summary: List attachments for a transaction
      operationId: listTransactionAttachments
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Attachments.
    post:
      tags: [Transactions]
      summary: Add attachment to a transaction
      operationId: addTransactionAttachment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Attachment added.
  /transactions/ext-{external_id}/attachments:
    get:
      tags: [Transactions]
      summary: List attachments by external transaction ID
      operationId: listTransactionAttachmentsByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Attachments.
    post:
      tags: [Transactions]
      summary: Add attachment by external transaction ID
      operationId: addTransactionAttachmentByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Attachment added.
  /transactions/{id}/confirm:
    post:
      tags: [Transactions]
      summary: Confirm a transaction by ID
      operationId: confirmTransaction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction confirmed.
  /transactions/ext-{external_id}/confirm:
    post:
      tags: [Transactions]
      summary: Confirm a transaction by external ID
      operationId: confirmTransactionByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction confirmed.
  /transactions/{id}/cancel:
    post:
      tags: [Transactions]
      summary: Cancel a transaction by ID
      operationId: cancelTransaction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction cancelled.
  /transactions/ext-{external_id}/cancel:
    post:
      tags: [Transactions]
      summary: Cancel a transaction by external ID
      operationId: cancelTransactionByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction cancelled.
  /simulation/transactions/{id}/possible-transitions:
    get:
      tags: [Simulation]
      summary: List possible status transitions (pre-production)
      operationId: listPossibleTransitions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Possible transitions.
  /simulation/transactions/{id}/{status_name}:
    get:
      tags: [Simulation]
      summary: Simulate transaction status change by ID (pre-production)
      operationId: simulateTransactionStatus
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: status_name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Status simulated.
  /simulation/transactions/ext-{external_id}/{status_name}:
    get:
      tags: [Simulation]
      summary: Simulate transaction status change by external ID (pre-production)
      operationId: simulateTransactionStatusByExternalId
      parameters:
        - name: external_id
          in: path
          required: true
          schema:
            type: string
        - name: status_name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Status simulated.
components:
  parameters:
    PayerId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Payer identifier.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using API key as user-ID and API secret as password.