openapi: 3.1.0
info:
  title: Western Union Mass Payments 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: Health
    description: API health check.
  - name: Customers
    description: Customer account management.
  - name: Balances
    description: Holding balance inquiry.
  - name: Batches
    description: Payment batch lifecycle management.
  - name: Payments
    description: Individual payment management within a batch.
  - name: Orders
    description: Payment order management.
  - name: Quotes
    description: FX rate and payment quote generation.

paths:
  /Ping:
    get:
      operationId: ping
      summary: Health Check
      description: >-
        Verifies the API is available and the client's mTLS credentials are
        valid. Returns a simple pong response.
      tags:
        - Health
      security:
        - mtlsAuth: []
      responses:
        '200':
          description: API is healthy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: pong
        '401':
          description: Invalid or missing client certificate.

  /customers/{clientId}:
    get:
      operationId: getCustomer
      summary: Get Customer
      description: >-
        Returns the account details and configuration for the authenticated
        Western Union partner/customer.
      tags:
        - Customers
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
      responses:
        '200':
          description: Customer account details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          description: Authentication failed.
        '404':
          description: Customer not found.

  /HoldingBalance/{clientId}/{currencyCode}:
    get:
      operationId: getHoldingBalance
      summary: Get Holding Balance
      description: >-
        Returns the current holding balance for the specified currency in the
        partner's WU account. Used to verify sufficient funds before initiating
        payments.
      tags:
        - Balances
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: currencyCode
          in: path
          required: true
          schema:
            type: string
            pattern: '^[A-Z]{3}$'
          description: ISO 4217 currency code (e.g., USD, EUR, GBP).
      responses:
        '200':
          description: Holding balance for the specified currency.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingBalanceResponse'
        '401':
          description: Authentication failed.
        '404':
          description: Client or currency not found.

  /customers/{clientId}/batches/{batchId}:
    get:
      operationId: getBatch
      summary: Get Batch
      description: >-
        Returns the details and current status of a payment batch, including
        counts of received and accepted payments and aggregate amounts.
      tags:
        - Batches
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: The unique batch identifier.
      responses:
        '200':
          description: Batch details and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '404':
          description: Batch not found.

    put:
      operationId: createBatch
      summary: Create Batch
      description: >-
        Creates a new payment batch with the specified batch ID and reference.
        Payments are added to this batch before committing.
      tags:
        - Batches
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: Partner-assigned batch identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference:
                  type: string
                  description: Partner's internal reference for the batch.
              required: [reference]
      responses:
        '200':
          description: Batch created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Invalid request.

    delete:
      operationId: deleteBatch
      summary: Delete Batch
      description: >-
        Deletes a batch that has not yet been committed. Committed batches
        cannot be deleted.
      tags:
        - Batches
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: The batch identifier to delete.
      responses:
        '204':
          description: Batch deleted successfully.
        '404':
          description: Batch not found.

  /customers/{clientId}/batches/{batchId}/payments:
    get:
      operationId: listPayments
      summary: List Payments in Batch
      description: >-
        Returns all payments within a specified batch, with their current
        statuses.
      tags:
        - Payments
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: The batch identifier.
      responses:
        '200':
          description: List of payments in the batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsResponse'
        '404':
          description: Batch not found.

    post:
      operationId: createPayment
      summary: Add Payment to Batch
      description: >-
        Adds a single payment to an existing batch. Payments specify amount,
        currency, beneficiary, and bank account details for international
        money transfer.
      tags:
        - Payments
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: The batch to add the payment to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment added to batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Invalid payment data.

  /customers/{clientId}/batches/{batchId}/payments/{paymentId}:
    get:
      operationId: getPayment
      summary: Get Payment
      description: >-
        Returns the details and current status of a specific payment within
        a batch.
      tags:
        - Payments
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: batchId
          in: path
          required: true
          schema:
            type: string
          description: The batch identifier.
        - name: paymentId
          in: path
          required: true
          schema:
            type: string
          description: The payment identifier.
      responses:
        '200':
          description: Payment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '404':
          description: Payment not found.

  /customers/{clientId}/orders:
    get:
      operationId: listOrders
      summary: List Orders
      description: >-
        Returns all payment orders for the customer account.
      tags:
        - Orders
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
      responses:
        '200':
          description: List of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'

  /customers/{clientId}/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Returns the details and status of a specific payment order.
      tags:
        - Orders
      security:
        - mtlsAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: The partner's Western Union client ID.
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The order identifier.
      responses:
        '200':
          description: Order details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found.

  /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:
  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.

  schemas:
    Customer:
      type: object
      description: Western Union partner customer account details.
      properties:
        id:
          type: string
          description: Western Union client ID.
        name:
          type: string
          description: Partner company name.
        status:
          type: string
          description: Account status.
          enum: [active, suspended, pending]
        settlementCurrency:
          type: string
          description: Default settlement currency (ISO 4217).
        createdOn:
          type: string
          format: date-time
        lastUpdatedOn:
          type: string
          format: date-time

    HoldingBalance:
      type: object
      properties:
        currencyCode:
          type: string
          description: ISO 4217 currency code.
        amount:
          type: number
          format: double
          description: Available balance amount.

    HoldingBalanceResponse:
      type: object
      properties:
        clientId:
          type: string
        currencyCode:
          type: string
        balance:
          $ref: '#/components/schemas/HoldingBalance'

    AggregateAmount:
      type: object
      properties:
        currencyCode:
          type: string
        totalAmount:
          type: number
          format: double

    BatchResponse:
      type: object
      description: Payment batch details.
      properties:
        id:
          type: string
          description: Batch identifier.
        reference:
          type: string
          description: Partner's internal reference.
        createdOn:
          type: string
          format: date-time
        lastUpdatedOn:
          type: string
          format: date-time
        numberOfReceivedPayments:
          type: integer
          description: Total payments received in the batch.
        numberOfAcceptedPayments:
          type: integer
          description: Payments accepted for processing.
        aggregateAmounts:
          type: array
          items:
            $ref: '#/components/schemas/AggregateAmount'
      required: [id, reference, createdOn, numberOfReceivedPayments, numberOfAcceptedPayments]

    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        line3:
          type: string
        city:
          type: string
        stateOrProv:
          type: string
        zipOrPostal:
          type: string
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code.

    Beneficiary:
      type: object
      description: Payment recipient details.
      properties:
        id:
          type: string
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phoneNumber:
          type: string
        cellNumber:
          type: string
        dateOfBirth:
          type: string
          format: date
        gender:
          type: string
          enum: [M, F]
        type:
          type: string
          enum: [individual, business]
        businessName:
          type: string
        businessRegistrationNumber:
          type: string
        businessRegistrationCountry:
          type: string
        taxId:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    BankAccount:
      type: object
      description: Beneficiary bank account details for wire transfer.
      properties:
        id:
          type: string
        accountNumber:
          type: string
        accountType:
          type: string
          enum: [checking, savings, current]
        bankName:
          type: string
        bankCode:
          type: string
          description: SWIFT/BIC code.
        bankBranchCode:
          type: string
        bankBranchName:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    ThirdPartyRemitter:
      type: object
      description: Third-party sender information for compliance.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        businessName:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    PaymentRequest:
      type: object
      description: Request body for adding a payment to a batch.
      properties:
        partnerReference:
          type: string
          description: Partner's internal reference for the payment.
        amount:
          type: integer
          description: Payment amount in minor units (e.g., cents).
        currencyCode:
          type: string
          description: ISO 4217 payment currency code.
        settlementCurrency:
          type: string
          description: ISO 4217 settlement currency code.
        paymentMethod:
          type: string
          enum: [bankTransfer, wireTransfer, swift]
        purposeOfPayment:
          type: string
        remittanceType:
          type: string
        isFixedAmountInSettlementCurrency:
          type: boolean
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        bankAccount:
          $ref: '#/components/schemas/BankAccount'
        thirdPartyRemitter:
          $ref: '#/components/schemas/ThirdPartyRemitter'
      required: [amount, currencyCode, beneficiary, bankAccount]

    PaymentResponse:
      type: object
      description: Payment details and status.
      properties:
        id:
          type: string
        customerId:
          type: string
        status:
          type: string
          enum: [received, accepted, rejected, processed, returned, pending]
        errorCode:
          type: string
        partnerReference:
          type: string
        paymentReference:
          type: string
        createdOn:
          type: string
          format: date-time
        lastUpdatedOn:
          type: string
          format: date-time
        paymentMethod:
          type: string
        amount:
          type: integer
        currencyCode:
          type: string
        settlementAmount:
          type: integer
        settlementCurrencyCode:
          type: string
        chargeType:
          type: string
        amountReturned:
          type: number
        amountReturnedCurrency:
          type: string
        purposeOfPayment:
          type: string
        remittanceType:
          type: string
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        bankAccount:
          $ref: '#/components/schemas/BankAccount'

    PaymentsResponse:
      type: object
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentResponse'

    OrderResponse:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        status:
          type: string
          enum: [pending, processed, rejected, cancelled]
        settlementCurrency:
          type: string
        partnerReference:
          type: string
        createdOn:
          type: string
          format: date-time
        lastUpdatedOn:
          type: string
          format: date-time
        errorCode:
          type: string

    OrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderResponse'

    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]

    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'

    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