name: payments-management
description: Workflow capability for managing end-to-end payment acceptance, global account operations, cross-border payouts, and foreign exchange using the Airwallex API.
version: "1.0"
provider: Airwallex
imports:
  - shared/airwallex-api.yaml
tools:
  - name: create_payment_intent
    description: Create a new Airwallex payment intent to begin a checkout session.
    operation: createPaymentIntent
    inputs:
      - name: amount
        type: number
        required: true
        description: Payment amount in the specified currency.
      - name: currency
        type: string
        required: true
        description: ISO 4217 currency code (e.g., USD, AUD, GBP).
      - name: merchant_order_id
        type: string
        required: false
        description: Merchant's own order identifier for reconciliation.
      - name: customer_id
        type: string
        required: false
        description: Airwallex customer ID if the payer is a known customer.
    outputs:
      - name: id
        type: string
        description: Payment intent ID.
      - name: client_secret
        type: string
        description: Client secret for frontend SDK initialization.
      - name: status
        type: string
        description: Payment intent status.

  - name: confirm_payment_intent
    description: Confirm a payment intent to trigger payment processing.
    operation: confirmPaymentIntent
    inputs:
      - name: id
        type: string
        required: true
        description: The payment intent ID to confirm.
      - name: payment_method
        type: object
        required: true
        description: Payment method details (card, bank transfer, etc.).
    outputs:
      - name: status
        type: string
        description: Updated payment intent status.
      - name: captured_amount
        type: number
        description: Amount captured after confirmation.

  - name: get_payment_intent
    description: Retrieve the status and details of a payment intent.
    operation: getPaymentIntent
    inputs:
      - name: id
        type: string
        required: true
        description: Payment intent ID.
    outputs:
      - name: status
        type: string
        description: Current payment intent status.
      - name: amount
        type: number
        description: Payment amount.

  - name: list_payment_intents
    description: List all payment intents with optional filtering by status or date range.
    operation: listPaymentIntents
    inputs:
      - name: status
        type: string
        required: false
        description: Filter by payment intent status.
      - name: from_created_at
        type: string
        required: false
        description: Start date filter (ISO 8601 datetime).
      - name: to_created_at
        type: string
        required: false
        description: End date filter (ISO 8601 datetime).
    outputs:
      - name: items
        type: array
        description: List of matching payment intents.

  - name: get_account
    description: Retrieve a global multi-currency account and its current status.
    operation: getAccount
    inputs:
      - name: id
        type: string
        required: true
        description: Account ID.
    outputs:
      - name: account_name
        type: string
        description: Business name of the account holder.
      - name: status
        type: string
        description: Account status (ACTIVE, SUSPENDED, etc.).
      - name: primary_currency
        type: string
        description: Primary currency of the account.

  - name: list_account_balances
    description: List all currency balances held in a global account.
    operation: listAccountBalances
    inputs:
      - name: id
        type: string
        required: true
        description: Account ID.
    outputs:
      - name: balances
        type: array
        description: Array of currency balance objects.

  - name: get_fx_quote
    description: Request a foreign exchange rate quote for a currency conversion.
    operation: getFxQuote
    inputs:
      - name: from_currency
        type: string
        required: true
        description: Source currency ISO 4217 code.
      - name: to_currency
        type: string
        required: true
        description: Target currency ISO 4217 code.
      - name: from_amount
        type: number
        required: false
        description: Amount to convert from source currency.
    outputs:
      - name: quote_id
        type: string
        description: Unique quote identifier for locking the rate.
      - name: rate
        type: number
        description: Quoted exchange rate.
      - name: to_amount
        type: number
        description: Estimated target amount after conversion.
      - name: expires_at
        type: string
        description: Timestamp when the quote expires.

  - name: execute_currency_conversion
    description: Execute a currency conversion using a locked FX quote.
    operation: convertCurrency
    inputs:
      - name: quote_id
        type: string
        required: true
        description: FX quote ID obtained from get_fx_quote.
      - name: from_amount
        type: number
        required: true
        description: Amount to convert.
    outputs:
      - name: conversion_id
        type: string
        description: Unique conversion transaction ID.
      - name: to_amount
        type: number
        description: Final converted amount.

  - name: create_transfer
    description: Initiate a cross-border payout to a beneficiary account.
    operation: createTransfer
    inputs:
      - name: beneficiary_id
        type: string
        required: true
        description: Airwallex beneficiary ID.
      - name: source_amount
        type: number
        required: true
        description: Amount to send from the source account.
      - name: source_currency
        type: string
        required: true
        description: Currency of the source amount.
      - name: target_currency
        type: string
        required: false
        description: Currency for the beneficiary to receive.
      - name: reference
        type: string
        required: false
        description: Payment reference text.
    outputs:
      - name: id
        type: string
        description: Transfer ID.
      - name: status
        type: string
        description: Initial transfer status.

  - name: get_transfer
    description: Retrieve the status and details of an existing transfer.
    operation: getTransfer
    inputs:
      - name: id
        type: string
        required: true
        description: Transfer ID.
    outputs:
      - name: status
        type: string
        description: Current transfer status.
      - name: target_amount
        type: number
        description: Amount received by the beneficiary.
      - name: fx_rate
        type: number
        description: Applied foreign exchange rate.