Changelog

Copy

• KYC Review API now supports submitting the SSN_DECLARATION type for US customers, either with a Social Security Number or with a reason the SSN is unavailable.

• New guide for Webhook mTLS public CA support change.
• Added a notice to the mTLS for webhooks guide linking to the Public CA support change guide.

• Updated the file upload response documentation to include the file creation timestamp (createdAt) and upload purpose (purpose).

• Fixed the documentation for the ultimate beneficial owner create, update, and list endpoints:

  • Documented supported optional address, identity, nationality, email, and place-of-birth fields in create and update requests.
  • Documented returned city and state fields in responses for all three endpoints.
  • Corrected the documented success status for the create endpoint from 200 OK to 201 Created.

• Fixed the documentation for business profile create and update requests: documented supported optional business contactDetails object.

2026Q4 Version released. This consolidated entry covers the new, updated and removed endpoints for the version.

• Added a SAML Assertion Consumer Service endpoint (POST /{gv}/login/saml2/sso) to receive single sign-on responses from an identity provider.
• Added an endpoint (GET /{gv}/saml2/metadata) to retrieve Wise’s SAML service-provider metadata for configuring single sign-on with an identity provider.
• Replaced Retrieve Bank Account Details with Get account details by ID under Balances. The new endpoint supports GB, US and BE account details; requests for unsupported countries return 404 Not Found. For other countries, continue to use the 2026Q3 endpoint.
• Added file upload under Cases to submit files as supporting documentation for cases.
• Updated GPI tracking availability in the 2026Q4 API. Partners can retrieve SWIFT tracking information for transfers they own using a transfer ID or UETR.
• Added transfer delivery update simulation to trigger a transfers#delivery-update webhook in sandbox without changing the transfer state.
• Added Create a settlement allocation request to submit a Settlement Allocation Request (SAR) file containing instructions for allocating settled funds across payment intents.
• Added Get a settlement allocation to retrieve a settlement allocation by ID, with the option to include a paginated list of its payment intents.
• Added settlement funds simulation to simulate receipt of funds for a settlement allocation, allowing integrations to test settlement funding flows.

• Payment Instrument API endpoints added to API reference.

• Business profile classification moves to industryCategories as a field change only. The existing create and update business profile endpoints accept it, so no endpoint migration is required. Earlier guidance describing separate endpoints for this change no longer applies.
• Documentation has been updated to reflect this, including the business categories list and Migrating to industry categories.

• Updated Partner Support Domain name to Cases to better describe the endpoints within it.

• KYC Review API now supports submitting the LEGAL_ENTITY_SHAREHOLDER type.

• Added a guide for fees and pricing for the issue card product.

• Add support for custom reference, sender and beneficiary details in bank transaction import simulation.

• Added support for detailed sender bank information including LEI, Clearing System Member ID, Clearing System Code and structured address in swift-in simulation.
• Added schema version 4.3.0 with LEI, Clearing System Member ID and Clearing System Code support to swift-in#credit webhook.
• Deprecated schema version 3.0.0 for swift-in#credit webhook. This version uses flattened unstructured addresses. Migrate to 4.3.0 for enhanced address and bank details information.

• Updated v5.0.0 webhook usage in the payout failure guide.
• Updated OAuth 2.0 and token guides to indicate partners on the embedded integration model use client credentials tokens for all authenticated requests. This integration model no longer relies on user objects and so user access tokens no longer apply.

• KYC Review API now supports submitting the following requirement types:
  • BUSINESS_CONTROLLING_PERSON
  • BUSINESS_SHAREHOLDER_CONTACT_DETAILS
  • BUSINESS_INCOME_CLASSIFICATION

• Add newly exposed payout failure reasons TECHNICAL_ISSUE, TECHNICAL_ISSUE_RETRYABLE to payout failure guide.
• Upgrade failure_reason_code from a free-text string to a committed enum in v5.0.0 of transfers#payout-failure webhook, ensuring stable, machine-readable values partners can rely on.

New: Automated RFI case handling for Partners Partners can now receive, respond to, and track Requests for Information (RFIs) programmatically through the Cases API. This enables faster resolution of compliance and operations queries through automated workflows.

• New Case handling guide - Receive RFIs, submit structured responses, track case status, and automate case handling in your backend systems.
• New Respond to RFIs guide - Step-by-step implementation for handling automated and freeform RFIs.

Cases API (new)

• Create a case - Open support or operations cases with Wise.
• Retrieve a case - Get full case details including all messages and reference information.
• Submit a message - Respond to RFIs with structured submission types or freeform messages.

Deprecated: Legacy Cases API v1 The following v1 Case endpoints are now deprecated. Migrate to the new Cases API for structured RFI handling, typed messages, and improved case management:

• Deprecated GET /v1/cases/{caseId} - Use GET /cases/{caseId} instead. New endpoint returns typed messages with structured content, reference information, and aligned status values.
• Deprecated GET /v1/cases/{caseId}/comments - Use GET /cases/{caseId} instead. Messages are now included in the case response with full content structure.
• Deprecated PUT /v1/cases/{caseId}/comments - Use POST /cases/{caseId}/messages instead. New endpoint supports structured submission types for RFI responses and freeform messages.

partner-support#case-changed webhook

• Add schema version 5.0.0 for partner-support#case-changed webhook with restructured payload.
• Deprecated schema versions 4.0.0 and 2.0.0 for partner-support#case-changed webhook. These versions use legacy payload structure. Migrate to 5.0.0 for structured message content and full message history in each webhook payload.

