Overview
This article explains upcoming changes to payer and beneficiary data requirements for SWIFT payments, as well as the deprecation and removal of selected payer and beneficiary API fields.
These changes are being introduced to support SWIFT’s move toward structured address data under ISO 20022 and to simplify and standardize Currencycloud’s API data model.
Summary of changes
| Change | Notes |
|---|---|
| SWIFT structured address requirements | From 14 November 2026, unstructured payer and beneficiary addresses will no longer be accepted in relevant SWIFT payment messages. |
| Deprecated API fields | Selected fields are deprecated and will be removed after 3 months. |
1. Mandatory address fields for SWIFT payments
From 14 November 2026, SWIFT will no longer process payments containing unstructured payer or beneficiary addresses. Payments containing unstructured payer or beneficiary addresses may be rejected once the new SWIFT requirements take effect.
To support this requirement, the following fields will become mandatory for SWIFT payments for both individual and company payers and beneficiaries.
Beneficiary address fields:
| Field | API Field Name | Relevant Endpoints |
|---|---|---|
| Beneficiary City | beneficiary_city | Create Beneficiary (POST / v2/beneficiaries/create) Validate Beneficiary (POST /v2/beneficiaries/validate) |
| Beneficiary Country | beneficiary_country | Create Beneficiary (POST / v2/beneficiaries/create) Validate Beneficiary (POST /v2/beneficiaries/validate) |
Payer address fields when creating a payment:
| Field | API Field Name | Relevant Endpoints |
|---|---|---|
| Payer City | payer_city | Create Payment (POST /v2/payments/create), Validate Payment (POST /v2/payments/validate) |
| Payer Country | payer_country | Create Payment (POST /v2/payments/create), Validate Payment (POST /v2/payments/validate) |
City and country are already mandatory address fields when creating an account through the Accounts API.
Additional validation will also be introduced to improve address data quality and reduce the risk of network rejections.
Examples of data that may be rejected by validation checks include:
- Country codes entered into city fields
- Placeholder values such as "-", "x", "N/A" or "test"
- Country values that do not comply with ISO alpha-2 standards
Action Required
- Audit your SWIFT beneficiary records to ensure beneficiary city and beneficiary country are populated.
- Audit payer details supplied when creating a payment to ensure payer city and payer country are populated.
- Correct any non-compliant address data before the production enforcement date.
Key dates
| Date | Event |
|---|---|
| Now | Review and update non-compliant payer and beneficiary data |
| 14 November 2026 | Platform enforcement |
2. Deprecated fields
The following fields are now deprecated and will be removed from the API on 26 November 2026:
| Field | API field name | API endpoints | Change |
|---|---|---|---|
| Name of the ultimate beneficiary | ultimate_beneficiary_name |
Create Payment Update Payment Validate Payment |
Deprecated |
| Beneficiary Email |
Update Beneficiary Create Beneficiary |
Deprecated | |
| Nature of beneficiary’s business | business_nature |
Update Beneficiary Create Beneficiary |
Deprecated |
Planned Deprecation
| Field | API field name | API endpoints | Change |
|---|---|---|---|
| Beneficiary nickname | name |
Create Beneficiary (POST /v2/beneficiaries/create) Find Beneficiary (POST /v2/beneficiaries/find) Update Beneficiary (POST/v2/beneficiaries/{id}) |
API: This field will be deprecated on 20 September 2026 and removed on 10 January 2027. No replacement field will be introduced. Currencycloud Direct: The Beneficiary Nickname field will be replaced by an identifier based on the account holder name and account number on 20 September 2026. |
Action
Currencycloud Direct Users: The Beneficiary Nickname field listed above will be removed from the portal on 20 September 2026. It will be replaced in the portal by the account holder name, with the account number used to distinguish between beneficiaries that have the same name.
API Users: Remove beneificary 'name' from API requests before its removal.
Key dates
| Date | Event |
|---|---|
| Now |
The following API fields are deprecated.
|
| 20 September 2026 |
API: The beneficiary name field will be deprecated and made optional across the Beneficiaries API. Currencycloud Direct: The Beneficiary Nickname field will be replaced by an identifier based on the account holder name and account number. |
| 26 November 2026 | Deprecated fields, not including beneficiary 'name', will be removed from the API. |
| 10 January 2027 | The beneficiary 'name' field will be removed from the API. No replacement field will be introduced. |