Individual payment management within a batch.
openapi: 3.1.0
info:
title: Western Union Mass Balances 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: Payments
description: Individual payment management within a batch.
paths:
/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.
components:
schemas:
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'
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'
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'
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'
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
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.
PaymentsResponse:
type: object
properties:
payments:
type: array
items:
$ref: '#/components/schemas/PaymentResponse'
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.