• 2026Q3 Version released, the first global, datebased API version is now available, enabling better compatibility, documentation and easier change management. This is currently opt-in. Previous endpoint-based versions remain available. See Global API versioning for more.
• Business profile creation (global versions): Global versions do not support POST /v2/profiles/business-profile. Use POST /v3/profiles/business-profile instead (creates the business profile and authorised representative in one request via businessRepresentative). The v2 endpoint remains available in the previous endpoint-based API; authentication and scopes are unchanged.
• Deprecated endpoints in global versions: Some endpoints already deprecated in the non-versioned API are not included in global versions. If you use them, move to the documented replacements before adopting a global version. See Global API versioning.

• Add new Partner pooled funding guide for cards.
• Add data.resource.incoming_transfer_type enum to swift-in#credit webhook 4.2.0 schema version.

• Added conditional attributes field to the KYC requirement object. Certain requirement types now return additional contextual metadata.
• Attribute changes on KYC requirements now trigger a kyc-reviews#state-change webhook notification.

• Deprecated first_line in favour of address_lines in swift-in#credit webhook address properties.

• Updated Client credentials token format migration with sandbox timeline.

• Card Orders: The address field is now optional when ordering virtual cards, but required for physical cards. See the Card address validation guide for details.

• Updated Subscribe to webhooks guide to include both subscription methods: subscribe via Developer Hub and subscribe via API.

• Revised the Send money refund guides to provide more details about refund methods, how they work, what methods apply to which funding models, and partial refunds. Also added example webhook payloads.
  • Refund to sender bank account
  • Refund to balance
  • Refund via net settlement

• New guide for Client credentials token format migration.

• New guide for Subscribing to webhooks
• New guide for Viewing and Retrying webhooks
• New guides for Recipient verification and currency-specific guides for currencies that support additional recipient account verification checks:
  • CNY recipient verification
  • IDR recipient verification
  • INR recipient verification
  • KRW recipient verification

• Improve consistency regarding KYC review fields across the documentation.
• Document correct return response from the KYC review endpoints
• Improve wording in the Update KYC review endpoint

• Add instructedAmount and instructedCurrencyCode fields to swift-in simulation endpoint

• Added a new value VERIFIED to the KYC requirement state. This value will be returned in the webhook and API response if the requirement was submitted and verified on our side.
• Added new transfer payout failure simulation endpoint. Triggers transfers#payout-failure webhook in Sandbox.

• Added sandbox support for transfer refund webhooks. Simulating funds_refunded now triggers a transfers#refund webhook with a simulated refund amount.

• Add bank_details fields within recipient and sender to swift-in#credit webhook

• Update copy in Get Wise JOSE public key to accommodate both JWS + JWE.

• Add data.requested_by_customer field to profiles#state-change webhook

• New guide for JOSE JWS Key Rotation.

• New guide for API and hybrid customer onboarding for embedded partners.
• Significant updates to the introduction to Wise-performed KYC and Hosted customer onboarding guides. Provides more in-depth details about available customer onboarding methods and instructions for using the Wise-hosted method.

• Add structured addresses and previous_instructing_agents in swift-in#credit webhook v4.0.0.

• Add keyId field to Get Wise public signing key endpoint.
• Documented global X-External-Correlation-Id header on all API operations. See correlation ID guide.
• Documented global x-trace-id header on all API operations.
• Documented 429 Too Many Requests response with Retry-After and X-Rate-Limited-By headers on all API operations.

• Consolidated Client Credentials Token and User Tokens into a single OAuth Token endpoint

• Updated Auth and Security guide
• New OAuth 2.0 setup guide
• New Client credentials tokens guide
• New User access tokens guide
• New Refresh tokens guide

• Rename Push Provisioning api reference section to Digital Wallet
• Update digital wallet guide
• Add payment token activation endpoint to activate a card payment token for manual provisioning
• Add cards#manual-provisioning-verification webhook

• Add new Event Ordering guide. Webhook events may not be delivered in the order they occurred — this guide explains how to use ordering fields to reconcile the correct sequence.
• Add schema version 4.0.0 for all webhook event types. This version provides consistent millisecond-precision timestamps across all events, making it easier to determine event order. We recommend updating your subscriptions to use 4.0.0 to order events reliably.

• Add guide for X-External-Correlation-Id header usage
• Update error codes for verify PIN and verify device fingerprint endpoints

• Add relayed authorisation guide to card issuance
• Update card transaction api to include relayed authorisation data
• Update card transaction webhook to include relayed authorisation data

• Add fees and previous instructing agent in swift-in simulation endpoint

• Add details for submitting Tax Residency Kyc Requirement KYC Requirement Submit

• Adds support for providing the following on originators of third-party transfers
  • nationality: for PRIVATE originators
  • businessRegistrationDate: for BUSINESS originators

• Multiple ID fields are now explicitly documented as int64 (64-bit integer). Please ensure your integration stores these IDs using the appropriate 64-bit type (e.g., Long in Java, BIGINT in SQL).

  Key fields to note:

  • transfer ID - approaching the int32 upper bound
  • recipient ID - approaching the int32 upper bound
  • card transaction ID - past the int32 upper bound
  • user ID
  • profile ID
  • balance ID

• See detailed data type changelog for all updated fields and endpoints.