openapi: 3.1.0
info:
  title: Western Union Mass Payments Balances Quotes API
  description: The Western Union Mass Payments API enables financial institutions and enterprise customers to send up to 10,000 international payments in a single batch across 130+ currencies in 200+ countries and territories. The API supports payment lifecycle management including batch creation, adding payments, FX quotes, committing, and tracking. Authentication requires mutual TLS (mTLS) client certificates provided by Western Union upon partnership enrollment.
  version: v1
  contact:
    name: Western Union Partnership Program
    url: https://developer.westernunion.com/getting-started.html
    email: wuconnect@westernunion.com
  license:
    name: Western Union Partner Terms
    url: https://developer.westernunion.com/getting-started.html
servers:
- url: https://api.westernunion.com
  description: Production endpoint
- url: https://api-sandbox.westernunion.com
  description: Sandbox for testing
tags:
- name: Quotes
  description: FX rate and payment quote generation.
paths:
  /customers/{clientId}/quotes:
    post:
      operationId: createQuote
      summary: Create FX Quote
      description: Generates a foreign exchange rate quote for a currency conversion. The quote includes rate, inverted rate, and settlement details and has a limited validity period.
      tags:
      - Quotes
      security:
      - mtlsAuth: []
      parameters:
      - name: clientId
        in: path
        required: true
        schema:
          type: string
        description: The partner's Western Union client ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '201':
          description: FX quote created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Invalid quote request.
components:
  schemas:
    QuoteRequest:
      type: object
      properties:
        tradeCurrency:
          type: string
          description: Source currency ISO 4217 code.
        settlementCurrency:
          type: string
          description: Destination currency ISO 4217 code.
        tradeAmount:
          type: integer
          description: Amount to convert in minor units.
        partnerReference:
          type: string
      required:
      - tradeCurrency
      - settlementCurrency
      - tradeAmount
    QuotedItem:
      type: object
      properties:
        isDirectRate:
          type: boolean
        rate:
          type: number
          format: double
          description: FX rate (trade to settlement).
        rateInverted:
          type: number
          format: double
          description: Inverted FX rate.
        decimalsDirect:
          type: integer
        decimalsIndirect:
          type: integer
        tradeAmount:
          type: integer
        settlementAmount:
          type: integer
        tradeCurrency:
          type: string
        settlementCurrency:
          type: string
    QuoteResponse:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        partnerReference:
          type: string
        status:
          type: string
          enum:
          - active
          - expired
          - used
        createdOn:
          type: string
          format: date-time
        lastUpdatedOn:
          type: string
          format: date-time
        expirationIntervalInSec:
          type: integer
          description: Seconds until the quote expires.
        quotedItems:
          $ref: '#/components/schemas/QuotedItem'
  securitySchemes:
    mtlsAuth:
      type: mutualTLS
      description: Mutual TLS authentication using client certificates provided by Western Union upon enrollment in the Partnership Program. Include the certificate and key with every request.