diff --git a/openapi/source.json b/openapi/source.json index 72b9d42..4ddfe99 100644 --- a/openapi/source.json +++ b/openapi/source.json @@ -1,6 +1,6 @@ { "url": "https://docs.wise.com/_bundle/api-reference/@latest/index.json?download", - "retrievedAt": "2026-09-18T09:01:06.679Z", - "apiVersion": "2026Q3", - "sha256": "3d9b501a3c2e179c04be17ac875322b84dd1c52a6ec9d3ce7c239ea961efcffc" + "retrievedAt": "2026-11-05T08:24:31.049Z", + "apiVersion": "2026Q4", + "sha256": "91076ed54ec56e012013d4c50e640b9e3cace9796c4a9675c9304ab63c082db2" } diff --git a/openapi/wise.json b/openapi/wise.json index 8cf6c18..524724f 100644 --- a/openapi/wise.json +++ b/openapi/wise.json @@ -2,16 +2,16 @@ "openapi": "3.1.0", "info": { "title": "Wise Platform API", - "version": "", - "description": "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**
\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n" + "version": "2026Q4", + "description": "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes, except the browser-based [SAML](/api-reference/saml) single sign-on endpoints, which return XML metadata or redirects.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nWe recommend connecting to our Docs MCP Server.\n{% connect-mcp /%}\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**
\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n" }, "servers": [ { - "url": "https://api.wise.com/2026Q3", + "url": "https://api.wise.com/2026Q4", "description": "Production Environment" }, { - "url": "https://api.wise-sandbox.com/2026Q3", + "url": "https://api.wise-sandbox.com/2026Q4", "description": "Sandbox Environment" } ], @@ -29,7 +29,7 @@ { "name": "verification", "x-displayName": "Additional Verification", - "description": "{% admonition type=\"warning\" %}\n This endpoint is being deprecated. Use [KYC review endpoints](/guides/product/kyc/wise-kyc/api-hybrid-kyc) to verify your customers.\n {% /admonition %}\n\nIn certain situations, additional evidence is required to verify customers and ensure we’re compliant with the KYC regulations.\n\nAdditional Verification APIs support a list of evidences that can be found in the [Supported Evidences guide](/guides/product/kyc/partner-kyc/supported-evidences).\n\nIf you use the [Customer Account with Partner KYC](/guides/product/kyc/partner-kyc) model and your customers are primarily based in the EU,\nrefer to this [Onboarding EU customers](/guides/product/kyc/partner-kyc/additional-verification#onboarding-eu-customers) guide\nfor instructions on how to use these APIs.\n\n" + "description": "{% admonition type=\"warning\" %}\n This endpoint is being deprecated. Use [KYC review endpoints](/guides/product/account-setup/customer-onboarding/api-hybrid-kyc) to verify your customers.\n {% /admonition %}\n\nIn certain situations, additional evidence is required to verify customers and ensure we’re compliant with the KYC regulations.\n\nAdditional Verification APIs support a list of evidences that can be found in the [Supported Evidences guide](/guides/product/account-setup/customer-onboarding/supported-evidences).\n\nIf you perform your own KYC and your customers are primarily based in the EU,\nrefer to this [Onboarding EU-based customers guide](/guides/product/account-setup/customer-onboarding/region/eu-onboarding) for instructions on how to use these endpoints.\n\n" }, { "name": "address", @@ -79,7 +79,7 @@ { "name": "card-order", "x-displayName": "Card Orders", - "description": "With this set of APIs, you will be able to create cards for your customers. You can also retrieve and view the status of your current card orders, as well as the list of available card programs for the user.\n\n{% admonition type=\"info\" %}\nOn production, each personal profile can order at most 1 physical card and 3 virtual cards. On sandbox, we allow up to 10 physical cards and 30 virtual cards for testing purpose. However, no more than 3 virtual cards can be ordered per day. This limit includes cards and card orders.\n{% /admonition %}\n\nCard order status flow {% #card-order-status-flow .title-3 .m-t-5 %}\n\nThe card order response will contain the `status` field. The initial status is `PLACED` or `REQUIREMENTS_FULFILLED` depending on the requirement fulfillment state:\n\n- `PLACED` - The card order is created. The card will be generated once it has fulfilled all the requirements\n- `REQUIREMENTS_FULFILLED` - The card order has fulfilled all the requirements and the card should be generated in a short while\n- `CARD_DETAILS_CREATED` - The card has been generated\n- `PRODUCED` - The physical card has been produced and waiting to be picked up by delivery vendor (physical card only)\n- `COMPLETED` - The card has been activated and is ready to use. The card order is completed\n- `CANCELLED` - The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order\n- `RETURNED` - Delivery failed, the physical card has been returned and will be blocked (physical card only)\n\n![Card order status state machine](/images/diagrams/card-order-status-flow.png)\n" + "description": "With this set of APIs, you will be able to create cards for your customers. You can also retrieve and view the status of your current card orders, as well as the list of available card programs for the user.\n\n{% admonition type=\"info\" %}\nOn production, each personal profile can order at most 1 physical card and 3 virtual cards, with no more than 3 virtual cards ordered per day. On sandbox, we allow up to 10 physical cards and 30 virtual cards for testing purpose, with no more than 30 virtual cards ordered per day. These limits include cards and card orders.\n{% /admonition %}\n\nCard order status flow {% #card-order-status-flow .title-3 .m-t-5 %}\n\nThe card order response will contain the `status` field. The initial status is `PLACED` or `REQUIREMENTS_FULFILLED` depending on the requirement fulfillment state:\n\n- `PLACED` - The card order is created. The card will be generated once it has fulfilled all the requirements\n- `REQUIREMENTS_FULFILLED` - The card order has fulfilled all the requirements and the card should be generated in a short while\n- `CARD_DETAILS_CREATED` - The card has been generated\n- `PRODUCED` - The physical card has been produced and waiting to be picked up by delivery vendor (physical card only)\n- `COMPLETED` - The card has been activated and is ready to use. The card order is completed\n- `CANCELLED` - The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order\n- `RETURNED` - Delivery failed, the physical card has been returned and will be blocked (physical card only)\n\n![Card order status state machine](/images/diagrams/card-order-status-flow.png)\n" }, { "name": "card-transaction", @@ -94,7 +94,7 @@ { "name": "comparison", "x-displayName": "Comparison", - "description": "The comparison API can be used to request price and speed information about various money transfer providers. This includes not only Wise but other providers in the market.\n\nPrice Estimation {% #comparison-price-estimation .title-3 .m-t-5 %}\n\nThe quotes (price and speed) provided by this API are based off of real quotes collected from 3rd party websites. We collect both the advertised exchange rate and fee for each provider for various amounts. When a comparison is requested, we calculate the markup percentage of the collected exchange rate on the mid-market rate at the time of collection. We then apply this markup to the current mid-market rate to provide a realistic estimate of what each provider offers. We collect data for all providers around once per hour to ensure we provide as accurate and up-to-date information as possible.\n\nNote: Today, we only provide estimations for FX transactions with a Bank Transfer pay-in and pay-out option. This is important to stress as many providers offer significantly different fees and exchange rates when used debit/credit card, cash etc.\n\nFor more details on the data collection process please see the following page:\n[https://wise.com/gb/compare/disclaimer](https://wise.com/gb/compare/disclaimer)\n\nIf you have questions or suspect any data to be inaccurate or incomplete please contact us at: [comparison@wise.com](mailto:comparison@wise.com)\n\nDelivery Estimation {% #comparison-delivery-estimation .title-3 .m-t-5 %}\n\nSimilar to price, we collect speed data for most (if not all) providers which we have price information for. Many providers display speed estimates to their customers in a number of different ways.\n\nSome examples:\n\n- \"The transfer should be complete within 2-5 days\"\n- \"The money should arrive in your account within 48 hours\"\n- \"Should arrive by 26th Aug\"\n- \"Could take up to 4 working days\"\n\nThe below API intends to model these in a consistent format by providing a minimum and maximum range for all delivery estimations. An estimate that states \"up to X\" will have \"max\" set to a duration but \"min\" as null; \"from X\" will have \"min\" set to a duration and \"max\" as null. Finally, for those providers who offer a specific, point in time estimation (like Wise), the API will surface a duration where \"min\" and \"max\" are equal.\n\nQuotes structure {% #comparison-quotes-structure .title-3 .m-t-5 %}\n\nIn order to provide the most flexible and accurate data for clients, we surface a denormalized list of quotes per provider where each quote represents a unique collection of comparison \"dimensions\".\n\nA single given provider may expose multiple quotes for the same currency route. The most common example is where a provider offers different pricing for two different countries which use the same currency, e.g.:\n\nProvider X:\n\n- GBP EUR 1000 [GB -> ES] fee: 10, rate: 1.5\n- GBP EUR 1000 [GB -> DE] fee: 8, rate: 1.5\n- GBP EUR 1000 [GB -> FR] fee: 10, rate: 1.35\n\nThe same principle applies for speed, i.e. a provider may have different speed estimates for different target countries. Hence, we expose these as discrete quotes, where a quote is a unique combination of route, country, speed and price factors.\n\nA client may choose to reduce this set of quotes down to a single or several quotes in order to display a relevant quote to a given user. An example where we take the cheapest quote for a given currency route (and also surface the target country) can be seen at the below link:\n\n[https://wise.com/gb/compare/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=1000](https://wise.com/gb/compare/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=1000)\n" + "description": "The comparison API can be used to request price and speed information about various money transfer providers. This includes not only Wise but other providers in the market.\n\n{% admonition type=\"warning\" name=\"Important\" %}\nAll requests to the Comparison API require authentication. Comparison data is provided for informational purposes and must not be used for critical flows.\n{% /admonition %}\n\nPrice Estimation {% #comparison-price-estimation .title-3 .m-t-5 %}\n\nThe quotes (price and speed) provided by this API are based off of real quotes collected from 3rd party websites. We collect both the advertised exchange rate and fee for each provider for various amounts. When a comparison is requested, we calculate the markup percentage of the collected exchange rate on the mid-market rate at the time of collection. We then apply this markup to the current mid-market rate to provide a realistic estimate of what each provider offers. We collect data for all providers around once per hour to ensure we provide as accurate and up-to-date information as possible.\n\nNote: Today, we only provide estimations for FX transactions with a Bank Transfer pay-in and pay-out option. This is important to stress as many providers offer significantly different fees and exchange rates when used debit/credit card, cash etc.\n\nFor more details on the data collection process please see the following page:\n[https://wise.com/gb/compare/disclaimer](https://wise.com/gb/compare/disclaimer)\n\nIf you have questions or suspect any data to be inaccurate or incomplete please contact us at: [comparison@wise.com](mailto:comparison@wise.com)\n\nDelivery Estimation {% #comparison-delivery-estimation .title-3 .m-t-5 %}\n\nSimilar to price, we collect speed data for most (if not all) providers which we have price information for. Many providers display speed estimates to their customers in a number of different ways.\n\nSome examples:\n\n- \"The transfer should be complete within 2-5 days\"\n- \"The money should arrive in your account within 48 hours\"\n- \"Should arrive by 26th Aug\"\n- \"Could take up to 4 working days\"\n\nThe below API intends to model these in a consistent format by providing a minimum and maximum range for all delivery estimations. An estimate that states \"up to X\" will have \"max\" set to a duration but \"min\" as null; \"from X\" will have \"min\" set to a duration and \"max\" as null. Finally, for those providers who offer a specific, point in time estimation (like Wise), the API will surface a duration where \"min\" and \"max\" are equal.\n\nQuotes structure {% #comparison-quotes-structure .title-3 .m-t-5 %}\n\nIn order to provide the most flexible and accurate data for clients, we surface a denormalized list of quotes per provider where each quote represents a unique collection of comparison \"dimensions\".\n\nA single given provider may expose multiple quotes for the same currency route. The most common example is where a provider offers different pricing for two different countries which use the same currency, e.g.:\n\nProvider X:\n\n- GBP EUR 1000 [GB -> ES] fee: 10, rate: 1.5\n- GBP EUR 1000 [GB -> DE] fee: 8, rate: 1.5\n- GBP EUR 1000 [GB -> FR] fee: 10, rate: 1.35\n\nThe same principle applies for speed, i.e. a provider may have different speed estimates for different target countries. Hence, we expose these as discrete quotes, where a quote is a unique combination of route, country, speed and price factors.\n\nA client may choose to reduce this set of quotes down to a single or several quotes in order to display a relevant quote to a given user. An example where we take the cheapest quote for a given currency route (and also surface the target country) can be seen at the below link:\n\n[https://wise.com/gb/compare/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=1000](https://wise.com/gb/compare/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=1000)\n" }, { "name": "contact", @@ -124,7 +124,7 @@ { "name": "disputes", "x-displayName": "Disputes", - "description": "Raise and manage card transaction disputes, including submission via Dynamic Flow or direct API, file uploads, and dispute lifecycle tracking.\n\nFor implementation details, see:\n- [Disputes via Dynamic Flow](/guides/product/issue-cards/card-disputes-dynamic-flow) — build a dispute UI using the Dynamic Flow framework\n- [Disputes via API](/guides/product/issue-cards/card-disputes-api) — submit disputes directly, with per-reason request body details\n- [Dispute management](/guides/product/issue-cards/card-disputes-management) — track and withdraw disputes\n\nDispute sub-statuses {% #dispute-sub-status .title-3 .m-t-5 %}\n\nThe possible `subStatus` values are:\n- `SUBMITTED` — Initial status\n- `IN_REVIEW` — The dispute is under review or requires additional information\n- `REFUNDED` — The refund has been processed\n- `REJECTED` — The dispute is invalid\n- `WITHDRAWN` — The customer has withdrawn the dispute\n- `CONFIRMED` — The dispute has been reviewed but a refund is not applicable\n- `REFUND_IN_PROGRESS` — A refund is being processed\n- `ATTEMPTING_RECOVERY` — A chargeback request has been submitted\n- `RECOVERY_UNSUCCESSFUL` — The chargeback attempt was unsuccessful\n\n{% admonition type=\"warning\" %}\nThe status transition diagram may undergo modifications in the future and only covers regular pathways.\n{% /admonition %}\n\n{% img\n src=\"/images/diagrams/dispute-status-flow.png\"\n alt=\"Dispute statuses transition diagram\"\n/%}\n" + "description": "Raise and manage card transaction disputes, including submission through an embedded flow or direct API, file uploads, and dispute lifecycle tracking.\n\nFor implementation details, see:\n- [Raise dispute with embedded flow](/guides/product/issue-cards/card-disputes-embedded-flow) — collect dispute details and supporting documents on a Wise-hosted page\n- [Raise dispute via API](/guides/product/issue-cards/card-disputes-api) — submit disputes directly, with per-reason request body details\n- [Manage disputes](/guides/product/issue-cards/card-disputes-management) — track and withdraw disputes\n\nDispute sub-statuses {% #dispute-sub-status .title-3 .m-t-5 %}\n\nThe possible `subStatus` values are:\n- `SUBMITTED` — Initial status\n- `IN_REVIEW` — The dispute is under review or requires additional information\n- `REFUNDED` — The refund has been processed\n- `REJECTED` — The dispute is invalid\n- `WITHDRAWN` — The customer has withdrawn the dispute\n- `CONFIRMED` — The dispute has been reviewed but a refund is not applicable\n- `REFUND_IN_PROGRESS` — A refund is being processed\n- `ATTEMPTING_RECOVERY` — A chargeback request has been submitted\n- `RECOVERY_UNSUCCESSFUL` — The chargeback attempt was unsuccessful\n\n{% admonition type=\"warning\" %}\nThe status transition diagram may undergo modifications in the future and only covers regular pathways.\n{% /admonition %}\n\n{% img\n src=\"/images/diagrams/dispute-status-flow.png\"\n alt=\"Dispute statuses transition diagram\"\n/%}\n" }, { "name": "facetec", @@ -151,11 +151,21 @@ "x-displayName": "OAuth Token", "description": "Exchange client credentials or authorisation grants for OAuth 2.0 access tokens. All grant types use `POST /oauth/token` with basic authentication (your `client_id` and `client_secret`).\n\nDepending on the grant type, this endpoint issues either a **client credentials token** or a **user token**.\n\nClient credentials token {% .title-3 .m-t-5 %}\n\nAn application-level token for requests that aren't tied to a specific Wise user, such as generating un-authenticated quotes and subscribing to application webhooks. Valid for 12 hours.\n\n- `client_credentials` — the only grant type for this token.\n\nUser token {% .title-3 .m-t-5 %}\n\nA token for making API calls on behalf of a specific Wise user, such as creating transfers and managing balances. Access tokens are valid for 12 hours and can be refreshed using a refresh token. Grant types:\n\n- `registration_code` — for partners that create Wise users via API. Exchanges a registration code for a user access token and refresh token.\n- `authorization_code` — for partners using the OAuth redirect flow. Exchanges an authorisation code for a user access token and refresh token.\n- `refresh_token` — obtain a new user access token without requiring the user to re-authorise.\n\nManaging token expiration {% #managing-token-expiration .title-3 .m-t-5 %}\n\nAccess tokens are valid for 12 hours. You can request a new access token whenever it's close to expiring — there is no need to wait for the actual expiration to happen first. Depending on how your application uses the Wise Platform API, requesting a new access token before attempting a series of API calls on behalf of an individual user will avoid issues with expired access tokens.\n" }, + { + "name": "saml", + "x-displayName": "SAML", + "description": "Sign in to Wise using single sign-on (SSO) with your SAML 2.0 identity provider. Wise acts as the SAML service provider.\n\nThese endpoints follow the [SAML 2.0 Web Browser SSO Profile](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). They are part of a browser-based sign-in flow and are not general-purpose REST API endpoints, so they do not use API tokens.\n\nSAML SSO requires configuration on the Wise side. To enable it for your integration, contact your Wise implementation team.\n\nTo set up SSO, configure Wise as a service provider in your identity provider using the [service provider metadata](/api-reference/saml/samlmetadataget). To start sign-in from Wise, open SP-initiated login in your browser. After you authenticate, your identity provider sends the SAML response to the [Assertion Consumer Service](/api-reference/saml/samlassertionconsumerservice) endpoint.\n" + }, { "name": "case", "x-displayName": "Cases", "description": "Cases enable you to open, retrieve, and respond to support and operations queries through direct API.\n\nThe Cases API allows you to integrate your back-end tooling, enabling:\n- Faster responses through automated workflows\n- Structured data via typed messages and submissions\n- Operational efficiencies with programmatic case management\n\n**Case statuses**\n- cases can move through different statuses.\n \n| Status | Description | Partner Action |\n|--------|-------------|----------------|\n| `CREATING` | Case being created | Wait |\n| `IN_REVIEW` | Case being actioned | No action needed |\n| `WAITING_CUSTOMER_INPUT` | Information required | Respond |\n| `RESOLVED` | Case solved and closed | None |\n| `FAILED` | Case creation failed | Contact support |\n\n{% img src=\"/images/diagrams/case-status-flow-v2.svg\" /%}\n\n**Message types**\n- Messages are typed and structured:\n\nRequest messages:\n- `DEPOSIT_SANCTION_HIT_REQUEST`\n- `RECIPIENT_SANCTION_HIT_REQUEST`\n- `REFERENCE_SANCTION_HIT_REQUEST`\n- `RECIPIENT_LOCATION_HIT_REQUEST`\n- `REFERENCE_LOCATION_HIT_REQUEST`\n- `FREEFORM` - Free text communication\n\nSubmission messages (from partner):\n- `*_SUBMISSION` - Structured response to requests\n- `FREEFORM` - Free text communication" }, + { + "name": "case-files", + "x-displayName": "Files", + "description": "Securely upload supporting documentation to Wise and list your uploaded files with their metadata. Each upload returns a file ID, which you can pass to any endpoint that documents support for it. Files currently work with the Cases API only." + }, { "name": "payins", "x-displayName": "Payins", @@ -174,7 +184,7 @@ { "name": "quote", "x-displayName": "Quotes", - "description": "The quote resource defines the currencies involved in a transfer, the amount to send, and the profile sending the money.\n\nThe quote resource is one of the resources required when creating a transfer, along with the recipient account that is receiving the funds.\n\n### Types of quotes\n\nWith the Wise API you can create either **unauthenticated** or **authenticated** quotes.\n\n**Unauthenticated quotes** are for illustrative purposes only. Use this option to display example rates before a user has created or linked an account. This endpoint does not required an auth token and the response has no ID, so it cannot be used to create a transfer.\n\n**Authenticated quotes** require an auth token and provide a quote ID in the response, which you then use when creating a transfer. \n\nUpon creating an authenticated quote, the current mid-market exchange rate is locked and will be used for the transfer created from the quote. The rate is locked for 30 minutes to give a user time to submit the transfer.\n\nThe quote response contains details like the exchange rate, the estimated delivery time, applicable fees, methods for the user to pay for the transfer, and quote expiration time. _Not all fields are applicable to all use cases_.\n" + "description": "The quote resource defines the currencies involved in a transfer, the amount to send, and the profile sending the money.\n\nThe quote resource is one of the resources required when creating a transfer, along with the recipient account that is receiving the funds.\n\n### Types of quotes\n\nWith the Wise API you can create either **unauthenticated** or **authenticated** quotes.\n\n**Unauthenticated quotes** are for illustrative purposes only. Use this option to display example rates before a user has created or linked an account. This endpoint does not require an auth token and the response has no ID, so it cannot be used to create a transfer.\n\n**Authenticated quotes** require an auth token and provide a quote ID in the response, which you then use when creating a transfer. \n\nUpon creating an authenticated quote, the current mid-market exchange rate is locked and will be used for the transfer created from the quote. The rate is locked for 30 minutes to give a user time to submit the transfer.\n\nThe quote response contains details like the exchange rate, the estimated delivery time, applicable fees, methods for the user to pay for the transfer, and quote expiration time. _Not all fields are applicable to all use cases_.\n" }, { "name": "rate", @@ -231,6 +241,11 @@ "x-displayName": "OTP", "description": "For phone-based OTP (one-time password) authentication — where an OTP is a single-use 6-digit code sent to verify the identity of a user — Wise supports multiple delivery methods, including SMS, WhatsApp, and voice. Use Wise's secure endpoint to [create](/api-reference/sca-otp/usersecurityphonenumbercreate) and register the end user's phone number. Then, call the trigger endpoints ([SMS](/api-reference/sca-otp/ottsmstrigger), [WhatsApp](/api-reference/sca-otp/ottwhatsapptrigger), [Voice](/api-reference/sca-otp/ottvoicetrigger)) to send an OTP to the registered number. Finally, submit the OTP via the verify endpoints ([SMS](/api-reference/sca-otp/ottsmsverify), [WhatsApp](/api-reference/sca-otp/ottwhatsappverify), [Voice](/api-reference/sca-otp/ottvoiceverify)) to complete the authentication challenge.\n\nPlease read the [SCA over API guide](/guides/developer/auth-and-security/sca-over-api) to understand how SCA integration works.\n" }, + { + "name": "settlement", + "x-displayName": "Settlement", + "description": "Settlement APIs enable the allocation of settled funds across multiple recipients. A settlement allocation request specifies how a received amount should be distributed. Wise processes each allocation as an individual payment intent that can be tracked through completion.\n\n\n" + }, { "name": "transfer", "x-displayName": "Transfers", @@ -256,6 +271,11 @@ "x-displayName": "GPI Tracking", "description": "Look up SWIFT gpi tracking data by UETR or Wise transfer ID. Each match returns the payment's current status and status reason, the timeline of gpi events reported by the banks in the chain, the agent BICs that handled each leg, the amounts and exchange rate applied at each step, and any charges those banks deducted.\n" }, + { + "name": "payment-instruments", + "x-displayName": "Payment Instruments", + "description": "This set of APIs allows you to create and utilize payment instruments for direct debits." + }, { "name": "user", "x-displayName": "Users", @@ -281,7 +301,8 @@ { "name": "Authentication", "tags": [ - "oauth-token" + "oauth-token", + "saml" ] }, { @@ -387,7 +408,8 @@ "payin-deposit-detail", "direct-debit-account", "bulk-settlement", - "payins" + "payins", + "payment-instruments" ] }, { @@ -397,6 +419,12 @@ "webhook-event" ] }, + { + "name": "Settlement", + "tags": [ + "settlement" + ] + }, { "name": "Simulations", "tags": [ @@ -406,7 +434,8 @@ { "name": "Cases", "tags": [ - "case" + "case", + "case-files" ] }, { @@ -3699,33 +3728,23 @@ } } }, - "/profiles/{profileId}/account-details": { + "/balances/account-details/{id}": { "get": { - "tags": [ - "bank-account-details" - ], - "summary": "Retrieve bank account details", - "operationId": "bankAccountDetailsGet", - "security": [ - { - "UserToken": [] - }, - { - "PersonalToken": [] - } - ], - "description": "Returns a list with all the `AVAILABLE` and `ACTIVE` account details for the given profile, including examples. Account receive options can also include local and international details to receive money on the currency balance.\n\nExample bank account details are returned for any currency where bank account details have not been requested and issued. Examples will always include an `id` of `null`.\n", + "description": "Retrieves account details by ID. Account details identify an account that can receive funds\n(e.g. an IBAN, or a sort code and account number). GB, US and BE account details are supported.\nRequesting account details for an unsupported country returns `404 Not Found`. For coverage across\nall countries, use the [2026Q3 account details API](https://docs.wise.com/api-reference/bank-account-details/bankaccountdetailsget).\n", + "summary": "Get account details by ID", + "operationId": "getAccountDetails", "parameters": [ { - "name": "profileId", + "name": "id", "in": "path", - "required": true, + "description": "Unique identifier for the account details.", "schema": { "type": "integer", + "description": "Unique identifier for the account details.", "format": "int64", "example": 12345678 }, - "description": "The ID of the profile to retrieve bank account details for." + "required": true }, { "$ref": "#/components/parameters/X-External-Correlation-Id" @@ -3733,13 +3752,91 @@ ], "responses": { "200": { - "description": "A list of bank account details.", + "description": "GetAccountDetails 200 response", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/BankAccountDetails" + "$ref": "#/components/schemas/AccountDetails" + }, + "examples": { + "be-account-details": { + "summary": "BE account details", + "value": { + "id": 32345678, + "profileId": 87654321, + "state": "ACTIVE", + "accountHolderName": "Sarah Jenkins", + "country": "BE", + "accountIdentification": { + "beAccountIdentification": { + "bic": "TRWIBEB1", + "iban": "BE71096123456769", + "institutionName": "Wise", + "institutionAddress": { + "streetName": "Avenue Louise", + "buildingNumber": "54", + "townName": "Brussels", + "postCode": "1050", + "country": "BE", + "addressLines": [] + } + } + } + } + }, + "gb-account-details": { + "summary": "GB account details", + "value": { + "id": 12345678, + "profileId": 87654321, + "state": "ACTIVE", + "accountHolderName": "Sarah Jenkins", + "country": "GB", + "accountIdentification": { + "gbAccountIdentification": { + "bic": "TRWIGB2L", + "iban": "GB29NWBK60161331926819", + "sortCode": "230801", + "accountNumber": "12345678", + "institutionName": "Wise Payments Ltd", + "institutionAddress": { + "streetName": "Worship Street", + "buildingNumber": "56", + "townName": "London", + "postCode": "EC2A 2BE", + "country": "GB", + "addressLines": [] + } + } + } + } + }, + "us-account-details": { + "summary": "US account details", + "value": { + "id": 22345678, + "profileId": 87654321, + "state": "ACTIVE", + "accountHolderName": "Sarah Jenkins", + "country": "US", + "accountIdentification": { + "usAccountIdentification": { + "bic": "TRWIUS35XXX", + "routingNumber": "101019628", + "accountNumber": "9900000000", + "institutionName": "Wise", + "institutionAddress": { + "streetName": "West 26th Street", + "buildingNumber": "30", + "townName": "New York", + "postCode": "10010", + "countrySubDivision": "NY", + "country": "US", + "addressLines": [] + } + } + } + } } } } @@ -3753,10 +3850,32 @@ } } }, + "404": { + "description": "AccountDetailsNotFoundError 404 response", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, "429": { "$ref": "#/components/responses/429" } - } + }, + "security": [ + { + "ClientCredentialsToken": [] + }, + { + "UserToken": [] + } + ], + "tags": [ + "bank-account-details" + ] } }, "/profiles/{profileId}/account-details-orders": { @@ -4587,7 +4706,7 @@ "tags": [ "batch-group" ], - "summary": "Fund a batch group", + "summary": "Fund a batch group via balance", "operationId": "batchGroupFund", "security": [ { @@ -4761,14 +4880,14 @@ "tags": [ "batch-group" ], - "summary": "Fund a batch group via direct debit", + "summary": "Fund a batch group", "operationId": "batchGroupPaymentInitiationCreate", "security": [ { "UserToken": [] } ], - "description": "Funds all transfers in a batch group via direct debit. The batch group must be in the `COMPLETED` state.\n\nTo use this funding method, you must link an external bank account first. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate) for more information.\n\n{% admonition type=\"warning\" name=\"SCA protected endpoint\" %}\nThis endpoint is SCA protected. SCA requirements apply to profiles registered outside of the following regions: US, AU, NZ, SG, CA, MY. \n\nReview the [Strong Customer Authentication guide](/guides/developer/auth-and-security/sca-and-2fa) for more details.\n{% /admonition %}\n", + "description": "Funds all transfers in a batch group. The batch group must be in the `COMPLETED` state.\n\nThe `type` field determines the funding method and which fields are required:\n- `DIRECT_DEBIT` — Funds the batch group via direct debit. You must link an external bank account first. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate) for more information.\n- `PAYIN_SESSION` — Funds the batch group using the payin session associated with the batch group.\n\n{% admonition type=\"warning\" name=\"SCA protected endpoint\" %}\nThis endpoint is SCA protected. SCA requirements apply to profiles registered outside of the following regions: US, AU, NZ, SG, CA, MY. \n\nReview the [Strong Customer Authentication guide](/guides/developer/auth-and-security/sca-and-2fa) for more details.\n{% /admonition %}\n", "parameters": [ { "name": "profileId", @@ -4801,32 +4920,21 @@ "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "type", - "accountId" - ], - "properties": { - "type": { - "type": "string", - "description": "The method of payment to use.", - "enum": [ - "DIRECT_DEBIT" - ], - "example": "DIRECT_DEBIT" - }, - "accountId": { - "type": "integer", - "format": "int64", - "description": "Direct debit account ID. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate).", - "example": 1 + "discriminator": { + "propertyName": "type", + "mapping": { + "DIRECT_DEBIT": "#/components/schemas/PaymentInitiationDirectDebitRequest", + "PAYIN_SESSION": "#/components/schemas/PaymentInitiationPayinSessionRequest" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/PaymentInitiationDirectDebitRequest" }, - "reference": { - "type": "string", - "description": "Optional payment initiation reference. Maximum 10 characters. If not provided, a reference will be generated automatically.", - "example": "B1234567" + { + "$ref": "#/components/schemas/PaymentInitiationPayinSessionRequest" } - } + ] } } } @@ -5503,6 +5611,112 @@ } }, "/spend/profiles/{profileId}/cards/{cardToken}/spending-permissions": { + "get": { + "operationId": "cardPermissionsGet", + "summary": "Get card spending permissions", + "description": "Retrieves the current spending permissions configured for a card.\n", + "tags": [ + "card" + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "The ID of the profile that owns the card.", + "schema": { + "type": "integer", + "format": "int64" + }, + "example": 123456 + }, + { + "name": "cardToken", + "in": "path", + "required": true, + "description": "The unique token identifying the card.", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "ca0c8154-1e14-4464-a1ce-dcea7dc3de52" + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "security": [ + { + "UserToken": [] + } + ], + "responses": { + "200": { + "description": "Card permissions retrieved successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "permissions": { + "type": "array", + "description": "List of spending permissions for this card.", + "items": { + "$ref": "#/components/schemas/Permission" + } + } + } + }, + "example": { + "permissions": [ + { + "type": "ECOM", + "isEnabled": false, + "isLocked": false + }, + { + "type": "POS_CHIP", + "isEnabled": true, + "isLocked": false + }, + { + "type": "ATM_WITHDRAWAL", + "isEnabled": false, + "isLocked": false + }, + { + "type": "MOBILE_WALLETS", + "isEnabled": true, + "isLocked": false + }, + { + "type": "POS_CONTACTLESS", + "isEnabled": false, + "isLocked": true + }, + { + "type": "POS_MAGSTRIPE", + "isEnabled": false, + "isLocked": true + } + ] + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + }, "patch": { "operationId": "cardPermissionsBulkUpdate", "summary": "Bulk update card permissions", @@ -7387,27 +7601,27 @@ }, "errors": { "type": "array", - "description": "A list of specific validation failures.", + "description": "A list of specific validation failures", "items": { "type": "object", "properties": { "detail": { "type": "string", - "description": "A detailed description of the validation failure.", + "description": "A detailed description of the validation failure", "examples": [ "Invalid date format. Expected ISO-8601 format YYYY-MM-DDTHH:mm:ssZ." ] }, "code": { "type": "string", - "description": "A specific code for the validation failure type.", + "description": "A specific code for the validation failure type", "examples": [ "parameter_invalid_format" ] }, "ref": { "type": "string", - "description": "A reference to the field that failed validation." + "description": "A reference to the field that failed validation" } } } @@ -7577,6 +7791,17 @@ "tags": [ "comparison" ], + "security": [ + { + "UserToken": [] + }, + { + "PersonalToken": [] + }, + { + "ClientCredentialsToken": [] + } + ], "parameters": [ { "name": "sourceCurrency", @@ -8367,155 +8592,6 @@ } } }, - "/spend/profiles/{profileId}/dispute-form/flows/step/{scheme}/{reason}": { - "post": { - "operationId": "disputeDynamicFlowStep", - "summary": "Dispute dynamic flow entry point", - "description": "Retrieves the JSON for initiating the dispute flow. Use this endpoint with Wise's\n[Dynamic Flow framework](https://www.npmjs.com/package/@transferwise/dynamic-flows).\n\nThe JSON response must be passed into the Dynamic Flow framework, which handles the multi-step dispute submission including the generation of subsequent pages and the creation of the dispute.\n\n**Setting up the API**\n\nYou will need to implement a GET API with the following format:\n`GET https://{{yourApiUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}?transactionId={{transactionId}}`\n\nThis API should forward the call to:\n`POST https://{{wiseUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}?transactionId={{transactionId}}`\n\nThis is required as the dynamic flow returned by Wise will automatically be configured to call your GET API. Use `baseUrl` or `fetcher` as part of the dynamic flow setup to redirect the Dynamic Flow JavaScript library to your domain.\n\nFor a full integration guide, including example backend implementation and styling, see [Disputes via Dynamic Flow](/guides/product/issue-cards/card-disputes-dynamic-flow).\n", - "tags": [ - "disputes" - ], - "security": [ - { - "UserToken": [] - } - ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Your profile ID.", - "schema": { - "type": "integer", - "format": "int64" - }, - "example": 14547572 - }, - { - "name": "scheme", - "in": "path", - "required": true, - "description": "The network of the card that was used to make this transaction.", - "schema": { - "type": "string", - "enum": [ - "MASTERCARD", - "VISA" - ] - }, - "example": "VISA" - }, - { - "name": "reason", - "in": "path", - "required": true, - "description": "Dispute reason code supplied by the [dispute reasons endpoint](/api-reference/disputes/disputereasonsget).", - "schema": { - "type": "string" - }, - "example": "TROUBLE_WITH_GOODS_SERVICES" - }, - { - "name": "transactionId", - "in": "query", - "required": true, - "description": "The ID of the transaction being disputed. Can be a comma-separated list of IDs if the reason code has the `supportsMultipleTransactions` flag.", - "schema": { - "type": "string" - }, - "example": "6789" - }, - { - "$ref": "#/components/parameters/X-External-Correlation-Id" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Email used to receive communications regarding the dispute from Wise (e.g. your support team's email).", - "example": "support@partner.com" - } - } - }, - "example": { - "email": "support@partner.com" - } - } - } - }, - "responses": { - "200": { - "description": "Returns information required to populate the form with the correct information. Note how the `action` field contains the URL and method to the next step.", - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Dynamic Flow JSON object. Pass this to the Dynamic Flow framework to render the dispute form." - }, - "example": { - "key": "TROUBLE_WITH_GOODS_SERVICES", - "type": "form", - "title": "There's a problem with the goods or service I ordered", - "actions": [], - "schemas": [], - "layout": [ - { - "type": "decision", - "options": [ - { - "title": "I never got the goods or service I ordered", - "action": { - "url": "/v3/spend/profiles/12345/dispute-form/flows/visa/no-goods-or-services?transactionId=6789", - "method": "GET" - }, - "disabled": false, - "description": "Choose this if the order was cancelled or never arrived" - }, - { - "title": "Something is wrong with the goods or service I ordered", - "action": { - "url": "/v3/spend/profiles/12345/dispute-form/flows/visa/something-wrong-what-was-received?transactionId=6789", - "method": "GET" - }, - "disabled": false - }, - { - "title": "I think there might be an issue with the merchant", - "action": { - "url": "/v3/spend/profiles/12345/dispute-form/flows/visa/scam?transactionId=6789", - "method": "GET" - }, - "disabled": false, - "description": "Choose this if you haven't heard from the merchant, or have found scam reviews" - } - ] - } - ] - } - } - }, - "headers": { - "X-External-Correlation-Id": { - "$ref": "#/components/headers/X-External-Correlation-Id" - }, - "x-trace-id": { - "$ref": "#/components/headers/x-trace-id" - } - } - }, - "429": { - "$ref": "#/components/responses/429" - } - } - } - }, "/spend/profiles/{profileId}/dispute-form/reasons": { "get": { "operationId": "disputeReasonsGet", @@ -9932,8 +10008,111 @@ } }, "/auth/jose/playground/jwsjwe": { + "get": { + "operationId": "josePlaygroundJwsJweGet", + "summary": "Playground JWS+JWE for GET requests", + "description": "Send test signed and encrypted HTTP requests and receive signed and encrypted responses. Both signing and encryption are mandatory for this endpoint. The request must be a JSON Web Signature (JWS) wrapped in JSON Web Encryption (JWE) — any message that does not follow this format will be rejected.\n\nThe flow combines both JWS and JWE:\n1. **Request**: Send request to Wise, setting the correct jose method header and setting a valid Encryption Key ID in the relevant header.\n2. **Response**: Receive encrypted response → Decrypt (JWE) → Verify signature (JWS)\n\n{% admonition type=\"warning\" name=\"\" %}\nCurrently, the Wise API returns a generic 500 Internal Server Error for decryption failures across endpoints using JWE and JWS+JWE. For example, an invalid key can cause a decryption failure.\n\nOur team is currently planning improvements for these types of error messages to make them more specific and clear. Thank you for your patience.\n{% /admonition %}\n", + "tags": [ + "jose" + ], + "parameters": [ + { + "name": "Accept", + "in": "header", + "required": true, + "schema": { + "type": "string", + "enum": [ + "application/jose+json" + ] + }, + "example": "application/jose+json" + }, + { + "name": "x-tw-jose-method", + "in": "header", + "required": true, + "description": "JOSE method identifier.", + "schema": { + "type": "string", + "enum": [ + "jws+jwe" + ] + }, + "example": "jws+jwe" + }, + { + "name": "X-TW-JOSE-Encryption-kid", + "in": "header", + "required": true, + "description": "ID of the public JWE key uploaded to Wise for encrypting the response.", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "2333836d-2e1c-4acd-8b52-234d379260aa" + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "security": [ + { + "ClientCredentialsToken": [] + } + ], + "responses": { + "200": { + "description": "Signed and encrypted response.", + "content": { + "application/jose+json": { + "schema": { + "type": "string", + "description": "JWE-encoded string containing a signed JWS. After decryption (JWE) and signature verification (JWS), the response contains:\n\n- `message` — The original message prefixed with `jose-playground-response-`. Message length is limited to 100 characters.\n- `method` — Original HTTP request method name: `GET`.\n\nExample of decrypted and decoded response:\n```json\n{\n \"message\": \"jose-playground-response-This is an example from docs.wise.com\",\n \"method\": \"GET\"\n}\n```\n" + }, + "example": "eyJraWQiOiJiMzc0ODE1MC0xNGQ0LTRlMDAtYjM5NC03YWUwYzkzYmUyNDUiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.VGhpcyBpcyB0aGUgZW5jcnlwdGVkIENFSw.aXZfdmFsdWU.ZW5jcnlwdGVkX3BheWxvYWQ.YXV0aF90YWc" + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "examples": { + "unexpectedError": { + "summary": "Unexpected server error", + "value": { + "message": "An unexpected error occurred", + "request_id": "c29beb2374156c390c06fb583e99c999" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + } + } + }, "post": { - "operationId": "josePlaygroundJwsJwe", + "operationId": "josePlaygroundJwsJwePost", "summary": "Playground JWS+JWE", "description": "Send test signed and encrypted HTTP requests and receive signed and encrypted responses. Both signing and encryption are mandatory for this endpoint. The request must be a JSON Web Signature (JWS) wrapped in JSON Web Encryption (JWE) — any message that does not follow this format will be rejected.\n\nThe flow combines both JWS and JWE:\n1. **Request**: Sign payload (JWS) → Encrypt signed JWT (JWE) → Send to Wise\n2. **Response**: Receive encrypted response → Decrypt (JWE) → Verify signature (JWS)\n\n{% admonition type=\"warning\" name=\"\" %}\nCurrently, the Wise API returns a generic 500 Internal Server Error for decryption failures across endpoints using JWE and JWS+JWE. For example, an invalid key can cause a decryption failure.\n\nOur team is currently planning improvements for these types of error messages to make them more specific and clear. Thank you for your patience.\n{% /admonition %}\n", "tags": [ @@ -10038,30 +10217,6 @@ } } }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "examples": { - "jwsError": { - "summary": "Unable to verify request signature", - "value": { - "error": "jws_error", - "error_description": "Unable to verify the request signature" - } - } - } - } - }, - "headers": { - "X-External-Correlation-Id": { - "$ref": "#/components/headers/X-External-Correlation-Id" - }, - "x-trace-id": { - "$ref": "#/components/headers/x-trace-id" - } - } - }, "429": { "$ref": "#/components/responses/429" }, @@ -10504,7 +10659,7 @@ "post": { "operationId": "kycReviewRequirementSubmit", "summary": "Submit a KYC Requirement", - "description": "Submit a KYC requirement for a KYC Review.\n\n- A KYC requirement can only be submitted if the KYC Review status is `WAITING_CUSTOMER_INPUT` or `PASSED_WITH_REQUIREMENTS`.\n- A KYC requirement should only be submitted if its `state` is `NOT_PROVIDED` and `apiCollectionSupported` is `true`.\n\nSee the [KYC requirement types](/guides/product/kyc/wise-kyc/kyc-requirement-types) guide for the full list of supported requirement types, submission data structures, and accepted values.\n", + "description": "Submit a KYC requirement for a KYC Review.\n\n- A KYC requirement can only be submitted if the KYC Review status is `WAITING_CUSTOMER_INPUT` or `PASSED_WITH_REQUIREMENTS`.\n- A KYC requirement should only be submitted if its `state` is `NOT_PROVIDED` and `apiCollectionSupported` is `true`.\n\nThe structure of `submissionData` depends on the `requirementKey`. If you already know which requirement type you are implementing, select it in the request body to see its fields and a matching request sample.\n\nTo explore which requirement types exist and what each one collects, see the [KYC requirement types](/guides/product/account-setup/customer-onboarding/kyc-requirement-types) guide for the full list of supported requirement types, submission data structures, and accepted values.\n", "tags": [ "kyc-review" ], @@ -10528,7 +10683,7 @@ "name": "requirementKey", "in": "path", "required": true, - "description": "The KYC requirement type to submit.\n\nSee the [KYC requirement types](/guides/product/kyc/wise-kyc/kyc-requirement-types) guide for details on each type.\n", + "description": "The KYC requirement type to submit.\n\nTo see the fields for a requirement type, select it in the request body dropdown below. To compare all requirement types, see the [KYC requirement types](/guides/product/account-setup/customer-onboarding/kyc-requirement-types) guide.\n", "schema": { "type": "string", "enum": [ @@ -10561,6 +10716,7 @@ "SOURCE_OF_WEALTH", "SOURCE_OF_WEALTH_INFO", "SOURCE_OF_WEALTH_PROOF", + "SSN_DECLARATION", "TAX_RESIDENCY", "USE_CASE_COUNTRIES" ] @@ -10575,39 +10731,19 @@ "content": { "multipart/form-data": { "schema": { - "type": "object", - "required": [ - "submissionData" - ], - "properties": { - "submissionData": { - "type": "string", - "format": "application/json", - "description": "A JSON string containing the following fields:\n\n- `data` — an object whose fields vary by requirement type. Some requirement types do not require a `data` field.\n- `version` — the submission version, currently `\"V1\"`.\n- `kycReviewId` — the ID of the KYC Review this submission belongs to.\n\nFor example, the JSON payload would look like below, but it should be included as a string value in the multipart form field:\n\n```json\n{\n \"data\": {\n \"accountPurpose\": \"SENDING_MONEY_TO_FRIENDS_OR_FAMILY\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n\nSee the [KYC requirement types](/guides/product/kyc/wise-kyc/kyc-requirement-types) guide for the `data` structure and accepted values for each requirement type.\n" - }, - "files": { - "type": "array", - "items": { - "type": "string", - "format": "binary" - }, - "description": "One or more files to upload. Required for certain requirement types.\n\nThere are 3 accepted types for documents, they must be provided with the below content-type/Mime-type and have a matching file extension.\n\nContentType/MimeType & file extension:\n - `image/png` & `.png`\n - `image/jpeg` & (`.jpg` or `jpeg`)\n - `application/pdf` & `.pdf`\n\n\nSee the [KYC requirement types](/guides/product/kyc/wise-kyc/kyc-requirement-types) guide for which types require files.\n" - } - } + "$ref": "#/components/schemas/request-body" }, - "example": { - "submissionData": "{\"data\":{\"accountPurpose\":\"SENDING_MONEY_TO_FRIENDS_OR_FAMILY\"},\"version\":\"V1\",\"kycReviewId\":\"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"}" + "encoding": { + "submissionData": { + "contentType": "application/json" + }, + "files": { + "contentType": "image/png, image/jpeg, application/pdf" + } } } } }, - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -X POST \\\n 'https://api.wise-sandbox.com/v2/profiles/{profileId}/kyc-requirements/{requirementKey}' \\\n -H 'Authorization: Bearer ' \\\n -F 'submissionData={\"data\":{\"accountPurpose\":\"SENDING_MONEY_TO_FRIENDS_OR_FAMILY\"},\"version\":\"V1\",\"kycReviewId\":\"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"};type=application/json' \\\n -F 'files=@\"\"'\n" - } - ], "responses": { "202": { "description": "KYC requirement successfully submitted.", @@ -11321,6 +11457,43 @@ } ] } + }, + "invalid-ssn-number": { + "summary": "Invalid ssnNumber provided", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/v2/profiles/{profileId}/kyc-requirements/SSN_DECLARATION", + "errors": [ + { + "code": "invalid_value", + "ref": "ssnNumber", + "detail": "ssnNumber must be a valid 9-digit Social Security Number" + } + ] + } + }, + "invalid-ssn-unavailable-reason": { + "summary": "Invalid ssnUnavailableReason provided", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/v2/profiles/{profileId}/kyc-requirements/SSN_DECLARATION", + "errors": [ + { + "code": "invalid_value", + "ref": "ssnUnavailableReason", + "detail": "Invalid ssnUnavailableReason submitted: invalid", + "attributes": { + "acceptedValues": [ + "NON_US_CITIZEN" + ] + } + } + ] + } } } } @@ -11362,11 +11535,162 @@ } } }, + "/profiles/{profileId}/embedded-flows/link-requests/spend/disputes": { + "post": { + "operationId": "disputeEmbeddedLinkRequestCreate", + "summary": "Dispute creation", + "description": "Returns a link that allows a user to complete a dispute creation flow via either a redirect or embedded iframe/webview.\n\nTo see what data is returned to the frontend upon flow completion, see our [Embedded Flows - Dispute Creation guide](/guides/product/embedded-flows/flows/dispute-creation).\n", + "tags": [ + "link-requests" + ], + "security": [ + { + "UserToken": [] + }, + { + "ClientCredentialsToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "The profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "redirectUrl", + "transactionId", + "email" + ], + "properties": { + "redirectUrl": { + "type": "string", + "format": "uri", + "description": "URL where the user is redirected when the flow resolves.\nThis also includes query parameters based on flow completion state and disputed transaction IDs.\n\nFor more information, see our [Embedded Flows - Dispute Creation guide](/guides/product/embedded-flows/flows/dispute-creation).\n", + "example": "https://example.com/return" + }, + "transactionId": { + "type": "integer", + "format": "int64", + "description": "The ID of the card transaction to dispute. It must belong to the given profile.", + "example": 625327 + }, + "email": { + "type": "string", + "format": "email", + "description": "The end user's email address, to receive dispute updates.", + "example": "user@example.com" + } + } + }, + "example": { + "redirectUrl": "https://example.com/return", + "transactionId": 625327, + "email": "user@example.com" + } + } + } + }, + "responses": { + "201": { + "description": "Embedded link request created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "url", + "expiresAt" + ], + "properties": { + "url": { + "type": "string", + "format": "uri", + "description": "Short-lived URL to start the embedded dispute flow.", + "example": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the returned flow URL expires.", + "example": "2026-06-15T13:23:20.265Z" + } + } + }, + "example": { + "url": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20", + "expiresAt": "2026-06-15T13:23:20.265Z" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "400": { + "description": "Invalid request, such as an invalid redirect URL or a transaction that doesn't exist.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "401": { + "description": "User is not authorised to access the resource.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "403": { + "description": "The dispute creation flow is not enabled for the profile.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, "/profiles/{profileId}/embedded-flows/link-requests/recipients": { "post": { "operationId": "recipientEmbeddedLinkRequestCreate", "summary": "Recipient creation", - "description": "Returns a link that allows a user to complete a recipient creation flow via either a redirect or embedded iframe/webview.\n\nView [Embedded Flows - Recipient Creation](/guides/product/embedded-flows/flows/recipient-creation) to see what data the frontend is returned upon flow completion.\n", + "description": "Returns a link that allows a user to complete a recipient creation flow via either a redirect or embedded iframe/webview.\n\nTo see what data is returned to the frontend upon flow completion, see our [Embedded Flows - Recipient Creation guide](/guides/product/embedded-flows/flows/recipient-creation).\n", "tags": [ "link-requests" ], @@ -11403,7 +11727,7 @@ "redirectUrl": { "type": "string", "format": "uri", - "description": "URL where the user will be redirected when the flow resolves.\nThis will also include query parameters based on flow completion state and created recipient ID.\n\nView [Embedded Flows - Recipient Creation](/guides/product/embedded-flows/flows/recipient-creation) for more information.\n", + "description": "URL where the user is redirected when the flow resolves.\nThis also includes query parameters based on flow completion state and created recipient ID.\n\nFor more information, see our [Embedded Flows - Recipient Creation guide](/guides/product/embedded-flows/flows/recipient-creation).\n", "example": "https://example.com/return" }, "targetCurrency": { @@ -11504,7 +11828,7 @@ "post": { "operationId": "paymentInstrumentEmbeddedLinkRequestCreate", "summary": "Payment instrument creation", - "description": "Returns a link that allows a user to complete a payment instrument flow via either a redirect or embedded iframe/webview.\n\nView [Embedded Flows - Payment Instruments](/guides/product/embedded-flows/flows/payment-instrument) to see what data the frontend is returned upon flow completion.\n", + "description": "Returns a link that allows a user to complete a payment instrument flow via either a redirect or embedded iframe/webview.\n\nTo see what data is returned to the frontend upon flow completion, see our [Embedded Flows - Payment Instruments guide](/guides/product/embedded-flows/flows/payment-instrument).\n", "tags": [ "link-requests" ], @@ -11542,7 +11866,7 @@ "redirectUrl": { "type": "string", "format": "uri", - "description": "URL where the user will be redirected when the flow resolves.\nThis will also include query parameters based on flow completion state and created payment instrument ID.\n\nView [Embedded Flows - Payment Instruments](/guides/product/embedded-flows/flows/payment-instrument) for more information.\n", + "description": "URL where the user is redirected when the flow resolves.\nThis also includes query parameters based on flow completion state and created payment instrument ID.\n\nFor more information, see our [Embedded Flows - Payment Instruments guide](/guides/product/embedded-flows/flows/payment-instrument).\n", "example": "https://example.com/return" }, "method": { @@ -11649,7 +11973,7 @@ "post": { "operationId": "kycReviewsEmbeddedLinkRequestCreate", "summary": "KYC review completion", - "description": "Returns a link that allows a user to complete a KYC review flow via either a redirect or embedded iframe/webview.\n\nView [Embedded Flows - KYC Review](/guides/product/embedded-flows/flows/kyc-reviews) to see what data the frontend is returned upon flow completion.\n", + "description": "Returns a link that allows a user to complete a KYC review flow via either a redirect or embedded iframe/webview.\n\nTo see what data is returned to the frontend upon flow completion, see our [Embedded Flows - KYC Review guide](/guides/product/embedded-flows/flows/kyc-reviews).\n", "tags": [ "link-requests" ], @@ -11687,7 +12011,7 @@ "redirectUrl": { "type": "string", "format": "uri", - "description": "URL where the user will be redirected when the flow resolves.\nThis will also include query parameters based on flow completion state and completed KYC review ID.\n\nView [Embedded Flows - KYC Review](/guides/product/embedded-flows/flows/kyc-reviews) for more information.\n", + "description": "URL where the user is redirected when the flow resolves.\nThis also includes query parameters based on flow completion state and completed KYC review ID.\n\nFor more information, see our [Embedded Flows - KYC Review guide](/guides/product/embedded-flows/flows/kyc-reviews).\n", "example": "https://example.com/return" }, "kycReviewId": { @@ -12385,6 +12709,161 @@ ] } }, + "/login/saml2/sso": { + "post": { + "operationId": "samlAssertionConsumerService", + "summary": "Assertion Consumer Service (ACS)", + "description": "Receives the SAML authentication response from your identity provider after you authenticate.\n\nThe identity provider sends a `SAMLResponse` to this endpoint using the SAML HTTP POST binding. The response is validated and, if successful, completes your SAML sign-in.\n\nThis endpoint implements the [SAML 2.0 Web Browser SSO Profile](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). For details of the SAML message format and protocol requirements, refer to the OASIS SAML 2.0 specification.\n", + "tags": [ + "saml" + ], + "security": [], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "SAMLResponse": { + "type": "string", + "description": "Base64-encoded SAML `` message issued by the identity provider." + }, + "RelayState": { + "type": "string", + "description": "Opaque state value. If the authentication request included a `RelayState`, the identity provider returns it unchanged." + } + }, + "required": [ + "SAMLResponse" + ] + } + } + } + }, + "responses": { + "302": { + "description": "The SAML response was processed. Your browser is redirected to continue the sign-in flow.", + "headers": { + "Location": { + "description": "URL your browser is redirected to.", + "schema": { + "type": "string" + } + }, + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ] + } + }, + "/saml2/metadata": { + "get": { + "operationId": "samlMetadataGet", + "summary": "Retrieve SP metadata", + "description": "Returns the SAML 2.0 metadata for the service provider.\n\nUse this metadata when configuring the service provider in your identity provider. It includes the information required by the identity provider, such as the service provider entity ID, Assertion Consumer Service endpoint, supported bindings, and signing certificate information where applicable.\n\nThe response is an XML document conforming to the [SAML 2.0 Metadata specification](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf).\n\nWhere supported, we recommend configuring your identity provider using this metadata rather than entering SAML settings manually.\n", + "tags": [ + "saml" + ], + "security": [], + "responses": { + "200": { + "description": "The service provider metadata.", + "content": { + "application/samlmetadata+xml": { + "schema": { + "type": "string", + "description": "SAML 2.0 `` XML document." + }, + "examples": { + "sandboxMetadata": { + "summary": "Sandbox service provider metadata", + "description": "The signing certificate is shortened. Retrieve the metadata from the endpoint to get the current certificate.", + "value": "\n\n \n \n \n \n MIIEQjCCAqqgAwIBAgIUUUF+VCaEJllClaROLMa1bXBj2x0...\n \n \n \n \n \n\n" + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ] + } + }, + "/saml2/authenticate/{registrationId}": { + "get": { + "operationId": "samlAuthenticate", + "summary": "Start SP-initiated login", + "description": "Starts an SP-initiated SAML authentication flow.\n\nWhen you open this endpoint, you are redirected to your configured identity provider with a SAML authentication request. After you authenticate, your identity provider sends the resulting SAML response to the [Assertion Consumer Service](/api-reference/saml/samlassertionconsumerservice) endpoint.\n\nOpen this endpoint in your browser. It is not a general-purpose REST API endpoint.\n\nThe authentication flow follows the [SAML 2.0 Web Browser SSO Profile](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf).\n", + "tags": [ + "saml" + ], + "security": [], + "parameters": [ + { + "name": "registrationId", + "in": "path", + "required": true, + "description": "Identifier of the identity provider configuration to authenticate with.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "302": { + "description": "Your browser is redirected to your identity provider with a SAML authentication request.", + "headers": { + "Location": { + "description": "Identity provider single sign-on URL, including the SAML authentication request.", + "schema": { + "type": "string" + } + }, + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, "/application/users/{userId}/phone-numbers": { "post": { "operationId": "userSecurityPhoneNumberCreate", @@ -13150,13 +13629,6 @@ "ClientCredentialsToken": [] } ], - "x-codeSamples": [ - { - "lang": "bash", - "label": "cURL", - "source": "curl -X GET \\\n 'https://api.sandbox.wise.com/2026Q4/cases/{caseId}' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer '\n" - } - ], "parameters": [ { "name": "caseId", @@ -14420,22 +14892,6 @@ ] } }, - "filesNotUploadedByYou": { - "summary": "Files were not uploaded by you", - "value": { - "type": "/errors/types/validation", - "title": "Validation Error", - "status": 400, - "instance": "/public/v2/cases/12345678/messages", - "errors": [ - { - "code": "invalid_value", - "ref": "fileIds", - "detail": "One or more files were not created by the Partner" - } - ] - } - }, "invalidSanctionHitStructure": { "summary": "Invalid sanction hit submission structure", "value": { @@ -14614,95 +15070,88 @@ } } }, - "/profiles/{profileId}/payin-sessions/{payinSessionId}/paynow": { + "/cases/files": { "post": { - "operationId": "paynowCreate", - "summary": "Create PayNow payment details", - "description": "Creates the encoded QR code and details for the payin session so the user can fund a transfer or balance top-up via a PayNow transaction.\nThis operation supports the SGD currency only.\n", + "operationId": "caseFileUpload", + "summary": "Upload a file", + "description": "Uploads a file that can be used as supporting documentation for cases.\nAll files are scanned for malware before being accepted.\n", "tags": [ - "payins" + "case-files" ], "security": [ { - "UserToken": [] + "ClientCredentialsToken": [] } ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Profile ID of the profile that created the transfer.", - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "payinSessionId", - "in": "path", - "required": true, - "description": "Payin Session ID retrieved from Transfer object.", - "schema": { - "type": "string", - "format": "string" + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "contentMediaType": "application/octet-stream", + "description": "The file to upload. Do not include personally identifying information in the file name. Must be one of the supported content types\n(`application/pdf`, `image/jpeg`, `image/png`) and must not exceed 15 MB.\nFile name must not exceed 128 characters and the file extension must match the content type\n(e.g. `.pdf` for `application/pdf`).\n" + }, + "submissionData": { + "$ref": "#/components/schemas/file-upload-request" + } + }, + "required": [ + "file", + "submissionData" + ] + }, + "encoding": { + "file": { + "contentType": "application/pdf, image/jpeg, image/png" + }, + "submissionData": { + "contentType": "application/json" + } + } } - }, - { - "$ref": "#/components/parameters/X-External-Correlation-Id" } - ], + }, "responses": { - "200": { - "description": "PayNow payment object.", + "201": { + "description": "File uploaded successfully", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "qrCodeInBase64": { - "type": "string", - "description": "An encoded QR image in base64 format, which can be decoded and displayed directly to the end user.", - "example": "iVBORw0KGgoAAAANSUhEUgAAAXUAAAF1CAIAAACYn+2fAAB2CUlEQVR4Xux9B2BU15k1cYxAdJCQhB..." - }, - "details": { - "type": "object", - "description": "Manual input details that can be used by the end user to make the transfer without scanning the QR image.", - "properties": { - "virtualPaymentAddress": { - "type": "string", - "description": "Virtual payment address to pay to.", - "example": "UEN123456789R#WISE" - }, - "amount": { - "type": [ - "number" - ], - "description": "Transfer amount.", - "example": 100 - }, - "currency": { - "type": [ - "string" - ], - "description": "Currency.", - "example": "SGD" - }, - "reference": { - "type": [ - "string" - ], - "description": "Payment reference used for linking the PayNow transaction to the transfer created by the profile.", - "example": "PP12345678" - }, - "entityName": { - "type": [ - "string" - ], - "description": "Entity name of the Wise Account to make the PayNow transfer to.", - "example": "WISE ASIA-PACIFIC PTE LTD" - } - } + "$ref": "#/components/schemas/file-upload-response" + }, + "examples": { + "pdfUpload": { + "summary": "PDF file uploaded", + "value": { + "profileId": 14556049, + "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "fileName": "company-registration.pdf", + "createdAt": "2026-09-28T10:00:00.123", + "purpose": "GENERAL" + } + }, + "pngUpload": { + "summary": "PNG image uploaded", + "value": { + "profileId": 14556049, + "fileId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "fileName": "identity-document.png", + "createdAt": "2026-09-29T10:00:00.123", + "purpose": "GENERAL" + } + }, + "jpegUpload": { + "summary": "JPEG image uploaded", + "value": { + "profileId": 14556049, + "fileId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "fileName": "identity-document.jpg", + "createdAt": "2026-09-30T10:00:00.123", + "purpose": "GENERAL" } } } @@ -14718,67 +15167,219 @@ } }, "400": { - "description": "Invalid request.", + "description": "Bad request - validation failed", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "type": { - "type": "string", - "format": "uri-reference", - "description": "Must be /errors/types/validation for this error type.", - "examples": [ - "/errors/types/validation" + "$ref": "#/components/schemas/error-400-validation" + }, + "examples": { + "missingProfileId": { + "summary": "Missing profileId", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_missing", + "ref": "profileId", + "detail": "profileId must be provided" + } ] - }, - "title": { - "type": "string", - "description": "Validation Error", - "examples": [ - "Validation Error" + } + }, + "missingPurpose": { + "summary": "Missing purpose", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_missing", + "ref": "purpose", + "detail": "purpose must be provided" + } ] - }, - "status": { - "type": "string", - "description": "Bad Format Validation Error", - "examples": [ - 400 + } + }, + "invalidPurpose": { + "summary": "Invalid purpose value", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "purpose", + "detail": "Invalid purpose" + } ] - }, - "instance": { - "type": "string", - "description": "The uri the triggered a validation error", - "examples": [ - "/v1/profiles/12345678/payin-sessions/74a3fe63-f37e-49ff-f744-8ef020efabcde/paynow" + } + }, + "emptyFile": { + "summary": "File is empty", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_missing", + "ref": "file", + "detail": "File must be provided" + } ] - }, - "errors": { - "type": "array", - "description": "A list of specific validation failures.", - "items": { - "type": "object", - "properties": { - "detail": { - "type": "string", - "description": "A detailed description of the validation failure.", - "examples": [ - "Invalid request to create payment for session 1." - ] - }, - "code": { - "type": "string", - "description": "A specific code for the validation failure type.", - "examples": [ - "invalid_request" - ] - }, - "ref": { - "type": "string", - "description": "A reference to the field that failed validation." - } + } + }, + "missingFileName": { + "summary": "File name is missing", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_missing", + "ref": "file", + "detail": "File name must be provided" } - } + ] + } + }, + "fileNameTooLong": { + "summary": "File name exceeds 128 characters", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "file", + "detail": "File name must not exceed 128 characters" + } + ] + } + }, + "fileSizeTooLarge": { + "summary": "File exceeds 15 MB size limit", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "file_size_exceeds_max_limit", + "ref": "file", + "detail": "File size exceeds maximum allowed size" + } + ] + } + }, + "missingContentType": { + "summary": "File content type is missing", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "file", + "detail": "File content type must be provided" + } + ] + } + }, + "unsupportedContentType": { + "summary": "File content type not allowed", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "invalid_file_extension", + "ref": "file", + "detail": "File content type not allowed" + } + ] + } + }, + "noValidExtension": { + "summary": "File name has no valid extension", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "invalid_file_extension", + "ref": "file", + "detail": "File name must have a valid extension" + } + ] + } + }, + "extensionMismatch": { + "summary": "File extension does not match content type", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "invalid_file_extension", + "ref": "file", + "detail": "File extension does not match content type" + } + ] + } + }, + "profileNotConnected": { + "summary": "Profile is not associated with Partner", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "profileId", + "detail": "Profile does not belong to Partner" + } + ] + } + }, + "malwareDetected": { + "summary": "File failed security scan", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "file", + "detail": "File failed security scan" + } + ] } } } @@ -14793,48 +15394,18 @@ } } }, - "422": { - "description": "Unprocessable request.", + "401": { + "description": "Unauthorized - missing or invalid authentication", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "type": { - "type": "string", - "format": "uri-reference", - "description": "Must be /errors/types/domain for this error type.", - "examples": [ - "/errors/types/domain" - ] - }, - "title": { - "type": "string", - "description": "Unprocessable Entity", - "examples": [ - "Unprocessable Entity" - ] - }, - "status": { - "type": "string", - "description": "Unprocessable Entity Domain Error", - "examples": [ - 422 - ] - }, - "instance": { - "type": "string", - "description": "The uri that triggered the error", - "examples": [ - "/v1/profiles/12345678/payin-sessions/74a3fe63-f37e-49ff-f744-8ef020efabcde/paynow" - ] - }, - "code": { - "type": "string", - "description": "Error code of the request", - "example": "payins.paynow.details.creation.not.allowed" - } - } + "$ref": "#/components/schemas/error-401-unauthorized-2" + }, + "example": { + "type": "/errors/types/access", + "title": "Unauthorized", + "status": 401, + "detail": "Authentication required" } } }, @@ -14847,231 +15418,19 @@ } } }, - "429": { - "$ref": "#/components/responses/429" - } - } - } - }, - "/profiles/{profileId}/transfers/{transferId}/deposit-details/bank-transfer": { - "get": { - "operationId": "payinDepositDetailGet", - "summary": "Retrieve bank transfer deposit details", - "description": "Retrieve the bank details for the account that the customer should send funds to when paying for a Wise transfer via a bank transfer.\n\n`profileId` in the request URL refers to the profile that created the transfer. It can be either the personal profile ID, or the business profile ID.\n\nThe `payinBankAccount` field allows the bank details to be displayed dynamically in a user interface, by displaying the label and value fields.\n\nCurrently, this API supports the following currencies: AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, INR, JPY, MYR, NOK, NZD, PLN, RON, SEK, SGD, TRY, USD.\n", - "tags": [ - "payin-deposit-detail" - ], - "security": [ - { - "UserToken": [] - } - ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Profile ID.", - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "name": "transferId", - "in": "path", - "required": true, - "description": "Transfer ID.", - "schema": { - "type": "integer", - "format": "int64" - } - }, - { - "$ref": "#/components/parameters/X-External-Correlation-Id" - } - ], - "responses": { - "200": { - "description": "Payin deposit detail object.", + "403": { + "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "payinBank": { - "type": "object", - "description": "Information about the receiving bank.", - "properties": { - "bankName": { - "type": "string", - "description": "Bank name.", - "example": "Wise Europe SA/NV" - }, - "bankAddress": { - "type": [ - "object", - "null" - ], - "description": "Bank address.", - "properties": { - "country": { - "type": "string", - "description": "Country ISO 2 code.", - "example": "BE" - }, - "firstLine": { - "type": "string", - "description": "Street address.", - "example": "Rue Du Trône 100, box 3" - }, - "postCode": { - "type": "string", - "description": "Post code / zip code.", - "example": "1050" - }, - "city": { - "type": "string", - "description": "City.", - "example": "Brussels" - }, - "state": { - "type": [ - "string", - "null" - ], - "description": "State.", - "example": null - }, - "phone": { - "type": [ - "string", - "null" - ], - "description": "Phone number.", - "example": "+32 472 123 456" - } - } - } - } - }, - "payinBankAccount": { - "type": "object", - "description": "Bank account details to use to send the payment to.", - "properties": { - "currency": { - "type": "string", - "description": "ISO 4217 source currency code.", - "example": "EUR" - }, - "bankAccountType": { - "type": "string", - "description": "The type of bank account to use for the payin, e.g. RECIPIENT, ESCROW, BALANCE, etc.", - "example": "RECIPIENT" - }, - "details": { - "type": "array", - "description": "Account details.", - "items": { - "type": "object", - "description": "Account detail entry.", - "properties": { - "type": { - "type": "string", - "description": "Account details type, e.g. accountNumber, iban etc.", - "example": "iban" - }, - "label": { - "type": "string", - "description": "Account details label that should be displayed in your user interface.", - "example": "IBAN" - }, - "value": { - "type": "string", - "description": "Account details value. This field is deprecated. Use `rawValue` and `formattedValue` instead.", - "example": "BE11111111111111", - "deprecated": true - }, - "rawValue": { - "type": "string", - "description": "Account details value, always unformatted. Can be used for processing.", - "example": "BE11111111111111" - }, - "formattedValue": { - "type": [ - "string", - "null" - ], - "description": "Account details value, formatted according to the type of the field. Intended to be human-readable. This can be null.", - "example": "BE11 1111 1111 1111" - }, - "description": { - "type": "string", - "description": "Description of the account detail type.", - "example": "International Bank Account Number" - } - } - } - } - } - }, - "wiseInformation": { - "type": "object", - "description": "Information about the receiving Wise entity, the owner of the bank account.", - "properties": { - "localCompanyName": { - "type": "string", - "description": "Wise local company name.", - "example": "Wise Europe SA" - }, - "localAddress": { - "type": [ - "object", - "null" - ], - "description": "Wise local address.", - "properties": { - "country": { - "type": "string", - "description": "Country ISO 2 code.", - "example": "BE" - }, - "firstLine": { - "type": "string", - "description": "Street address.", - "example": "Rue du Trône 100, 3rd floor" - }, - "postCode": { - "type": "string", - "description": "Post code / zip code.", - "example": "1050" - }, - "city": { - "type": "string", - "description": "City.", - "example": "Brussels" - }, - "state": { - "type": [ - "string", - "null" - ], - "description": "State.", - "example": null - }, - "phone": { - "type": [ - "string", - "null" - ], - "description": "Phone number.", - "example": null - } - } - } - } - } - } + "$ref": "#/components/schemas/error-403-forbidden-2" + }, + "example": { + "type": "/errors/types/access", + "title": "Forbidden", + "status": 403, + "detail": "Unauthorized", + "code": "forbidden" } } }, @@ -15085,117 +15444,20 @@ } }, "429": { - "$ref": "#/components/responses/429" - } - } - } - }, - "/profiles": { - "get": { - "operationId": "profileList", - "summary": "List profiles for a user account", - "description": "List of all profiles belonging to user.\n", - "tags": [ - "profile" - ], - "security": [ - { - "UserToken": [] - }, - { - "PersonalToken": [] - } - ], - "responses": { - "200": { - "description": "Array of profile objects. Note that there might be more than one business profile returned in the response.", + "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/profile" - } + "$ref": "#/components/schemas/error-429-too-many-requests" }, - "example": [ - { - "type": "PERSONAL", - "id": 14575282, - "publicId": "a1b2c3d4-e5f6-7890-1234-567890abcdef", - "userId": 9889627, - "address": { - "id": 36086782, - "addressFirstLine": "24 Willow Creek Lane", - "city": "Bristol", - "countryIso2Code": "GB", - "countryIso3Code": "gbr", - "postCode": "BS1 6AE", - "stateCode": null - }, - "email": "sarah.jenkins@example.com", - "createdAt": "2023-01-15T10:30:00", - "updatedAt": "2025-06-18T14:20:00", - "avatar": "https://example.com/avatars/sarah_jenkins.png", - "currentState": "VISIBLE", - "contactDetails": { - "email": "sarah.contact@example.com", - "phoneNumber": "+447700900123" - }, - "firstName": "Sarah", - "lastName": "Jenkins", - "preferredName": "Sal", - "dateOfBirth": "1985-05-20", - "phoneNumber": "+447700900456", - "secondaryAddresses": [], - "fullName": "Sarah Jenkins" - }, - { - "type": "BUSINESS", - "id": 14599371, - "publicId": "f0e9d8c7-b6a5-4321-fedc-ba9876543210", - "userId": 9889627, - "address": { - "id": 36152772, - "addressFirstLine": "15 Tech Hub Studios", - "city": "Manchester", - "countryIso2Code": "GB", - "countryIso3Code": "gbr", - "postCode": "M1 7JA", - "stateCode": null - }, - "email": "info@innovate-solutions.co.uk", - "createdAt": "2024-03-10T09:00:00", - "updatedAt": "2025-06-18T14:22:00", - "contactDetails": { - "email": "contact@innovate-solutions.co.uk", - "phoneNumber": "+441617891234" - }, - "businessName": "Innovate Solutions Ltd", - "registrationNumber": "SC1234567890ABCD", - "descriptionOfBusiness": "IT_DEVELOPMENT", - "webpage": "https://www.innovate-solutions.co.uk", - "companyType": "LIMITED_COMPANY", - "businessFreeFormDescription": "We create cutting-edge software for businesses.", - "firstLevelCategory": "CONSULTING_IT_BUSINESS_SERVICES", - "secondLevelCategory": "IT_DEVELOPMENT", - "industryCategories": [ - "SOFTWARE_DEVELOPMENT_PUBLISHING", - "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" - ], - "operationalAddresses": [ - { - "id": 36152773, - "addressFirstLine": "Unit 5, Innovation Park", - "city": "Leeds", - "countryIso2Code": "GB", - "countryIso3Code": "gbr", - "postCode": "LS1 4YZ", - "stateCode": null - } - ], - "fullName": "Innovate Solutions Ltd" - } - ] + "example": { + "type": "/errors/types/domain", + "title": "Too Many Requests", + "status": 429, + "detail": "Too many files uploaded recently. Please try again later.", + "instance": "/cases/files", + "code": "rate_limit_exceeded" + } } }, "headers": { @@ -15207,8 +15469,30 @@ } } }, - "429": { - "$ref": "#/components/responses/429" + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error-response-2" + }, + "example": { + "type": "/errors/types/internal", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred. Please try again later.", + "instance": "/cases/files" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } } }, "parameters": [ @@ -15216,310 +15500,438 @@ "$ref": "#/components/parameters/X-External-Correlation-Id" } ] - } - }, - "/profiles/personal-profile": { - "post": { - "operationId": "profilePersonalCreate", - "summary": "Create a personal profile", - "description": "Create a personal profile for the authenticated user. A personal profile represents an individual and is required before creating transfers or business profiles.\n\n{% admonition type=\"info\" %}\nUse the `X-idempotence-uuid` header to safely retry requests. If omitted and a profile already exists, the API returns `409 Conflict`. You can then retrieve existing profiles via [List profiles](/api-reference/profile/profilelist).\n{% /admonition %}\n\nField notes {% .title-4 .m-t-3 %}\n\n- **First and last names** are limited to 30 characters each. Truncate if necessary (e.g. when a customer has many middle names).\n- **`occupations`** is required for CA, IN, JP, ID, IL, MX, and within the US for the state NM.\n- **`contactDetails`** are used for mandatory customer notifications and to help identify your customer when contacting Wise support.\n", + }, + "get": { + "operationId": "caseFileList", + "summary": "List files", + "description": "Returns a paginated list of metadata for files uploaded.\nUse `profileId` to retrieve files for a specific profile.\nIf omitted, returns files across all profiles.\n", "tags": [ - "profile" + "case-files" ], "security": [ { - "UserToken": [] - }, - { - "PersonalToken": [] + "ClientCredentialsToken": [] } ], "parameters": [ { - "name": "X-idempotence-uuid", - "in": "header", + "name": "pageNumber", + "in": "query", "required": false, - "description": "Unique idempotency key for the request.", + "description": "The page number to retrieve. Must be at least `1`.", "schema": { - "type": "string", - "format": "uuid" - } + "type": "integer", + "format": "int32", + "minimum": 1, + "default": 1 + }, + "example": 1 + }, + { + "name": "pageSize", + "in": "query", + "required": false, + "description": "The maximum number of files to return per page. Between `1` and `100`.", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100 + }, + "example": 2 + }, + { + "name": "profileId", + "in": "query", + "required": false, + "description": "Filter files by profile ID.\nOmit this parameter to retrieve files across all profiles.\n", + "schema": { + "type": "integer", + "format": "int64" + }, + "example": 14556049 }, { "$ref": "#/components/parameters/X-External-Correlation-Id" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "firstName", - "lastName", - "dateOfBirth", - "address", - "contactDetails" - ], - "properties": { - "firstName": { - "type": "string", - "maxLength": 30, - "description": "First name (including middle names).", - "example": "Oliver" - }, - "lastName": { - "type": "string", - "maxLength": 30, - "description": "Last name.", - "example": "Wilson" - }, - "preferredName": { - "type": "string", - "maxLength": 30, - "description": "Preferred first name, if different to the legal first name.", - "example": "Olivia" + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X GET \"https://api.wise.com/2027Q1/cases/files\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\"\n" + }, + { + "lang": "bash", + "label": "cURL - Filter by profile", + "source": "curl -X GET \"https://api.wise.com/2027Q1/cases/files?pageNumber=1&pageSize=2&profileId=14556049\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\"\n" + } + ], + "responses": { + "200": { + "description": "Paginated list of files", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/file-list-response" + }, + "example": { + "files": [ + { + "profileId": 14556049, + "fileId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890", + "fileName": "company-registration.pdf", + "createdAt": "2026-09-30T10:00:00.123", + "purpose": "GENERAL" + }, + { + "profileId": 14556049, + "fileId": "b2c3d4e5-f6a7-4890-bcde-f12345678901", + "fileName": "identity-document.png", + "createdAt": "2026-09-29T10:00:00.123", + "purpose": "GENERAL" + } + ], + "totalFiles": 5 + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "400": { + "description": "Bad request - validation failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/file-list-validation-error" + }, + "examples": { + "pageNumberTooSmall": { + "summary": "Page number is less than 1", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "pageNumber", + "detail": "Page number must be greater than or equal to 1" + } + ] + } }, - "firstNameInKana": { - "type": [ - "string", - "null" - ], - "description": "First name in Katakana. Required for from-JPY personal transfers.", - "example": null + "pageSizeTooSmall": { + "summary": "Page size is less than 1", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "pageSize", + "detail": "Page size must be greater than or equal to 1" + } + ] + } }, - "lastNameInKana": { - "type": [ - "string", - "null" - ], - "description": "Last name in Katakana. Required for from-JPY personal transfers.", - "example": null + "pageSizeTooLarge": { + "summary": "Page size exceeds 100", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "pageSize", + "detail": "Page size must be less than or equal to 100" + } + ] + } }, - "address": { - "type": "object", - "required": [ - "addressFirstLine", - "city", - "countryIso3Code" - ], - "properties": { - "addressFirstLine": { - "type": "string", - "description": "First line of address.", - "example": "50 Sunflower Ave" - }, - "city": { - "type": "string", - "description": "City.", - "example": "Phoenix" - }, - "countryIso3Code": { - "type": "string", - "description": "3 letter country code (lower case).", - "example": "usa" - }, - "postCode": { - "type": "string", - "description": "Postal code.", - "example": "10025" - }, - "stateCode": { - "type": "string", - "maxLength": 5, - "description": "State code. Required for US, CA, BR and AU addresses.", - "example": "AZ" - } - } - }, - "nationality": { - "type": "string", - "description": "3 letter country code (lower case).", - "example": "usa" - }, - "dateOfBirth": { - "type": "string", - "description": "Date of birth.", - "example": "1977-07-01" - }, - "externalCustomerId": { - "type": "string", - "description": "An external reference identifier mapping the customer of this profile to your system.", - "example": "12345-oliver-wilson" - }, - "contactDetails": { - "type": "object", - "required": [ - "email", - "phoneNumber" - ], - "properties": { - "email": { - "type": "string", - "description": "Contact email address. Please speak with your integration account manager for details on how customer communication is handled for your integration.", - "example": "o.wilson@example.com" - }, - "phoneNumber": { - "type": "string", - "description": "Contact phone number in international phone number format, example \"+1408XXXXXXX\".", - "example": "+3725064992" - } - } - }, - "occupations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "code": { - "type": "string", - "description": "Occupation field code - this field accepts any job or occupation that the customer does, as the only occupation format currently accepted is `\"FREE_FORM\"`.", - "example": "Software Engineer" - }, - "format": { - "type": "string", - "description": "Occupation field format. As of now, it only accepts the value `\"FREE_FORM\"`.", - "example": "FREE_FORM" + "profileNotConnected": { + "summary": "Profile is not associated with Partner", + "value": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_invalid", + "ref": "profileId", + "detail": "Profile does not belong to Partner" } - } + ] } } } } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid authentication", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error-401-unauthorized-2" + }, + "example": { + "type": "/errors/types/access", + "title": "Unauthorized", + "status": 401, + "detail": "Authentication required" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "403": { + "description": "Forbidden - insufficient permissions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error-403-forbidden-2" + }, + "example": { + "type": "/errors/types/access", + "title": "Forbidden", + "status": 403, + "detail": "Unauthorized", + "code": "forbidden" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error-response-2" + }, + "example": { + "type": "/errors/types/internal", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred. Please try again later.", + "instance": "/cases/files" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } } } - }, + } + } + }, + "/profiles/{profileId}/payin-sessions/{payinSessionId}/paynow": { + "post": { + "operationId": "paynowCreate", + "summary": "Create PayNow payment details", + "description": "Creates the encoded QR code and details for the payin session so the user can fund a transfer or balance top-up via a PayNow transaction.\nThis operation supports the SGD currency only.\n", + "tags": [ + "payins" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Profile ID of the profile that created the transfer.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "payinSessionId", + "in": "path", + "required": true, + "description": "Payin Session ID retrieved from Transfer object.", + "schema": { + "type": "string", + "format": "string" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], "responses": { "200": { - "description": "Created personal profile.", + "description": "PayNow payment object.", "content": { "application/json": { "schema": { "type": "object", "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "Unique profile ID.", - "example": 30000001 - }, - "type": { + "qrCodeInBase64": { "type": "string", - "description": "Profile type.", - "enum": [ - "PERSONAL" - ], - "example": "PERSONAL" + "description": "An encoded QR image in base64 format, which can be decoded and displayed directly to the end user.", + "example": "iVBORw0KGgoAAAANSUhEUgAAAXUAAAF1CAIAAACYn+2fAAB2CUlEQVR4Xux9B2BU15k1cYxAdJCQhB..." }, "details": { "type": "object", - "description": "Profile details.", + "description": "Manual input details that can be used by the end user to make the transfer without scanning the QR image.", "properties": { - "firstName": { - "type": "string", - "description": "First name (including middle names).", - "example": "Oliver" - }, - "lastName": { - "type": "string", - "description": "Last name.", - "example": "Wilson" - }, - "preferredName": { + "virtualPaymentAddress": { "type": "string", - "description": "Preferred first name.", - "example": "Olivia" + "description": "Virtual payment address to pay to.", + "example": "UEN123456789R#WISE" }, - "firstNameInKana": { + "amount": { "type": [ - "string", - "null" + "number" ], - "description": "First name in Katakana.", - "example": null + "description": "Transfer amount.", + "example": 100 }, - "lastNameInKana": { + "currency": { "type": [ - "string", - "null" + "string" ], - "description": "Last name in Katakana.", - "example": null - }, - "address": { - "type": "object", - "properties": { - "addressFirstLine": { - "type": "string", - "example": "50 Sunflower Ave" - }, - "city": { - "type": "string", - "example": "Phoenix" - }, - "countryIso3Code": { - "type": "string", - "example": "usa" - }, - "postCode": { - "type": "string", - "example": "10025" - }, - "stateCode": { - "type": "string", - "example": "AZ" - } - } - }, - "nationality": { - "type": "string", - "description": "3 letter country code (lower case).", - "example": "usa" - }, - "dateOfBirth": { - "type": "string", - "description": "Date of birth.", - "example": "1977-07-01" - }, - "externalCustomerId": { - "type": "string", - "description": "External reference identifier in your system.", - "example": "12345-oliver-wilson" - }, - "contactDetails": { - "type": "object", - "properties": { - "email": { - "type": "string", - "example": "o.wilson@example.com" - }, - "phoneNumber": { - "type": "string", - "example": "+3725064992" - } - } + "description": "Currency.", + "example": "SGD" }, - "occupations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "Software Engineer" - }, - "format": { - "type": "string", - "example": "FREE_FORM" - } - } - } + "reference": { + "type": [ + "string" + ], + "description": "Payment reference used for linking the PayNow transaction to the transfer created by the profile.", + "example": "PP12345678" }, - "localizedInformation": { - "type": "array", - "description": "Localized information for the profile.", - "items": { - "type": "object" + "entityName": { + "type": [ + "string" + ], + "description": "Entity name of the Wise Account to make the PayNow transfer to.", + "example": "WISE ASIA-PACIFIC PTE LTD" + } + } + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "400": { + "description": "Invalid request.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "format": "uri-reference", + "description": "Must be /errors/types/validation for this error type.", + "examples": [ + "/errors/types/validation" + ] + }, + "title": { + "type": "string", + "description": "Validation Error", + "examples": [ + "Validation Error" + ] + }, + "status": { + "type": "string", + "description": "Bad Format Validation Error", + "examples": [ + 400 + ] + }, + "instance": { + "type": "string", + "description": "The uri the triggered a validation error", + "examples": [ + "/v1/profiles/12345678/payin-sessions/74a3fe63-f37e-49ff-f744-8ef020efabcde/paynow" + ] + }, + "errors": { + "type": "array", + "description": "A list of specific validation failures.", + "items": { + "type": "object", + "properties": { + "detail": { + "type": "string", + "description": "A detailed description of the validation failure.", + "examples": [ + "Invalid request to create payment for session 1." + ] + }, + "code": { + "type": "string", + "description": "A specific code for the validation failure type.", + "examples": [ + "invalid_request" + ] + }, + "ref": { + "type": "string", + "description": "A reference to the field that failed validation." } } } @@ -15537,34 +15949,86 @@ } } }, + "422": { + "description": "Unprocessable request.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "format": "uri-reference", + "description": "Must be /errors/types/domain for this error type.", + "examples": [ + "/errors/types/domain" + ] + }, + "title": { + "type": "string", + "description": "Unprocessable Entity", + "examples": [ + "Unprocessable Entity" + ] + }, + "status": { + "type": "string", + "description": "Unprocessable Entity Domain Error", + "examples": [ + 422 + ] + }, + "instance": { + "type": "string", + "description": "The uri that triggered the error", + "examples": [ + "/v1/profiles/12345678/payin-sessions/74a3fe63-f37e-49ff-f744-8ef020efabcde/paynow" + ] + }, + "code": { + "type": "string", + "description": "Error code of the request", + "example": "payins.paynow.details.creation.not.allowed" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, "429": { "$ref": "#/components/responses/429" } } } }, - "/profiles/business-profile": { + "/profiles/{profileId}/payment-instruments": { "post": { - "operationId": "profileBusinessCreateV3", - "summary": "Create a business profile", - "description": "Creates the business profile and its authorized representative in a single request.\n\n{% admonition type=\"info\" %}\nThis request accepts an optional field in the header, `X-idempotence-uuid`. This should be unique for each Profile you create. In the event that the request fails, you should use the same value again when retrying. If the `X-idempotence-uuid` header is not provided and a Profile already exists, then you will receive a response with an HTTP status code `409`.\n{% /admonition %}\n\nSee [Business Categories](/guides/product/kyc/business-categories) for the list of valid `industryCategories` values. Send either `industryCategories` or the deprecated `firstLevelCategory`/`secondLevelCategory` pair - supplying both in one request returns a `400`. If you currently send the legacy fields, see [Migrating to industry categories](/guides/product/kyc/migrate-business-profile-industry-categories).\n", - "tags": [ - "profile" - ], + "operationId": "paymentInstrumentsCreate", + "description": "Creates a payment-instrument\n", "security": [ { "UserToken": [] } ], + "tags": [ + "payment-instruments" + ], "parameters": [ { - "name": "X-idempotence-uuid", - "in": "header", - "required": false, - "description": "Unique idempotency key for the request.", + "in": "path", + "name": "profileId", + "required": true, "schema": { - "type": "string", - "format": "uuid" + "type": "integer", + "format": "int64" } }, { @@ -15575,378 +16039,22 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "businessName": { - "type": "string", - "description": "Business name.", - "example": "ABC Logistics Ltd" - }, - "businessNameInKatakana": { - "type": [ - "string", - "null" - ], - "description": "Business name in Katakana (only for Japanese businesses).", - "example": null - }, - "businessFreeFormDescription": { - "type": "string", - "description": "Business free form description. Required if `companyType` is `OTHER`. If this is not provided for an `OTHER` companyType, the profile should not be allowed to create a transfer.\nFor the rest of the companyTypes, it is highly recommended to always provide the business' description, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.\n", - "example": "Biz free form desc" - }, - "registrationNumber": { - "type": "string", - "description": "Business registration number.", - "example": "12144939" - }, - "acn": { - "type": [ - "string", - "null" - ], - "description": "Australian Company Number (only for Australian businesses).", - "example": null - }, - "abn": { - "type": [ - "string", - "null" - ], - "description": "Australian Business Number (only for Australian businesses).", - "example": null - }, - "arbn": { - "type": [ - "string", - "null" - ], - "description": "Australian Registered Body Number (only for Australian businesses).", - "example": null - }, - "companyType": { - "type": "string", - "description": "Company legal form.", - "enum": [ - "LIMITED", - "PARTNERSHIP", - "SOLE_TRADER", - "LIMITED_BY_GUARANTEE", - "LIMITED_LIABILITY_COMPANY", - "FOR_PROFIT_CORPORATION", - "NON_PROFIT_CORPORATION", - "LIMITED_PARTNERSHIP", - "LIMITED_LIABILITY_PARTNERSHIP", - "GENERAL_PARTNERSHIP", - "SOLE_PROPRIETORSHIP", - "PRIVATE_LIMITED_COMPANY", - "PUBLIC_LIMITED_COMPANY", - "TRUST", - "OTHER" - ], - "example": "LIMITED" - }, - "companyRole": { - "type": "string", - "description": "Role of person.", - "enum": [ - "OWNER", - "DIRECTOR", - "OTHER" - ], - "example": "OWNER" - }, - "address": { - "type": "object", - "properties": { - "addressFirstLine": { - "type": "string", - "description": "First line of address.", - "example": "1 A road" - }, - "city": { - "type": "string", - "description": "City.", - "example": "London" - }, - "countryIso2Code": { - "type": "string", - "description": "2 letter country code.", - "example": "gb" - }, - "countryIso3Code": { - "type": "string", - "description": "3 letter country code. Must be lowercase.", - "example": "gbr" - }, - "postCode": { - "type": "string", - "description": "Postal code.", - "example": "11111" - }, - "stateCode": { - "type": "string", - "description": "State code." - } - } - }, - "externalCustomerId": { - "type": "string", - "description": "An external reference identifier mapping the customer of this profile to your system.", - "example": "67890-biz-acct" - }, - "actorEmail": { - "type": "string", - "description": "Email of the actor.", - "example": "biz-acct@abcl.com" - }, - "industryCategories": { - "type": "array", - "description": "One or more industry categories classifying the business. See [Business Categories](/guides/product/kyc/business-categories) for the full list of valid values.", - "minItems": 1, - "items": { - "type": "string" - }, - "example": [ - "SOFTWARE_DEVELOPMENT_PUBLISHING", - "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" - ] - }, - "firstLevelCategory": { - "type": "string", - "deprecated": true, - "description": "Legacy primary [business category](/guides/product/kyc/business-categories). Use `industryCategories` instead. Cannot be combined with `industryCategories`.\n", - "example": "CONSULTING_IT_BUSINESS_SERVICES" - }, - "secondLevelCategory": { - "type": "string", - "deprecated": true, - "description": "Legacy secondary [business category](/guides/product/kyc/business-categories). Use `industryCategories` instead. Cannot be combined with `industryCategories`.\n", - "example": "DESIGN" - }, - "operationalAddresses": { - "type": "array", - "description": "List of operational addresses.", - "items": { - "type": "object", - "properties": { - "addressFirstLine": { - "type": "string", - "example": "1 A road" - }, - "city": { - "type": "string", - "example": "London" - }, - "countryIso2Code": { - "type": "string", - "example": "gb" - }, - "countryIso3Code": { - "type": "string", - "example": "gbr" - }, - "postCode": { - "type": "string", - "example": "11111" - }, - "stateCode": { - "type": "string" - } - } - } - }, - "webpage": { - "type": "string", - "description": "Business webpage. Required if `companyType` is `OTHER`. If this is not provided for an `OTHER` companyType, the profile should not be allowed to create a transfer.\nFor the rest of the companyTypes, it is highly recommended to always provide the business' website, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.\n", - "example": "https://abc-logistics.com" - }, - "businessRepresentative": { - "type": "object", - "description": "Business representative details. Provide either the full representative details or just the `businessRepresentativeId` to link an existing representative.", - "properties": { - "businessRepresentativeId": { - "type": "integer", - "description": "ID of a Business Representative. This can be obtained from a previous call to create a business profile, in which case the same Business Representative is linked to the current business effectively sharing it across multiple businesses. When the Business Representative ID is provided, it is the only field required and none of the other fields should be provided." - }, - "firstName": { - "type": "string", - "description": "First name of the person representing the business (including middle names). Required unless Business Representative ID is provided.", - "example": "Oliver" - }, - "lastName": { - "type": "string", - "description": "Last name of the person representing the business. Required unless Business Representative ID is provided.", - "example": "Wilson" - }, - "preferredName": { - "type": "string", - "description": "Preferred first name, if different to the legal first name.", - "example": "Olivia" - }, - "address": { - "type": "object", - "properties": { - "addressFirstLine": { - "type": "string", - "description": "First line of address. Required unless Business Representative ID is provided.", - "example": "50 Sunflower Ave" - }, - "city": { - "type": "string", - "description": "City. Required unless Business Representative ID is provided.", - "example": "Phoenix" - }, - "countryIso3Code": { - "type": "string", - "description": "3 letter country code (lower case). Required unless Business Representative ID is provided.", - "example": "usa" - }, - "postCode": { - "type": "string", - "description": "Postal code.", - "example": "10025" - }, - "stateCode": { - "type": "string", - "description": "State code (max 5 chars). Required for US, CA, BR and AU addresses unless Business Representative ID is provided.", - "example": "AZ" - } - } - }, - "contactDetails": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Contact email address. Required unless Business Representative ID is provided.", - "example": "o.wilson@example.com" - }, - "phoneNumber": { - "type": "string", - "description": "Contact phone number in international phone number format. Required unless Business Representative ID is provided.", - "example": "+3725064992" - } - } - }, - "dateOfBirth": { - "type": "string", - "description": "Date of birth. Required unless Business Representative ID is provided.", - "example": "1977-07-01" - } - } - } - } - }, - "examples": { - "withRepresentativeDetails": { - "summary": "With Business Representative details", - "value": { - "businessName": "ABC Logistics Ltd", - "businessNameInKatakana": null, - "businessFreeFormDescription": "Biz free form desc", - "registrationNumber": "12144939", - "acn": null, - "abn": null, - "arbn": null, - "companyType": "LIMITED", - "companyRole": "OWNER", - "address": { - "addressFirstLine": "1 A road", - "city": "London", - "countryIso2Code": "gb", - "countryIso3Code": "gbr", - "postCode": "11111" - }, - "externalCustomerId": "67890-biz-acct", - "actorEmail": "biz-acct@abcl.com", - "industryCategories": [ - "SOFTWARE_DEVELOPMENT_PUBLISHING", - "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" - ], - "operationalAddresses": [ - { - "addressFirstLine": "1 A road", - "city": "London", - "countryIso2Code": "gb", - "countryIso3Code": "gbr", - "postCode": "11111" - } - ], - "webpage": "https://abc-logistics.com", - "businessRepresentative": { - "firstName": "Oliver", - "lastName": "Wilson", - "preferredName": "Olivia", - "address": { - "addressFirstLine": "50 Sunflower Ave", - "city": "Phoenix", - "countryIso3Code": "usa", - "postCode": "10025", - "stateCode": "AZ" - }, - "dateOfBirth": "1977-07-01", - "contactDetails": { - "email": "o.wilson@example.com", - "phoneNumber": "+3725064992" - } - } - } - }, - "withRepresentativeId": { - "summary": "With Business Representative ID", - "value": { - "businessName": "ABC Logistics Ltd", - "businessNameInKatakana": null, - "businessFreeFormDescription": "Biz free form desc", - "registrationNumber": "12144939", - "acn": null, - "abn": null, - "arbn": null, - "companyType": "LIMITED", - "companyRole": "OWNER", - "address": { - "addressFirstLine": "1 A road", - "city": "London", - "countryIso2Code": "gb", - "countryIso3Code": "gbr", - "postCode": "11111" - }, - "externalCustomerId": "67890-biz-acct", - "actorEmail": "biz-acct@abcl.com", - "industryCategories": [ - "SOFTWARE_DEVELOPMENT_PUBLISHING", - "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" - ], - "operationalAddresses": [ - { - "addressFirstLine": "1 A road", - "city": "London", - "countryIso2Code": "gb", - "countryIso3Code": "gbr", - "postCode": "11111" - } - ], - "webpage": "https://abc-logistics.com", - "businessRepresentative": { - "businessRepresentativeId": 123 - } - } - } + "$ref": "#/components/schemas/InitialiseInstrumentRequest" } } - } + }, + "required": true }, "responses": { "200": { - "description": "Created business profile.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/business-profile" + "$ref": "#/components/schemas/PaymentInstrumentDetailsResource" } } }, + "description": "OK", "headers": { "X-External-Correlation-Id": { "$ref": "#/components/headers/X-External-Correlation-Id" @@ -15959,50 +16067,54 @@ "429": { "$ref": "#/components/responses/429" } - } + }, + "summary": "Create instrument" } }, - "/profiles/{profileId}": { + "/profiles/{profileId}/payment-instruments/{paymentInstrumentId}": { "get": { - "operationId": "profileGet", - "summary": "Retrieve a profile by ID", - "description": "Get profile info by ID.\n", - "tags": [ - "profile" - ], + "operationId": "paymentInstrumentsGet", + "description": "Retrieves a payment instrument.\n", "security": [ { "UserToken": [] - }, - { - "PersonalToken": [] } ], + "tags": [ + "payment-instruments" + ], "parameters": [ { - "name": "profileId", "in": "path", + "name": "profileId", "required": true, - "description": "Profile ID.", "schema": { "type": "integer", "format": "int64" } }, + { + "in": "path", + "name": "paymentInstrumentId", + "required": true, + "schema": { + "type": "string" + } + }, { "$ref": "#/components/parameters/X-External-Correlation-Id" } ], "responses": { "200": { - "description": "Profile object.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/profile" + "$ref": "#/components/schemas/PaymentInstrumentDetailsResource" } } }, + "description": "OK", "headers": { "X-External-Correlation-Id": { "$ref": "#/components/headers/X-External-Correlation-Id" @@ -16015,36 +16127,166 @@ "429": { "$ref": "#/components/responses/429" } - } + }, + "summary": "Get payment instrument" } }, - "/profiles/{profileId}/personal-profile": { - "put": { - "operationId": "profilePersonalUpdate", - "summary": "Update a personal profile", - "description": "Update user profile information for a personal profile.\n\n{% admonition type=\"warning\" %}\nIf user profile has been verified then there are restrictions on what information is allowed to change. Where permitted, use the update window functionality by [opening the update window](/api-reference/profile/profileupdatewindowopen), submitting the updated information using this endpoint, and finally [closing the update window](/api-reference/profile/profileupdatewindowclose).\n{% /admonition %}\n", + "/profiles/{profileId}/payment-instruments/{paymentInstrumentId}/manual-confirmation": { + "post": { + "operationId": "paymentInstrumentConfirm", + "description": "Manually confirms a payment instrument\n", + "security": [ + { + "UserToken": [] + } + ], "tags": [ - "profile" + "payment-instruments" + ], + "parameters": [ + { + "in": "path", + "name": "profileId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "in": "path", + "name": "paymentInstrumentId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaymentInstrumentDetailsResource" + } + } + }, + "description": "OK", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "summary": "Confirm instrument" + } + }, + "/profiles/{profileId}/payment-instruments/{paymentInstrumentId}/payins": { + "get": { + "operationId": "paymentInstrumentGetAllPayins", + "description": "Get all payins for a given payment instrument\n", "security": [ { "UserToken": [] + } + ], + "tags": [ + "payment-instruments" + ], + "parameters": [ + { + "in": "path", + "name": "profileId", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } }, { - "PersonalToken": [] + "in": "path", + "name": "paymentInstrumentId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PayinSessionPayinInitiationResource" + } + } + } + } + } + }, + "description": "OK", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "summary": "Get all payins for a given payment instrument" + }, + "post": { + "operationId": "paymentInstrumentCreatePayin", + "description": "Create a payin for payment instrument\n", + "security": [ + { + "UserToken": [] } ], + "tags": [ + "payment-instruments" + ], "parameters": [ { - "name": "profileId", "in": "path", + "name": "profileId", "required": true, - "description": "Personal profile ID.", "schema": { "type": "integer", "format": "int64" } }, + { + "in": "path", + "name": "paymentInstrumentId", + "required": true, + "schema": { + "type": "string" + } + }, { "$ref": "#/components/parameters/X-External-Correlation-Id" } @@ -16053,14 +16295,453 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "firstName": { - "type": "string", - "maxLength": 30, - "description": "First name (including middle names).", - "example": "Oliver" - }, + "$ref": "#/components/schemas/PayinSessionPayinInitiationRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayinSessionPayinInitiationResource" + } + } + }, + "description": "OK", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "summary": "Create payin" + } + }, + "/profiles/{profileId}/transfers/{transferId}/deposit-details/bank-transfer": { + "get": { + "operationId": "payinDepositDetailGet", + "summary": "Retrieve bank transfer deposit details", + "description": "Retrieve the bank details for the account that the customer should send funds to when paying for a Wise transfer via a bank transfer.\n\n`profileId` in the request URL refers to the profile that created the transfer. It can be either the personal profile ID, or the business profile ID.\n\nThe `payinBankAccount` field allows the bank details to be displayed dynamically in a user interface, by displaying the label and value fields.\n\nCurrently, this API supports the following currencies: AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, INR, JPY, MYR, NOK, NZD, PLN, RON, SEK, SGD, TRY, USD.\n", + "tags": [ + "payin-deposit-detail" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "transferId", + "in": "path", + "required": true, + "description": "Transfer ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "Payin deposit detail object.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payinBank": { + "type": "object", + "description": "Information about the receiving bank.", + "properties": { + "bankName": { + "type": "string", + "description": "Bank name.", + "example": "Wise Europe SA/NV" + }, + "bankAddress": { + "type": [ + "object", + "null" + ], + "description": "Bank address.", + "properties": { + "country": { + "type": "string", + "description": "Country ISO 2 code.", + "example": "BE" + }, + "firstLine": { + "type": "string", + "description": "Street address.", + "example": "Rue Du Trône 100, box 3" + }, + "postCode": { + "type": "string", + "description": "Post code / zip code.", + "example": "1050" + }, + "city": { + "type": "string", + "description": "City.", + "example": "Brussels" + }, + "state": { + "type": [ + "string", + "null" + ], + "description": "State.", + "example": null + }, + "phone": { + "type": [ + "string", + "null" + ], + "description": "Phone number.", + "example": "+32 472 123 456" + } + } + } + } + }, + "payinBankAccount": { + "type": "object", + "description": "Bank account details to use to send the payment to.", + "properties": { + "currency": { + "type": "string", + "description": "ISO 4217 source currency code.", + "example": "EUR" + }, + "bankAccountType": { + "type": "string", + "description": "The type of bank account to use for the payin, e.g. RECIPIENT, ESCROW, BALANCE, etc.", + "example": "RECIPIENT" + }, + "details": { + "type": "array", + "description": "Account details.", + "items": { + "type": "object", + "description": "Account detail entry.", + "properties": { + "type": { + "type": "string", + "description": "Account details type, e.g. accountNumber, iban etc.", + "example": "iban" + }, + "label": { + "type": "string", + "description": "Account details label that should be displayed in your user interface.", + "example": "IBAN" + }, + "value": { + "type": "string", + "description": "Account details value. This field is deprecated. Use `rawValue` and `formattedValue` instead.", + "example": "BE11111111111111", + "deprecated": true + }, + "rawValue": { + "type": "string", + "description": "Account details value, always unformatted. Can be used for processing.", + "example": "BE11111111111111" + }, + "formattedValue": { + "type": [ + "string", + "null" + ], + "description": "Account details value, formatted according to the type of the field. Intended to be human-readable. This can be null.", + "example": "BE11 1111 1111 1111" + }, + "description": { + "type": "string", + "description": "Description of the account detail type.", + "example": "International Bank Account Number" + } + } + } + } + } + }, + "wiseInformation": { + "type": "object", + "description": "Information about the receiving Wise entity, the owner of the bank account.", + "properties": { + "localCompanyName": { + "type": "string", + "description": "Wise local company name.", + "example": "Wise Europe SA" + }, + "localAddress": { + "type": [ + "object", + "null" + ], + "description": "Wise local address.", + "properties": { + "country": { + "type": "string", + "description": "Country ISO 2 code.", + "example": "BE" + }, + "firstLine": { + "type": "string", + "description": "Street address.", + "example": "Rue du Trône 100, 3rd floor" + }, + "postCode": { + "type": "string", + "description": "Post code / zip code.", + "example": "1050" + }, + "city": { + "type": "string", + "description": "City.", + "example": "Brussels" + }, + "state": { + "type": [ + "string", + "null" + ], + "description": "State.", + "example": null + }, + "phone": { + "type": [ + "string", + "null" + ], + "description": "Phone number.", + "example": null + } + } + } + } + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles": { + "get": { + "operationId": "profileList", + "summary": "List profiles for a user account", + "description": "List of all profiles belonging to user.\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + }, + { + "PersonalToken": [] + } + ], + "responses": { + "200": { + "description": "Array of profile objects. Note that there might be more than one business profile returned in the response.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/profile" + } + }, + "example": [ + { + "type": "PERSONAL", + "id": 14575282, + "publicId": "a1b2c3d4-e5f6-7890-1234-567890abcdef", + "userId": 9889627, + "address": { + "id": 36086782, + "addressFirstLine": "24 Willow Creek Lane", + "city": "Bristol", + "countryIso2Code": "GB", + "countryIso3Code": "gbr", + "postCode": "BS1 6AE", + "stateCode": null + }, + "email": "sarah.jenkins@example.com", + "createdAt": "2023-01-15T10:30:00", + "updatedAt": "2025-06-18T14:20:00", + "avatar": "https://example.com/avatars/sarah_jenkins.png", + "currentState": "VISIBLE", + "contactDetails": { + "email": "sarah.contact@example.com", + "phoneNumber": "+447700900123" + }, + "firstName": "Sarah", + "lastName": "Jenkins", + "preferredName": "Sal", + "dateOfBirth": "1985-05-20", + "phoneNumber": "+447700900456", + "secondaryAddresses": [], + "fullName": "Sarah Jenkins" + }, + { + "type": "BUSINESS", + "id": 14599371, + "publicId": "f0e9d8c7-b6a5-4321-fedc-ba9876543210", + "userId": 9889627, + "address": { + "id": 36152772, + "addressFirstLine": "15 Tech Hub Studios", + "city": "Manchester", + "countryIso2Code": "GB", + "countryIso3Code": "gbr", + "postCode": "M1 7JA", + "stateCode": null + }, + "email": "info@innovate-solutions.co.uk", + "createdAt": "2024-03-10T09:00:00", + "updatedAt": "2025-06-18T14:22:00", + "contactDetails": { + "email": "contact@innovate-solutions.co.uk", + "phoneNumber": "+441617891234" + }, + "businessName": "Innovate Solutions Ltd", + "registrationNumber": "SC1234567890ABCD", + "descriptionOfBusiness": "IT_DEVELOPMENT", + "webpage": "https://www.innovate-solutions.co.uk", + "companyType": "LIMITED_COMPANY", + "businessFreeFormDescription": "We create cutting-edge software for businesses.", + "firstLevelCategory": "CONSULTING_IT_BUSINESS_SERVICES", + "secondLevelCategory": "IT_DEVELOPMENT", + "industryCategories": [ + "SOFTWARE_DEVELOPMENT_PUBLISHING", + "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" + ], + "operationalAddresses": [ + { + "id": 36152773, + "addressFirstLine": "Unit 5, Innovation Park", + "city": "Leeds", + "countryIso2Code": "GB", + "countryIso3Code": "gbr", + "postCode": "LS1 4YZ", + "stateCode": null + } + ], + "fullName": "Innovate Solutions Ltd" + } + ] + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ] + } + }, + "/profiles/personal-profile": { + "post": { + "operationId": "profilePersonalCreate", + "summary": "Create a personal profile", + "description": "Create a personal profile for the authenticated user. A personal profile represents an individual and is required before creating transfers or business profiles.\n\n{% admonition type=\"info\" %}\nUse the `X-idempotence-uuid` header to safely retry requests. If omitted and a profile already exists, the API returns `409 Conflict`. You can then retrieve existing profiles via [List profiles](/api-reference/profile/profilelist).\n{% /admonition %}\n\nField notes {% .title-4 .m-t-3 %}\n\n- **First and last names** are limited to 30 characters each. Truncate if necessary (e.g. when a customer has many middle names).\n- **`occupations`** is required for CA, IN, JP, ID, IL, MX, and within the US for the state NM.\n- **`contactDetails`** are used for mandatory customer notifications and to help identify your customer when contacting Wise support.\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + }, + { + "PersonalToken": [] + } + ], + "parameters": [ + { + "name": "X-idempotence-uuid", + "in": "header", + "required": false, + "description": "Unique idempotency key for the request.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "firstName", + "lastName", + "dateOfBirth", + "address", + "contactDetails" + ], + "properties": { + "firstName": { + "type": "string", + "maxLength": 30, + "description": "First name (including middle names).", + "example": "Oliver" + }, "lastName": { "type": "string", "maxLength": 30, @@ -16091,6 +16772,11 @@ }, "address": { "type": "object", + "required": [ + "addressFirstLine", + "city", + "countryIso3Code" + ], "properties": { "addressFirstLine": { "type": "string", @@ -16104,12 +16790,12 @@ }, "countryIso3Code": { "type": "string", - "description": "3 letter country code (ISO3, lower case).", + "description": "3 letter country code (lower case).", "example": "usa" }, "postCode": { "type": "string", - "description": "Postal code or ZIP code.", + "description": "Postal code.", "example": "10025" }, "stateCode": { @@ -16122,7 +16808,7 @@ }, "nationality": { "type": "string", - "description": "3 letter country code (ISO3, lower case).", + "description": "3 letter country code (lower case).", "example": "usa" }, "dateOfBirth": { @@ -16130,8 +16816,17 @@ "description": "Date of birth.", "example": "1977-07-01" }, + "externalCustomerId": { + "type": "string", + "description": "An external reference identifier mapping the customer of this profile to your system.", + "example": "12345-oliver-wilson" + }, "contactDetails": { "type": "object", + "required": [ + "email", + "phoneNumber" + ], "properties": { "email": { "type": "string", @@ -16145,11 +16840,6 @@ } } }, - "externalCustomerId": { - "type": "string", - "description": "An external reference identifier mapping the customer of this profile to your system.", - "example": "12345-oliver-wilson" - }, "occupations": { "type": "array", "items": { @@ -16175,49 +16865,182 @@ }, "responses": { "200": { - "description": "Updated personal profile.", - "headers": { - "X-External-Correlation-Id": { - "$ref": "#/components/headers/X-External-Correlation-Id" - }, - "x-trace-id": { - "$ref": "#/components/headers/x-trace-id" - } - } - }, - "429": { - "$ref": "#/components/responses/429" - } - } - } - }, - "/profiles/{profileId}/business-profile": { - "put": { - "operationId": "profileBusinessUpdate", - "summary": "Update a business profile", - "description": "Update user profile information for a business profile.\n\n{% admonition type=\"warning\" %}\nIf user profile has been verified then there are restrictions on what information is allowed to change.\n{% /admonition %}\n\nWhere permitted, use the update window functionality by [opening the update window](/api-reference/profile/profileupdatewindowopen), submitting the updated information using this endpoint, and finally [closing the update window](/api-reference/profile/profileupdatewindowclose).\n\nSee [Business Categories](/guides/product/kyc/business-categories) for the list of valid `industryCategories` values. Send either `industryCategories` or the deprecated `firstLevelCategory`/`secondLevelCategory` pair, changing both in one request returns a `400`. If you currently send the legacy fields, see [Migrating to industry categories](/guides/product/kyc/migrate-business-profile-industry-categories).\n", - "tags": [ - "profile" - ], - "security": [ - { - "UserToken": [] - }, - { - "PersonalToken": [] - } - ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Business profile ID.", - "schema": { - "type": "integer", - "format": "int64" - } - }, + "description": "Created personal profile.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "Unique profile ID.", + "example": 30000001 + }, + "type": { + "type": "string", + "description": "Profile type.", + "enum": [ + "PERSONAL" + ], + "example": "PERSONAL" + }, + "details": { + "type": "object", + "description": "Profile details.", + "properties": { + "firstName": { + "type": "string", + "description": "First name (including middle names).", + "example": "Oliver" + }, + "lastName": { + "type": "string", + "description": "Last name.", + "example": "Wilson" + }, + "preferredName": { + "type": "string", + "description": "Preferred first name.", + "example": "Olivia" + }, + "firstNameInKana": { + "type": [ + "string", + "null" + ], + "description": "First name in Katakana.", + "example": null + }, + "lastNameInKana": { + "type": [ + "string", + "null" + ], + "description": "Last name in Katakana.", + "example": null + }, + "address": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string", + "example": "50 Sunflower Ave" + }, + "city": { + "type": "string", + "example": "Phoenix" + }, + "countryIso3Code": { + "type": "string", + "example": "usa" + }, + "postCode": { + "type": "string", + "example": "10025" + }, + "stateCode": { + "type": "string", + "example": "AZ" + } + } + }, + "nationality": { + "type": "string", + "description": "3 letter country code (lower case).", + "example": "usa" + }, + "dateOfBirth": { + "type": "string", + "description": "Date of birth.", + "example": "1977-07-01" + }, + "externalCustomerId": { + "type": "string", + "description": "External reference identifier in your system.", + "example": "12345-oliver-wilson" + }, + "contactDetails": { + "type": "object", + "properties": { + "email": { + "type": "string", + "example": "o.wilson@example.com" + }, + "phoneNumber": { + "type": "string", + "example": "+3725064992" + } + } + }, + "occupations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "Software Engineer" + }, + "format": { + "type": "string", + "example": "FREE_FORM" + } + } + } + }, + "localizedInformation": { + "type": "array", + "description": "Localized information for the profile.", + "items": { + "type": "object" + } + } + } + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles/business-profile": { + "post": { + "operationId": "profileBusinessCreateV3", + "summary": "Create a business profile", + "description": "Creates the business profile and its authorized representative in a single request.\n\n{% admonition type=\"info\" %}\nThis request accepts an optional field in the header, `X-idempotence-uuid`. This should be unique for each Profile you create. In the event that the request fails, you should use the same value again when retrying. If the `X-idempotence-uuid` header is not provided and a Profile already exists, then you will receive a response with an HTTP status code `409`.\n{% /admonition %}\n\nSee [Business Categories](/guides/product/kyc/business-categories) for the list of valid `industryCategories` values. Send either `industryCategories` or the deprecated `firstLevelCategory`/`secondLevelCategory` pair, supplying both in one request returns a `400`. If you currently send the legacy fields, see [Migrating to industry categories](/guides/product/kyc/migrate-business-profile-industry-categories).\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "X-idempotence-uuid", + "in": "header", + "required": false, + "description": "Unique idempotency key for the request.", + "schema": { + "type": "string", + "format": "uuid" + } + }, { "$ref": "#/components/parameters/X-External-Correlation-Id" } @@ -16228,12 +17051,6 @@ "schema": { "type": "object", "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "Business profile ID. This must match the business profile ID supplied in the URL.", - "example": 14599371 - }, "businessName": { "type": "string", "description": "Business name.", @@ -16249,7 +17066,7 @@ }, "businessFreeFormDescription": { "type": "string", - "description": "Business free form description.", + "description": "Business free form description. Required if `companyType` is `OTHER`. If this is not provided for an `OTHER` companyType, the profile should not be allowed to create a transfer.\nFor the rest of the companyTypes, it is highly recommended to always provide the business' description, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.\n", "example": "Biz free form desc" }, "registrationNumber": { @@ -16303,6 +17120,16 @@ ], "example": "LIMITED" }, + "companyRole": { + "type": "string", + "description": "Role of person.", + "enum": [ + "OWNER", + "DIRECTOR", + "OTHER" + ], + "example": "OWNER" + }, "address": { "type": "object", "properties": { @@ -16333,29 +17160,47 @@ }, "stateCode": { "type": "string", - "maxLength": 5, "description": "State code." } } }, - "companyRole": { - "type": "string", - "description": "Role of person.", - "enum": [ - "OWNER", - "DIRECTOR", - "OTHER" + "contactDetails": { + "type": "object", + "description": "Optional contact details for the business, separate from the representative's contact details.", + "required": [ + "email", + "phoneNumber" ], - "example": "OWNER" + "properties": { + "email": { + "type": "string", + "format": "email", + "minLength": 1, + "description": "Contact email address for the business.", + "example": "contact@innovate-solutions.co.uk" + }, + "phoneNumber": { + "type": "string", + "minLength": 5, + "maxLength": 25, + "description": "Contact phone number for the business.", + "example": "+441617891234" + } + } }, "externalCustomerId": { "type": "string", "description": "An external reference identifier mapping the customer of this profile to your system.", "example": "67890-biz-acct" }, + "actorEmail": { + "type": "string", + "description": "Email of the actor.", + "example": "biz-acct@abcl.com" + }, "industryCategories": { "type": "array", - "description": "One or more industry categories classifying the business. See [Business Categories](guides/product/kyc/business-categories) for the full list of valid values.", + "description": "One or more industry categories classifying the business. See [Business Categories](/guides/product/kyc/business-categories) for the full list of valid values.", "minItems": 1, "items": { "type": "string" @@ -16404,8 +17249,7 @@ "example": "11111" }, "stateCode": { - "type": "string", - "maxLength": 5 + "type": "string" } } } @@ -16414,6 +17258,226 @@ "type": "string", "description": "Business webpage. Required if `companyType` is `OTHER`. If this is not provided for an `OTHER` companyType, the profile should not be allowed to create a transfer.\nFor the rest of the companyTypes, it is highly recommended to always provide the business' website, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.\n", "example": "https://abc-logistics.com" + }, + "businessRepresentative": { + "type": "object", + "description": "Business representative details. Provide either the full representative details or just the `businessRepresentativeId` to link an existing representative.", + "properties": { + "businessRepresentativeId": { + "type": "integer", + "description": "ID of a Business Representative. This can be obtained from a previous call to create a business profile, in which case the same Business Representative is linked to the current business effectively sharing it across multiple businesses. When the Business Representative ID is provided, it is the only field required and none of the other fields should be provided." + }, + "firstName": { + "type": "string", + "description": "First name of the person representing the business (including middle names). Required unless Business Representative ID is provided.", + "example": "Oliver" + }, + "lastName": { + "type": "string", + "description": "Last name of the person representing the business. Required unless Business Representative ID is provided.", + "example": "Wilson" + }, + "preferredName": { + "type": "string", + "description": "Preferred first name, if different to the legal first name.", + "example": "Olivia" + }, + "address": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string", + "description": "First line of address. Required unless Business Representative ID is provided.", + "example": "50 Sunflower Ave" + }, + "city": { + "type": "string", + "description": "City. Required unless Business Representative ID is provided.", + "example": "Phoenix" + }, + "countryIso3Code": { + "type": "string", + "description": "3 letter country code (lower case). Required unless Business Representative ID is provided.", + "example": "usa" + }, + "postCode": { + "type": "string", + "description": "Postal code.", + "example": "10025" + }, + "stateCode": { + "type": "string", + "description": "State code (max 5 chars). Required for US, CA, BR and AU addresses unless Business Representative ID is provided.", + "example": "AZ" + } + } + }, + "contactDetails": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Contact email address. Required unless Business Representative ID is provided.", + "example": "o.wilson@example.com" + }, + "phoneNumber": { + "type": "string", + "description": "Contact phone number in international phone number format. Required unless Business Representative ID is provided.", + "example": "+3725064992" + } + } + }, + "dateOfBirth": { + "type": "string", + "description": "Date of birth. Required unless Business Representative ID is provided.", + "example": "1977-07-01" + }, + "localizedInformation": { + "type": "array", + "description": "Optional localized information for the business representative.\nFor Kana names, provide both firstName and lastName entries\nwith localeScriptCode set to Kana.\nEach combination of key and localeScriptCode must be unique.\n", + "items": { + "type": "object", + "required": [ + "key", + "value", + "localeScriptCode" + ], + "properties": { + "key": { + "type": "string", + "description": "Name of the field being localized.", + "example": "firstName" + }, + "value": { + "type": "string", + "description": "Localized value of the field.", + "example": "タロウ" + }, + "localeScriptCode": { + "type": "string", + "description": "Script code for the localized value.", + "example": "Kana" + } + } + } + } + } + } + } + }, + "examples": { + "withRepresentativeDetails": { + "summary": "With Business Representative details", + "value": { + "businessName": "ABC Logistics Ltd", + "businessNameInKatakana": null, + "businessFreeFormDescription": "Biz free form desc", + "registrationNumber": "12144939", + "acn": null, + "abn": null, + "arbn": null, + "companyType": "LIMITED", + "companyRole": "OWNER", + "address": { + "addressFirstLine": "1 A road", + "city": "London", + "countryIso2Code": "gb", + "countryIso3Code": "gbr", + "postCode": "11111" + }, + "contactDetails": { + "email": "contact@innovate-solutions.co.uk", + "phoneNumber": "+441617891234" + }, + "externalCustomerId": "67890-biz-acct", + "actorEmail": "biz-acct@abcl.com", + "industryCategories": [ + "SOFTWARE_DEVELOPMENT_PUBLISHING", + "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" + ], + "operationalAddresses": [ + { + "addressFirstLine": "1 A road", + "city": "London", + "countryIso2Code": "gb", + "countryIso3Code": "gbr", + "postCode": "11111" + } + ], + "webpage": "https://abc-logistics.com", + "businessRepresentative": { + "firstName": "Oliver", + "lastName": "Wilson", + "localizedInformation": [ + { + "key": "firstName", + "value": "オリバー", + "localeScriptCode": "Kana" + }, + { + "key": "lastName", + "value": "ウィルソン", + "localeScriptCode": "Kana" + } + ], + "preferredName": "Olivia", + "address": { + "addressFirstLine": "50 Sunflower Ave", + "city": "Phoenix", + "countryIso3Code": "usa", + "postCode": "10025", + "stateCode": "AZ" + }, + "dateOfBirth": "1977-07-01", + "contactDetails": { + "email": "o.wilson@example.com", + "phoneNumber": "+3725064992" + } + } + } + }, + "withRepresentativeId": { + "summary": "With Business Representative ID", + "value": { + "businessName": "ABC Logistics Ltd", + "businessNameInKatakana": null, + "businessFreeFormDescription": "Biz free form desc", + "registrationNumber": "12144939", + "acn": null, + "abn": null, + "arbn": null, + "companyType": "LIMITED", + "companyRole": "OWNER", + "address": { + "addressFirstLine": "1 A road", + "city": "London", + "countryIso2Code": "gb", + "countryIso3Code": "gbr", + "postCode": "11111" + }, + "contactDetails": { + "email": "contact@innovate-solutions.co.uk", + "phoneNumber": "+441617891234" + }, + "externalCustomerId": "67890-biz-acct", + "actorEmail": "biz-acct@abcl.com", + "industryCategories": [ + "SOFTWARE_DEVELOPMENT_PUBLISHING", + "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" + ], + "operationalAddresses": [ + { + "addressFirstLine": "1 A road", + "city": "London", + "countryIso2Code": "gb", + "countryIso3Code": "gbr", + "postCode": "11111" + } + ], + "webpage": "https://abc-logistics.com", + "businessRepresentative": { + "businessRepresentativeId": 123 + } } } } @@ -16422,7 +17486,7 @@ }, "responses": { "200": { - "description": "Updated business profile.", + "description": "Created business profile.", "content": { "application/json": { "schema": { @@ -16445,17 +17509,20 @@ } } }, - "/profiles/{profileId}/business-profile/business-representative": { + "/profiles/{profileId}": { "get": { - "operationId": "profileBusinessRepresentativeGet", - "summary": "Retrieve business representative", - "description": "Get Business Representative info by Business Profile ID.\n", + "operationId": "profileGet", + "summary": "Retrieve a profile by ID", + "description": "Get profile info by ID.\n", "tags": [ "profile" ], "security": [ { "UserToken": [] + }, + { + "PersonalToken": [] } ], "parameters": [ @@ -16463,7 +17530,7 @@ "name": "profileId", "in": "path", "required": true, - "description": "Business profile ID.", + "description": "Profile ID.", "schema": { "type": "integer", "format": "int64" @@ -16475,7 +17542,14 @@ ], "responses": { "200": { - "description": "Business representative object.", + "description": "Profile object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/profile" + } + } + }, "headers": { "X-External-Correlation-Id": { "$ref": "#/components/headers/X-External-Correlation-Id" @@ -16489,17 +17563,22 @@ "$ref": "#/components/responses/429" } } - }, + } + }, + "/profiles/{profileId}/personal-profile": { "put": { - "operationId": "profileBusinessRepresentativeUpdate", - "summary": "Update business representative", - "description": "Update or transfer the Business Representative for the specified Business Profile.\n\nSet `updateContext` to `UPDATE_DETAILS` to update the existing Business Representative's details, or `TRANSFER_OF_AUTHORISATION` to transfer authority of the Business Profile to a new Business Representative.\n\n{% admonition type=\"info\" %}\nIf the Business Representative has been verified then there are restrictions on what information is allowed to change.\n{% /admonition %}\n\n{% admonition type=\"info\" %}\nIf this Business Representative is shared across multiple Business Profiles, then changes will be reflected for all of the Business Profiles.\n{% /admonition %}\n\nWhen using `TRANSFER_OF_AUTHORISATION`, this will overwrite the existing Business Representative. The new Business Representative will need to be verified for KYC purposes.\n", + "operationId": "profilePersonalUpdate", + "summary": "Update a personal profile", + "description": "Update user profile information for a personal profile.\n\n{% admonition type=\"warning\" %}\nIf user profile has been verified then there are restrictions on what information is allowed to change. Where permitted, use the update window functionality by [opening the update window](/api-reference/profile/profileupdatewindowopen), submitting the updated information using this endpoint, and finally [closing the update window](/api-reference/profile/profileupdatewindowclose).\n{% /admonition %}\n", "tags": [ "profile" ], "security": [ { "UserToken": [] + }, + { + "PersonalToken": [] } ], "parameters": [ @@ -16507,7 +17586,7 @@ "name": "profileId", "in": "path", "required": true, - "description": "Business profile ID.", + "description": "Personal profile ID.", "schema": { "type": "integer", "format": "int64" @@ -16523,30 +17602,40 @@ "schema": { "type": "object", "properties": { - "updateContext": { - "type": "string", - "description": "Context of the update.", - "enum": [ - "UPDATE_DETAILS", - "TRANSFER_OF_AUTHORISATION" - ], - "example": "UPDATE_DETAILS" - }, "firstName": { "type": "string", - "description": "First name of the person representing the business (including middle names).", + "maxLength": 30, + "description": "First name (including middle names).", "example": "Oliver" }, "lastName": { "type": "string", - "description": "Last name of the person representing the business.", + "maxLength": 30, + "description": "Last name.", "example": "Wilson" }, "preferredName": { "type": "string", + "maxLength": 30, "description": "Preferred first name, if different to the legal first name.", "example": "Olivia" }, + "firstNameInKana": { + "type": [ + "string", + "null" + ], + "description": "First name in Katakana. Required for from-JPY personal transfers.", + "example": null + }, + "lastNameInKana": { + "type": [ + "string", + "null" + ], + "description": "Last name in Katakana. Required for from-JPY personal transfers.", + "example": null + }, "address": { "type": "object", "properties": { @@ -16562,28 +17651,510 @@ }, "countryIso3Code": { "type": "string", - "description": "3 letter country code (lower case).", + "description": "3 letter country code (ISO3, lower case).", "example": "usa" }, "postCode": { "type": "string", - "description": "Postal code.", + "description": "Postal code or ZIP code.", "example": "10025" }, "stateCode": { "type": "string", - "description": "State code (max 5 chars). Required for US, CA, BR and AU addresses.", + "maxLength": 5, + "description": "State code. Required for US, CA, BR and AU addresses.", "example": "AZ" } } }, - "contactDetails": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Contact email address of the person representing the business. Please speak with your integration account manager for details on how customer communication is handled for your integration.", - "example": "o.wilson@example.com" + "nationality": { + "type": "string", + "description": "3 letter country code (ISO3, lower case).", + "example": "usa" + }, + "dateOfBirth": { + "type": "string", + "description": "Date of birth.", + "example": "1977-07-01" + }, + "contactDetails": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Contact email address. Please speak with your integration account manager for details on how customer communication is handled for your integration.", + "example": "o.wilson@example.com" + }, + "phoneNumber": { + "type": "string", + "description": "Contact phone number in international phone number format, example \"+1408XXXXXXX\".", + "example": "+3725064992" + } + } + }, + "externalCustomerId": { + "type": "string", + "description": "An external reference identifier mapping the customer of this profile to your system.", + "example": "12345-oliver-wilson" + }, + "occupations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "Occupation field code - this field accepts any job or occupation that the customer does, as the only occupation format currently accepted is `\"FREE_FORM\"`.", + "example": "Software Engineer" + }, + "format": { + "type": "string", + "description": "Occupation field format. As of now, it only accepts the value `\"FREE_FORM\"`.", + "example": "FREE_FORM" + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Updated personal profile.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles/{profileId}/business-profile": { + "put": { + "operationId": "profileBusinessUpdate", + "summary": "Update a business profile", + "description": "Update user profile information for a business profile.\n\n{% admonition type=\"warning\" %}\nIf user profile has been verified then there are restrictions on what information is allowed to change.\n{% /admonition %}\n\nWhere permitted, use the update window functionality by [opening the update window](/api-reference/profile/profileupdatewindowopen), submitting the updated information using this endpoint, and finally [closing the update window](/api-reference/profile/profileupdatewindowclose).\n\nSee [Business Categories](/guides/product/kyc/business-categories) for the list of valid `industryCategories` values. Send either `industryCategories` or the deprecated `firstLevelCategory`/`secondLevelCategory` pair, changing both in one request returns a `400`. If you currently send the legacy fields, see [Migrating to industry categories](/guides/product/kyc/migrate-business-profile-industry-categories).\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + }, + { + "PersonalToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "Business profile ID. This must match the business profile ID supplied in the URL.", + "example": 14599371 + }, + "businessName": { + "type": "string", + "description": "Business name.", + "example": "ABC Logistics Ltd" + }, + "businessNameInKatakana": { + "type": [ + "string", + "null" + ], + "description": "Business name in Katakana (only for Japanese businesses).", + "example": null + }, + "businessFreeFormDescription": { + "type": "string", + "description": "Business free form description.", + "example": "Biz free form desc" + }, + "registrationNumber": { + "type": "string", + "description": "Business registration number.", + "example": "12144939" + }, + "acn": { + "type": [ + "string", + "null" + ], + "description": "Australian Company Number (only for Australian businesses).", + "example": null + }, + "abn": { + "type": [ + "string", + "null" + ], + "description": "Australian Business Number (only for Australian businesses).", + "example": null + }, + "arbn": { + "type": [ + "string", + "null" + ], + "description": "Australian Registered Body Number (only for Australian businesses).", + "example": null + }, + "companyType": { + "type": "string", + "description": "Company legal form.", + "enum": [ + "LIMITED", + "PARTNERSHIP", + "SOLE_TRADER", + "LIMITED_BY_GUARANTEE", + "LIMITED_LIABILITY_COMPANY", + "FOR_PROFIT_CORPORATION", + "NON_PROFIT_CORPORATION", + "LIMITED_PARTNERSHIP", + "LIMITED_LIABILITY_PARTNERSHIP", + "GENERAL_PARTNERSHIP", + "SOLE_PROPRIETORSHIP", + "PRIVATE_LIMITED_COMPANY", + "PUBLIC_LIMITED_COMPANY", + "TRUST", + "OTHER" + ], + "example": "LIMITED" + }, + "address": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string", + "description": "First line of address.", + "example": "1 A road" + }, + "city": { + "type": "string", + "description": "City.", + "example": "London" + }, + "countryIso2Code": { + "type": "string", + "description": "2 letter country code.", + "example": "gb" + }, + "countryIso3Code": { + "type": "string", + "description": "3 letter country code. Must be lowercase.", + "example": "gbr" + }, + "postCode": { + "type": "string", + "description": "Postal code.", + "example": "11111" + }, + "stateCode": { + "type": "string", + "maxLength": 5, + "description": "State code." + } + } + }, + "companyRole": { + "type": "string", + "description": "Role of person.", + "enum": [ + "OWNER", + "DIRECTOR", + "OTHER" + ], + "example": "OWNER" + }, + "contactDetails": { + "type": "object", + "description": "Optional contact details for the business, separate from the representative's contact details.", + "required": [ + "email", + "phoneNumber" + ], + "properties": { + "email": { + "type": "string", + "format": "email", + "minLength": 1, + "description": "Contact email address for the business.", + "example": "contact@innovate-solutions.co.uk" + }, + "phoneNumber": { + "type": "string", + "minLength": 5, + "maxLength": 25, + "description": "Contact phone number for the business.", + "example": "+441617891234" + } + } + }, + "externalCustomerId": { + "type": "string", + "description": "An external reference identifier mapping the customer of this profile to your system.", + "example": "67890-biz-acct" + }, + "industryCategories": { + "type": "array", + "description": "One or more industry categories classifying the business. See [Business Categories](/guides/product/kyc/business-categories) for the full list of valid values.", + "minItems": 1, + "items": { + "type": "string" + }, + "example": [ + "SOFTWARE_DEVELOPMENT_PUBLISHING", + "IT_CONSULTANCY_TECHNICAL_SUPPORT_SERVICES" + ] + }, + "firstLevelCategory": { + "type": "string", + "deprecated": true, + "description": "Legacy primary [business category](/guides/product/kyc/business-categories). Use `industryCategories` instead. Cannot be combined with `industryCategories`.\n", + "example": "CONSULTING_IT_BUSINESS_SERVICES" + }, + "secondLevelCategory": { + "type": "string", + "deprecated": true, + "description": "Legacy secondary [business category](/guides/product/kyc/business-categories). Use `industryCategories` instead. Cannot be combined with `industryCategories`.\n", + "example": "DESIGN" + }, + "operationalAddresses": { + "type": "array", + "description": "List of operational addresses.", + "items": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string", + "example": "1 A road" + }, + "city": { + "type": "string", + "example": "London" + }, + "countryIso2Code": { + "type": "string", + "example": "gb" + }, + "countryIso3Code": { + "type": "string", + "example": "gbr" + }, + "postCode": { + "type": "string", + "example": "11111" + }, + "stateCode": { + "type": "string", + "maxLength": 5 + } + } + } + }, + "webpage": { + "type": "string", + "description": "Business webpage. Required if `companyType` is `OTHER`. If this is not provided for an `OTHER` companyType, the profile should not be allowed to create a transfer.\nFor the rest of the companyTypes, it is highly recommended to always provide the business' website, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.\n", + "example": "https://abc-logistics.com" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Updated business profile.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/business-profile" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles/{profileId}/business-profile/business-representative": { + "get": { + "operationId": "profileBusinessRepresentativeGet", + "summary": "Retrieve business representative", + "description": "Get Business Representative info by Business Profile ID.\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "Business representative object.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + }, + "put": { + "operationId": "profileBusinessRepresentativeUpdate", + "summary": "Update business representative", + "description": "Update or transfer the Business Representative for the specified Business Profile.\n\nSet `updateContext` to `UPDATE_DETAILS` to update the existing Business Representative's details, or `TRANSFER_OF_AUTHORISATION` to transfer authority of the Business Profile to a new Business Representative.\n\n{% admonition type=\"info\" %}\nIf the Business Representative has been verified then there are restrictions on what information is allowed to change.\n{% /admonition %}\n\n{% admonition type=\"info\" %}\nIf this Business Representative is shared across multiple Business Profiles, then changes will be reflected for all of the Business Profiles.\n{% /admonition %}\n\nWhen using `TRANSFER_OF_AUTHORISATION`, this will overwrite the existing Business Representative. The new Business Representative will need to be verified for KYC purposes.\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "updateContext": { + "type": "string", + "description": "Context of the update.", + "enum": [ + "UPDATE_DETAILS", + "TRANSFER_OF_AUTHORISATION" + ], + "example": "UPDATE_DETAILS" + }, + "firstName": { + "type": "string", + "description": "First name of the person representing the business (including middle names).", + "example": "Oliver" + }, + "lastName": { + "type": "string", + "description": "Last name of the person representing the business.", + "example": "Wilson" + }, + "preferredName": { + "type": "string", + "description": "Preferred first name, if different to the legal first name.", + "example": "Olivia" + }, + "address": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string", + "description": "First line of address.", + "example": "50 Sunflower Ave" + }, + "city": { + "type": "string", + "description": "City.", + "example": "Phoenix" + }, + "countryIso3Code": { + "type": "string", + "description": "3 letter country code (lower case).", + "example": "usa" + }, + "postCode": { + "type": "string", + "description": "Postal code.", + "example": "10025" + }, + "stateCode": { + "type": "string", + "description": "State code (max 5 chars). Required for US, CA, BR and AU addresses.", + "example": "AZ" + } + } + }, + "contactDetails": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Contact email address of the person representing the business. Please speak with your integration account manager for details on how customer communication is handled for your integration.", + "example": "o.wilson@example.com" }, "phoneNumber": { "type": "string", @@ -16601,6 +18172,35 @@ "type": "string", "description": "Email of the actor.", "example": "biz-acct@abcl.com" + }, + "localizedInformation": { + "type": "array", + "description": "Optional localized information for the business representative.\nFor Kana names, provide both firstName and lastName entries\nwith localeScriptCode set to Kana.\nEach combination of key and localeScriptCode must be unique.\n", + "items": { + "type": "object", + "required": [ + "key", + "value", + "localeScriptCode" + ], + "properties": { + "key": { + "type": "string", + "description": "Name of the field being localized.", + "example": "firstName" + }, + "value": { + "type": "string", + "description": "Localized value of the field.", + "example": "タロウ" + }, + "localeScriptCode": { + "type": "string", + "description": "Script code for the localized value.", + "example": "Kana" + } + } + } } } }, @@ -16612,7 +18212,19 @@ "contactDetails": { "email": "o.wilson@example.com", "phoneNumber": "+3725064992" - } + }, + "localizedInformation": [ + { + "key": "firstName", + "value": "タロウ", + "localeScriptCode": "Kana" + }, + { + "key": "lastName", + "value": "ヤマダ", + "localeScriptCode": "Kana" + } + ] } }, "transferOfAuthorisation": { @@ -16837,7 +18449,7 @@ } }, "422": { - "description": "Request could not be processed due to a missing prerequisite.\n\nReturned when submitting `FINANCIAL_CAPACITY_BR` for a profile that has no tax ID on record.\n", + "description": "Request could not be processed due to a missing prerequisite.\nReturned when submitting `FINANCIAL_CAPACITY_BR` for a profile that has no tax ID on record.\n", "content": { "application/json": { "schema": { @@ -17430,13 +19042,83 @@ "$ref": "#/components/responses/429" } } - } - }, - "/profiles/{profileId}/ubos": { - "post": { - "operationId": "profileUboCreate", - "summary": "Create business ultimate owners", - "description": "Adds new ultimate beneficial owners to the business profile.\n\nReturns the list of all ultimate beneficial owners associated with the business profile.\n\nAll the shareholders that have at least 25% ownership should be submitted via this API.\n\nNote that in some cases, we do not require the `ownershipPercentage`. In these cases, `null` should be passed as the value.\n", + }, + "delete": { + "operationId": "profileDirectorsDelete", + "summary": "Delete all business directors", + "description": "Deletes all director objects associated with the business profile.\n", + "tags": [ + "profile" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "List of all directors deleted from the business profile.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/director" + } + }, + "example": [ + { + "id": 14, + "firstName": "John", + "lastName": "Doe", + "dateOfBirth": "1982-05-20", + "countryOfResidenceIso3Code": "usa" + }, + { + "id": 15, + "firstName": "Jane", + "lastName": "Doe", + "dateOfBirth": "1981-12-07", + "countryOfResidenceIso3Code": "usa" + } + ] + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles/{profileId}/ubos": { + "post": { + "operationId": "profileUboCreate", + "summary": "Create business ultimate owners", + "description": "Adds new ultimate beneficial owners to the business profile.\n\nReturns the list of all ultimate beneficial owners associated with the business profile.\n\nAll the shareholders that have at least 25% ownership should be submitted via this API.\n\nNote that in some cases, we do not require the `ownershipPercentage`. In these cases, `null` should be passed as the value.\n", "tags": [ "profile" ], @@ -17461,12 +19143,18 @@ } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", + "required": [ + "name", + "dateOfBirth", + "countryOfResidenceIso3Code" + ], "properties": { "name": { "type": "string", @@ -17485,14 +19173,69 @@ }, "addressFirstLine": { "type": "string", - "description": "First line of address.", + "description": "First line of residential address. Required if the business profile's registered address is in the EU, EEA or US.", "example": "123 Fake St" }, "postCode": { "type": "string", - "description": "Address post code.", + "description": "Residential address post code. Required if the business profile's registered address is in the EU, EEA or US and the country in `countryOfResidenceIso3Code` uses post codes.", "example": "FK 12345" }, + "documentType": { + "type": "string", + "description": "Identification document type.", + "enum": [ + "PASSPORT", + "NATIONAL_ID", + "RESIDENCE_PERMIT", + "DRIVING_LICENSE", + "CPF" + ], + "example": "PASSPORT" + }, + "documentId": { + "type": "string", + "description": "Document number or identifier.", + "example": "AA299822313" + }, + "documentCountryIso3Code": { + "type": "string", + "description": "Document issuing country as an ISO 3166-1 alpha-3 code.", + "example": "usa" + }, + "nationality": { + "type": "string", + "description": "Nationality as an ISO 3166-1 alpha-2 or alpha-3 country code. Required if the business profile's registered address is in Singapore.", + "example": "usa" + }, + "email": { + "type": "string", + "description": "Owner email address.", + "minLength": 1, + "maxLength": 255, + "pattern": "^.+@.+$", + "example": "john.doe@example.com" + }, + "placeOfBirthCity": { + "type": "string", + "description": "City of birth. Required if the business profile's registered address is in the EU or EEA. Maximum 255 characters.", + "example": "London" + }, + "placeOfBirthCountryIso3Code": { + "type": "string", + "description": "Country of birth as an ISO 3166-1 alpha-3 code. Required if the business profile's registered address is in the EU or EEA.", + "example": "gbr" + }, + "city": { + "type": "string", + "description": "City of residential address. Required if `countryOfResidenceIso3Code` is `usa`, or if the business profile's registered address is in the EU, EEA or US. Maximum 255 characters.", + "example": "Phoenix" + }, + "state": { + "type": "string", + "description": "State or region of residential address. Required if `countryOfResidenceIso3Code` is `usa`, or if the business profile's registered address is in the EU, EEA or US and the country in `countryOfResidenceIso3Code` has states. Maximum 32 characters.", + "example": "AZ" + }, "ownershipPercentage": { "type": [ "integer", @@ -17515,6 +19258,15 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "123 Fake St", "postCode": "FK 12345", + "documentType": "PASSPORT", + "documentId": "AA299822313", + "documentCountryIso3Code": "usa", + "nationality": "usa", + "email": "john.doe@example.com", + "placeOfBirthCity": "London", + "placeOfBirthCountryIso3Code": "gbr", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 30 }, { @@ -17523,6 +19275,15 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "125 Fake St", "postCode": "FK 12545", + "documentType": "DRIVING_LICENSE", + "documentId": "DL12345", + "documentCountryIso3Code": "usa", + "nationality": "usa", + "email": "jane.doe@example.com", + "placeOfBirthCity": "London", + "placeOfBirthCountryIso3Code": "gbr", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 70 } ] @@ -17532,7 +19293,7 @@ } }, "responses": { - "200": { + "201": { "description": "List of all ultimate beneficial owners associated with the business profile.", "content": { "application/json": { @@ -17550,6 +19311,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "123 Fake St", "postCode": "FK 12345", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 30 }, { @@ -17559,6 +19322,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "125 Fake St", "postCode": "FK 12545", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 70 } ] @@ -17573,6 +19338,38 @@ } } }, + "400": { + "description": "Validation failed and no owners were saved. Errors are grouped per owner: `parameter` is the submitted owner, and each entry in its `errors` list carries one error code in `message`.\n\nRules are checked one at a time, so a response carries the errors of one rule only. Fix them and resubmit to see any errors from the next rule.\n\nResidential address error codes:\n- `AddressLineRequired` — `addressFirstLine` is missing and the business profile's registered address is in the EU, EEA or US\n- `CityRequired` — `city` is missing for an owner whose `countryOfResidenceIso3Code` is `usa`, or the business profile's registered address is in the EU, EEA or US\n- `PostCodeRequired` — `postCode` is missing, the business profile's registered address is in the EU, EEA or US, and the owner's country of residence uses post codes\n- `StateRequired` — `state` is missing for an owner whose `countryOfResidenceIso3Code` is `usa`, or the business profile's registered address is in the EU, EEA or US and the owner's country of residence has states\n- `CityTooLong` — `city` is longer than 255 characters\n- `StateInvalid` — `state` is longer than 32 characters\n", + "content": { + "application/json": { + "example": { + "code": "not.valid", + "message": "Cannot update shareholders for profile 12345 due to validation errors", + "errors": [ + { + "parameter": "{\"addressFirstLine\":\"123 Fake St\",\"city\":null,\"countryOfResidenceIso3Code\":\"usa\",\"dateOfBirth\":\"1982-05-20\",\"documentCountryIso3Code\":null,\"documentId\":null,\"documentType\":null,\"email\":null,\"name\":\"John Doe\",\"nationality\":null,\"ownershipPercentage\":30,\"placeOfBirthCity\":null,\"placeOfBirthCountryIso3Code\":null,\"postCode\":\"FK 12345\",\"state\":null}", + "errors": [ + { + "message": "CityRequired" + }, + { + "message": "StateRequired" + } + ] + } + ] + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, "429": { "$ref": "#/components/responses/429" } @@ -17624,6 +19421,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "123 Fake St", "postCode": "FK 12345", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 30 }, { @@ -17633,6 +19432,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "125 Fake St", "postCode": "FK 12545", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 70 } ] @@ -17655,7 +19456,7 @@ "put": { "operationId": "profileUboUpdate", "summary": "Update business ultimate owners", - "description": "Overrides ultimate beneficial owners in the business profile.\n\nReturns the list of all ultimate beneficial owners associated with the business profile.\n", + "description": "Replaces the entire collection of ultimate beneficial owners in the business profile.\n\nReturns the list of all ultimate beneficial owners associated with the business profile.\n\nIf the business profile's registered address is in the EU, EEA or US, each owner's residential address is required: `addressFirstLine` and `city`, plus `postCode` and `state` where the owner's country of residence (`countryOfResidenceIso3Code`) uses them. Because this request replaces the whole collection, owners that were created earlier without an address must be resent with one.\n", "tags": [ "profile" ], @@ -17680,12 +19481,18 @@ } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", + "required": [ + "name", + "dateOfBirth", + "countryOfResidenceIso3Code" + ], "properties": { "name": { "type": "string", @@ -17704,14 +19511,69 @@ }, "addressFirstLine": { "type": "string", - "description": "First line of address.", + "description": "First line of residential address. Required if the business profile's registered address is in the EU, EEA or US.", "example": "123 Fake St" }, "postCode": { "type": "string", - "description": "Address post code.", + "description": "Residential address post code. Required if the business profile's registered address is in the EU, EEA or US and the country in `countryOfResidenceIso3Code` uses post codes.", "example": "FK 12345" }, + "documentType": { + "type": "string", + "description": "Identification document type.", + "enum": [ + "PASSPORT", + "NATIONAL_ID", + "RESIDENCE_PERMIT", + "DRIVING_LICENSE", + "CPF" + ], + "example": "PASSPORT" + }, + "documentId": { + "type": "string", + "description": "Document number or identifier.", + "example": "AA299822313" + }, + "documentCountryIso3Code": { + "type": "string", + "description": "Document issuing country as an ISO 3166-1 alpha-3 code.", + "example": "usa" + }, + "nationality": { + "type": "string", + "description": "Nationality as an ISO 3166-1 alpha-2 or alpha-3 country code. Required if the business profile's registered address is in Singapore.", + "example": "usa" + }, + "email": { + "type": "string", + "description": "Owner email address.", + "minLength": 1, + "maxLength": 255, + "pattern": "^.+@.+$", + "example": "john.doe@example.com" + }, + "placeOfBirthCity": { + "type": "string", + "description": "City of birth. Required if the business profile's registered address is in the EU or EEA. Maximum 255 characters.", + "example": "London" + }, + "placeOfBirthCountryIso3Code": { + "type": "string", + "description": "Country of birth as an ISO 3166-1 alpha-3 code. Required if the business profile's registered address is in the EU or EEA.", + "example": "gbr" + }, + "city": { + "type": "string", + "description": "City of residential address. Required if `countryOfResidenceIso3Code` is `usa`, or if the business profile's registered address is in the EU, EEA or US. Maximum 255 characters.", + "example": "Phoenix" + }, + "state": { + "type": "string", + "description": "State or region of residential address. Required if `countryOfResidenceIso3Code` is `usa`, or if the business profile's registered address is in the EU, EEA or US and the country in `countryOfResidenceIso3Code` has states. Maximum 32 characters.", + "example": "AZ" + }, "ownershipPercentage": { "type": [ "integer", @@ -17734,6 +19596,15 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "123 Fake St", "postCode": "FK 12345", + "documentType": "PASSPORT", + "documentId": "AA299822313", + "documentCountryIso3Code": "usa", + "nationality": "usa", + "email": "john.doe@example.com", + "placeOfBirthCity": "London", + "placeOfBirthCountryIso3Code": "gbr", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 30 }, { @@ -17742,6 +19613,15 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "125 Fake St", "postCode": "FK 12545", + "documentType": "DRIVING_LICENSE", + "documentId": "DL12345", + "documentCountryIso3Code": "usa", + "nationality": "usa", + "email": "jane.doe@example.com", + "placeOfBirthCity": "London", + "placeOfBirthCountryIso3Code": "gbr", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 70 } ] @@ -17769,6 +19649,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "123 Fake St", "postCode": "FK 12345", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 30 }, { @@ -17778,6 +19660,8 @@ "countryOfResidenceIso3Code": "usa", "addressFirstLine": "125 Fake St", "postCode": "FK 12545", + "city": "Phoenix", + "state": "AZ", "ownershipPercentage": 70 } ] @@ -17792,6 +19676,38 @@ } } }, + "400": { + "description": "Validation failed and no owners were saved. Errors are grouped per owner: `parameter` is the submitted owner, and each entry in its `errors` list carries one error code in `message`.\n\nRules are checked one at a time, so a response carries the errors of one rule only. Fix them and resubmit to see any errors from the next rule.\n\nResidential address error codes:\n- `AddressLineRequired` — `addressFirstLine` is missing and the business profile's registered address is in the EU, EEA or US\n- `CityRequired` — `city` is missing for an owner whose `countryOfResidenceIso3Code` is `usa`, or the business profile's registered address is in the EU, EEA or US\n- `PostCodeRequired` — `postCode` is missing, the business profile's registered address is in the EU, EEA or US, and the owner's country of residence uses post codes\n- `StateRequired` — `state` is missing for an owner whose `countryOfResidenceIso3Code` is `usa`, or the business profile's registered address is in the EU, EEA or US and the owner's country of residence has states\n- `CityTooLong` — `city` is longer than 255 characters\n- `StateInvalid` — `state` is longer than 32 characters\n", + "content": { + "application/json": { + "example": { + "code": "not.valid", + "message": "Cannot update shareholders for profile 12345 due to validation errors", + "errors": [ + { + "parameter": "{\"addressFirstLine\":\"123 Fake St\",\"city\":null,\"countryOfResidenceIso3Code\":\"usa\",\"dateOfBirth\":\"1982-05-20\",\"documentCountryIso3Code\":null,\"documentId\":null,\"documentType\":null,\"email\":null,\"name\":\"John Doe\",\"nationality\":null,\"ownershipPercentage\":30,\"placeOfBirthCity\":null,\"placeOfBirthCountryIso3Code\":null,\"postCode\":\"FK 12345\",\"state\":null}", + "errors": [ + { + "message": "CityRequired" + }, + { + "message": "StateRequired" + } + ] + } + ] + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, "429": { "$ref": "#/components/responses/429" } @@ -18957,7 +20873,7 @@ "post": { "operationId": "quoteCreate", "summary": "Create a quote (authenticated)", - "description": "Create an authenticated quote when the quote is to be used for a transfer.\n\nAuthenticated quotes require a user access token to authenticate. You must also include the profile the quote should be associated with.\n\nIf you are funding the transfer from a multi-currency balance, set the `payIn` field to `BALANCE`. Otherwise this field defaults to `BANK_TRANSFER`, causing the fees to be inconsistent between quote and transfer.\n\n{% admonition type=\"info\" %}\nWhen `payOut` value is set to `SWIFT_OUR`, it enables payment protection for SWIFT recipients of global currency transfers. \n\nBy using this `payOut` method, you can guarantee to your customers that the fee will be charged to the sender, ensuring the recipient receives the full target amount.\n{% /admonition %}\n\n#### paymentOptions in the response\n\nA few things to note about the data in the `paymentOptions` object:\n\n- The `payOut` field is used to select the correct entry in the `paymentOptions` array so you know which fees to display to your customer. \n- Find the `paymentOption` that matches the `payOut` field shown at the top level of the quote resource and `payIn` based on the settlement model the bank is using. By default, this is `BANK_TRANSFER`, unless you are using a prefunded or bulk settlement model. \n- The `payOut` field changes based on the type of recipient you add to the quote in the **update quote request**. For example, to-USD `swift_code` or to-CAD `interac` have different fees.\n- Each `paymentOption` includes a `price` field, which gives a full breakdown of all the taxes, fees, and discounts. Refer to this structure for breakdowns and totals, rather than the `fee` structure as that only gives a summary and does not surface important specifics such as taxes.\n- When showing the price of a transfer always show the 'price.total.value.amount' of a payment option.\n- Each payment option is either enabled or disabled based on the `disabled` value.\n - Disabled payment options should be shown to the user in a disabled state in most cases. This ensures users are given the options they are familiar with regardless of their availability, as well as options that can be beneficial to their accounts.\n - The `option.disabledReason` contains both a `code` and a `message`. The message is the user-friendly text to surface to the user, if necessary.\n\n#### Transfer nature for BRL\n\n`transferNature` is a **required** field for transfers to or from BRL. It also impacts the fees charged on the quote, specifically the IOF.\n\nIOF is determined based on the transfer nature, sender information, and recipient information. The default IOF is included in a quote until all relevant information has been included.\n\n{% admonition type=\"info\" %}\nOmitting `transferNature` will not prevent the transfer from being created or even funded. However, when attempting to process the transfer, it will be blocked and the money will be refunded to the sender.\n{% /admonition %}\n\n#### Pricing configuration\n\nWhen creating or updating a quote, partners with [flexible partner pricing](/guides/product/send-money/quotes/pricing) enabled can override the pricing configuration dynamically.\n", + "description": "Create an authenticated quote when the quote is to be used for a transfer.\n\nAuthenticated quotes require a user access token to authenticate. You must also include the profile the quote should be associated with.\n\nIf you are funding the transfer from a multi-currency balance, set the `payIn` field to `BALANCE`. Otherwise this field defaults to `BANK_TRANSFER`, causing the fees to be inconsistent between quote and transfer.\n\n{% admonition type=\"info\" %}\nWhen `payOut` value is set to `SWIFT_OUR`, it enables payment protection for SWIFT recipients of global currency transfers. \n\nBy using this `payOut` method, you can guarantee to your customers that the fee will be charged to the sender, ensuring the recipient receives the full target amount.\n{% /admonition %}\n\n#### paymentOptions in the response\n\nA few things to note about the data in the `paymentOptions` object:\n\n- The `payOut` field is used to select the correct entry in the `paymentOptions` array so you know which fees to display to your customer. \n- Find the `paymentOption` that matches the `payOut` field shown at the top level of the quote resource and `payIn` based on the settlement model the bank is using. By default, this is `BANK_TRANSFER`, unless you are using a prefunded or bulk settlement model. \n- The `payOut` field changes based on the type of recipient you add to the quote in the **update quote request**. For example, to-USD `swift_code` or to-CAD `interac` have different fees.\n- Each `paymentOption` includes a `price` field, which gives a full breakdown of all the taxes, fees, and discounts. Refer to this structure for breakdowns and totals, rather than the `fee` structure as that only gives a summary and does not surface important specifics such as taxes.\n- When showing the price of a transfer always show the 'price.total.value.amount' of a payment option.\n- Each payment option is either enabled or disabled based on the `disabled` value.\n - Disabled payment options should be shown to the user in a disabled state in most cases. This ensures users are given the options they are familiar with regardless of their availability, as well as options that can be beneficial to their accounts.\n - The `option.disabledReason` contains both a `code` and a `message`. The message is the user-friendly text to surface to the user, if necessary.\n\n#### Transfer nature for BRL\n\n`transferNature` is a **required** field for transfers to or from BRL. It also impacts the fees charged on the quote, specifically the IOF.\n\nIOF is determined based on the transfer nature, sender information, and recipient information. The default IOF is included in a quote until all relevant information has been included.\n\n{% admonition type=\"info\" %}\nOmitting `transferNature` will not prevent the transfer from being created or even funded. However, when attempting to process the transfer, it will be blocked and the money will be refunded to the sender.\n{% /admonition %}\n\n#### Creating quote for batch payment transfers\n\nFor batch transfers that will be funded by payin session, you must include the `creationContext` field in the request body, or the payin session feature cannot be used to fund the transfer. The transfer will ultimately be blocked and money refunded to the sender.\n\n#### Pricing configuration\n\nWhen creating or updating a quote, partners with [flexible partner pricing](/guides/product/send-money/quotes/pricing) enabled can override the pricing configuration dynamically.\n", "tags": [ "quote" ], @@ -19041,194 +20957,17 @@ "description": "_Optional_. Preferred payin method. Use `BANK_TRANSFER` to return this method at the top of the response's results.", "example": null }, - "paymentMetadata": { + "creationContext": { "type": "object", - "description": "_Optional_. Used to pass additional metadata about the intended transfer.", + "description": "Used to pass additional metadata about the intended transfer.", "properties": { - "transferNature": { + "flow": { "type": "string", - "description": "_Optional_. Used to pass transfer nature for calculating proper tax amounts (IOF) for transfers to and from BRL. Accepted values are shown dynamically in transfer requirements.", - "example": "MOVING_MONEY_BETWEEN_OWN_ACCOUNTS" + "description": "_Optional_. Used to pass flow type for the creation flow on the quote. It should always be `MASS_PAY` for batch transfers funded via payin sessions.", + "example": "MASS_PAY" } } }, - "pricingConfiguration": { - "type": "object", - "description": "Required when configured for your client ID. Includes a `pricingConfiguration` to be used for pricing calculations with the quote.", - "properties": { - "fee": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Identifies the type of fee to be configured. Options include only `OVERRIDE`.", - "example": "OVERRIDE" - }, - "variable": { - "type": "number", - "description": "The selected variable percentage, in decimal format, that should be used in the `pricingConfiguration`.", - "example": 0.011 - }, - "fixed": { - "type": "number", - "description": "The selected fixed fee that should be used in the `pricingConfiguration`. Always considered in source currency.", - "example": 15.42 - } - } - } - } - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Returns a quote object.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/quote" - } - } - }, - "headers": { - "X-External-Correlation-Id": { - "$ref": "#/components/headers/X-External-Correlation-Id" - }, - "x-trace-id": { - "$ref": "#/components/headers/x-trace-id" - } - } - }, - "429": { - "$ref": "#/components/responses/429" - } - } - } - }, - "/profiles/{profileId}/quotes/{quoteId}": { - "get": { - "operationId": "quoteGet", - "summary": "Retrieve a quote by ID", - "description": "Get quote info by ID. If the quote has expired (not used to create a transfer within 30 minutes of quote creation), it will only be accessible for approximately 48 hours via this endpoint.\n", - "tags": [ - "quote" - ], - "security": [ - { - "UserToken": [] - } - ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Personal or business profile ID.", - "schema": { - "type": "integer", - "format": "int64" - }, - "example": 101 - }, - { - "name": "quoteId", - "in": "path", - "required": true, - "description": "The quote ID (GUID format).", - "schema": { - "type": "string", - "format": "uuid" - }, - "example": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf" - }, - { - "$ref": "#/components/parameters/X-External-Correlation-Id" - } - ], - "responses": { - "200": { - "description": "Returns a quote object.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/quote" - } - } - }, - "headers": { - "X-External-Correlation-Id": { - "$ref": "#/components/headers/X-External-Correlation-Id" - }, - "x-trace-id": { - "$ref": "#/components/headers/x-trace-id" - } - } - }, - "429": { - "$ref": "#/components/responses/429" - } - } - }, - "patch": { - "operationId": "quoteUpdate", - "summary": "Update a quote", - "description": "When generating a quote before a recipient, you must update the quote with the recipient `sourceAccount` value, as the recipient details may impact the quote properties like available payment options, price, and estimated delivery time. \nThis is because sending some currencies to certain destinations costs a different amount based on the payment networks used (for example, it's more expensive to send USD to a country outside the USA using international payment networks, or send CAD over the Interac network).\n\nWhen updating a quote, the `payOut` field may change to denote the payment option you should select when sending to the recipient. For example, sending USD to a `swift_code` recipient or CAD to an `interac` recipient changes `payOut` to `SWIFT` or `INTERAC` respectively. This field defaults to `BANK_TRANSFER` so it can be used in all cases to help select the correct `paymentOption` and hence show the correct pricing.\n\nIf pricing changes after updating a quote for a recipient, be sure to inform your customer before confirming the transfer.\n\nTo provide more transparency for fees charged for SWIFT recipients, consider setting the `payOut` field to `SWIFT_OUR`. This ensures the recipient receives the full target amount.\n\n#### Transfer Nature for BRL\n\n`transferNature` is a **required** field for transfers to or from BRL. It also impacts the fees charged on the quote, specifically the IOF.\n\nIOF is determined based on the transfer nature, sender information, and recipient information. The default IOF is included in a quote until all relevant information has been included.\n\n{% admonition type=\"info\" %}\nOmitting `transferNature` will not prevent the transfer from being created or even funded. However, when attempting to process the transfer, it will be blocked and the money will be refunded to the sender.\n{% /admonition %}\n", - "tags": [ - "quote" - ], - "security": [ - { - "UserToken": [] - } - ], - "parameters": [ - { - "name": "profileId", - "in": "path", - "required": true, - "description": "Personal or business profile ID.", - "schema": { - "type": "integer", - "format": "int64" - }, - "example": 101 - }, - { - "name": "quoteId", - "in": "path", - "required": true, - "description": "The quote ID (GUID format).", - "schema": { - "type": "string", - "format": "uuid" - }, - "example": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf" - }, - { - "$ref": "#/components/parameters/X-External-Correlation-Id" - } - ], - "requestBody": { - "required": true, - "content": { - "application/merge-patch+json": { - "schema": { - "type": "object", - "properties": { - "targetAccount": { - "type": "integer", - "format": "int64", - "description": "ID of transfer recipient, found in the create recipient response.", - "example": 12345 - }, - "payOut": { - "type": "string", - "description": "_Optional_. Preferred payout method. \n\nDefault value is `BANK_TRANSFER`. \n\nExamples of other accepted values include `BALANCE`, `SWIFT`, `SWIFT_OUR`, `ALIPAY`, and `INTERAC`.\n", - "example": "SWIFT_OUR" - }, "paymentMetadata": { "type": "object", "description": "_Optional_. Used to pass additional metadata about the intended transfer.", @@ -19242,7 +20981,7 @@ }, "pricingConfiguration": { "type": "object", - "description": "Required when configured for your client ID. Includes `pricingConfiguration` to be used for pricing calculations with the quote. If previously passed, the existing `pricingConfiguration` will remain and not be updated.", + "description": "Required when configured for your client ID. Includes a `pricingConfiguration` to be used for pricing calculations with the quote.", "properties": { "fee": { "type": "object", @@ -19259,7 +20998,195 @@ }, "fixed": { "type": "number", - "description": "The selected fixed fee, in source currency, that should be used in the `pricingConfiguration`.", + "description": "The selected fixed fee that should be used in the `pricingConfiguration`. Always considered in source currency.", + "example": 15.42 + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a quote object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/quote" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/profiles/{profileId}/quotes/{quoteId}": { + "get": { + "operationId": "quoteGet", + "summary": "Retrieve a quote by ID", + "description": "Get quote info by ID. If the quote has expired (not used to create a transfer within 30 minutes of quote creation), it will only be accessible for approximately 48 hours via this endpoint.\n", + "tags": [ + "quote" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Personal or business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + }, + "example": 101 + }, + { + "name": "quoteId", + "in": "path", + "required": true, + "description": "The quote ID (GUID format).", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf" + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "Returns a quote object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/quote" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + }, + "patch": { + "operationId": "quoteUpdate", + "summary": "Update a quote", + "description": "When generating a quote before a recipient, you must update the quote with the recipient `sourceAccount` value, as the recipient details may impact the quote properties like available payment options, price, and estimated delivery time. \nThis is because sending some currencies to certain destinations costs a different amount based on the payment networks used (for example, it's more expensive to send USD to a country outside the USA using international payment networks, or send CAD over the Interac network).\n\nWhen updating a quote, the `payOut` field may change to denote the payment option you should select when sending to the recipient. For example, sending USD to a `swift_code` recipient or CAD to an `interac` recipient changes `payOut` to `SWIFT` or `INTERAC` respectively. This field defaults to `BANK_TRANSFER` so it can be used in all cases to help select the correct `paymentOption` and hence show the correct pricing.\n\nIf pricing changes after updating a quote for a recipient, be sure to inform your customer before confirming the transfer.\n\nTo provide more transparency for fees charged for SWIFT recipients, consider setting the `payOut` field to `SWIFT_OUR`. This ensures the recipient receives the full target amount.\n\n#### Transfer Nature for BRL\n\n`transferNature` is a **required** field for transfers to or from BRL. It also impacts the fees charged on the quote, specifically the IOF.\n\nIOF is determined based on the transfer nature, sender information, and recipient information. The default IOF is included in a quote until all relevant information has been included.\n\n{% admonition type=\"info\" %}\nOmitting `transferNature` will not prevent the transfer from being created or even funded. However, when attempting to process the transfer, it will be blocked and the money will be refunded to the sender.\n{% /admonition %}\n", + "tags": [ + "quote" + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "profileId", + "in": "path", + "required": true, + "description": "Personal or business profile ID.", + "schema": { + "type": "integer", + "format": "int64" + }, + "example": 101 + }, + { + "name": "quoteId", + "in": "path", + "required": true, + "description": "The quote ID (GUID format).", + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf" + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/merge-patch+json": { + "schema": { + "type": "object", + "properties": { + "targetAccount": { + "type": "integer", + "format": "int64", + "description": "ID of transfer recipient, found in the create recipient response.", + "example": 12345 + }, + "payOut": { + "type": "string", + "description": "_Optional_. Preferred payout method. \n\nDefault value is `BANK_TRANSFER`. \n\nExamples of other accepted values include `BALANCE`, `SWIFT`, `SWIFT_OUR`, `ALIPAY`, and `INTERAC`.\n", + "example": "SWIFT_OUR" + }, + "paymentMetadata": { + "type": "object", + "description": "_Optional_. Used to pass additional metadata about the intended transfer.", + "properties": { + "transferNature": { + "type": "string", + "description": "_Optional_. Used to pass transfer nature for calculating proper tax amounts (IOF) for transfers to and from BRL. Accepted values are shown dynamically in transfer requirements.", + "example": "MOVING_MONEY_BETWEEN_OWN_ACCOUNTS" + } + } + }, + "pricingConfiguration": { + "type": "object", + "description": "Required when configured for your client ID. Includes `pricingConfiguration` to be used for pricing calculations with the quote. If previously passed, the existing `pricingConfiguration` will remain and not be updated.", + "properties": { + "fee": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Identifies the type of fee to be configured. Options include only `OVERRIDE`.", + "example": "OVERRIDE" + }, + "variable": { + "type": "number", + "description": "The selected variable percentage, in decimal format, that should be used in the `pricingConfiguration`.", + "example": 0.011 + }, + "fixed": { + "type": "number", + "description": "The selected fixed fee, in source currency, that should be used in the `pricingConfiguration`.", "example": 15.42 } } @@ -19731,7 +21658,7 @@ "post": { "operationId": "recipientCreate", "summary": "Create a recipient account", - "description": "Creates a recipient account. A **recipient** is the person or institution who is the ultimate beneficiary of your payment.\n\nRecipient data includes:\n- The personal details of an individual or basic information about a business.\n- Bank details like account numbers, routing numbers, and other region-specific information.\n- Address details like country and street address.\n\n{% admonition type=\"info\" %}\nCertain fields shown in the schema are conditionally required depending on `currency`, `type`, `legalType`, and `country`.\n\nThe reference uses a GBP example for illustration purposes.\nAs such, some fields are `null` in the provided examples. To determine which fields are required for a currency corridor, use the\n**[Retrieve recipient account requirements](/api-reference/recipient/recipientaccountrequirementsget)** endpoint.\n{% /admonition %}\n\n#### Bank account details\n\nThere are many variations of required bank account details, depending on recipient target currency. For example:\n\n- **GBP** requires sort code and account number.\n- **BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK** require IBAN.\n- **USD** requires routing number, account number, and account type\n- **INR** requires IFSC code and account number.\n\n#### Address details\n\nRecipient address data is required only if target currency is **USD, PHP, THB or TRY**, or if the source currency is **USD or AUD**.\n\nAddress fields can include:\n- Country\n- State (required for US, Canada, Brazil)\n- City\n- Address line\n- Zip code\n\n#### accountHolderName rules\n\n- **Personal recipients**: Full names must include more than one name, and both first and last name must have more than one character. Numbers are not allowed.\n- **Business recipients**: Business names must be in full and can be a single name. The full name cannot be just a single character, but can be made up of a set of single characters (for example, `\"A\"` is not permitted but `\"A 1\"` or `\"A1\"` is permitted).\n- Special characters `_()'*,.` are allowed for personal and business names. In general, the following regex describes permitted characters: `[0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\\s]`.\n\n\n#### Creating a refund recipient account\n\nSometimes we may need to refund the transfer back to the sender. The _refund recipient_ is the person or institution who we refund the transfer money back to. \n\nIt is not always mandatory to create a refund recipient. \n\n- If the funds are sent over a fast local payment network, we can usually infer the refund recipient from the bank transaction that funded the transfer. Please discuss this with your Wise implementation team if you are unsure if the refund recipient is needed.\n- If funds are sent using a slow domestic payment network, or you are using a bulk settlement model, we may require you to share the bank details of the source bank account.\n\nTo indicate a recipient account is a _refund recipient_, include the query parameter `refund=true` in the request.\n\nThen, use the account ID returned in the response as `sourceAccount` when [creating transfers](/guides/product/send-money/transfers).\n\n#### Creating an email recipient account\n\n{% admonition type=\"warning\" %}\nContact us before attempting to use email recipients as it is only recommended for certain use cases.\n{% /admonition %}\n\nIf you don't know recipient bank account details, you can set up an _email recipient_. Wise then collects bank details directly from the recipient.\n\nWise will email your recipient with a link to collect their bank account details securely. After the bank account details have been provided, Wise completes the transfer.\n\nConfirm this recipient type is available for your transaction by checking if the `\"type\": \"email\"` class is present in the response of the [retrieve recipient account requirements endpoint](/api-reference/recipient/recipientaccountrequirementsget).\n\nIf planning to send multiple currencies to a single recipient, you must create a separate email recipient resource for the beneficiary, for every currency you intend to send them.\n\nBe aware of the following:\n\n- Testing of transfers to email recipients in sandbox is not currently possible.\n- Recipients are required to enter bank details **every time a payment is made**.\n- We highly encourage you to provide the `profileId` if your recipient is receiving a payment from your business account, especially if you have multiple businesses or have multiple users administrating your business account.\n- Refer to our **[help page](https://wise.com/help/articles/2932105/can-i-send-money-to-someone-with-only-their-email-address)** for more details about how this works and any additional constraints not mentioned here.\n", + "description": "Creates a recipient account. A **recipient** is the person or institution who is the ultimate beneficiary of your payment.\n\nRecipient data includes:\n- The personal details of an individual or basic information about a business.\n- Bank details like account numbers, routing numbers, and other region-specific information.\n- Address details like country and street address.\n\n{% admonition type=\"info\" %}\nCertain fields shown in the schema are conditionally required depending on `currency`, `type`, `legalType`, and `country`.\n\nThe reference uses a GBP example for illustration purposes.\nAs such, some fields are `null` in the provided examples. To determine which fields are required for a currency corridor, use the\n**[Retrieve recipient account requirements](/api-reference/recipient/recipientaccountrequirementsget)** endpoint.\n{% /admonition %}\n\n#### Bank account details\n\nThere are many variations of required bank account details, depending on recipient target currency. For example:\n\n- **GBP** requires sort code and account number.\n- **BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK** require IBAN.\n- **USD** requires routing number, account number, and account type\n- **INR** requires IFSC code and account number.\n\n#### Address details\n\nRecipient address data is required if target currency is **USD, PHP, THB or TRY**, or if the source currency is **USD or AUD**. If target currency is **CHF**, city and country are always required, and the other address fields are optional unless the source currency is **USD or AUD**.\n\nAddress fields can include:\n- Country\n- State (required for US, Canada, Brazil)\n- City\n- Address line\n- Zip code\n\n#### accountHolderName rules\n\n- **Personal recipients**: Full names must include more than one name, and both first and last name must have more than one character. Numbers are not allowed.\n- **Business recipients**: Business names must be in full and can be a single name. The full name cannot be just a single character, but can be made up of a set of single characters (for example, `\"A\"` is not permitted but `\"A 1\"` or `\"A1\"` is permitted).\n- Special characters `_()'*,.` are allowed for personal and business names. In general, the following regex describes permitted characters: `[0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\\s]`.\n\n\n#### Creating a refund recipient account\n\nSometimes we may need to refund the transfer back to the sender. The _refund recipient_ is the person or institution who we refund the transfer money back to. \n\nIt is not always mandatory to create a refund recipient. \n\n- If the funds are sent over a fast local payment network, we can usually infer the refund recipient from the bank transaction that funded the transfer. Please discuss this with your Wise implementation team if you are unsure if the refund recipient is needed.\n- If funds are sent using a slow domestic payment network, or you are using a bulk settlement model, we may require you to share the bank details of the source bank account.\n\nTo indicate a recipient account is a _refund recipient_, include the query parameter `refund=true` in the request.\n\nThen, use the account ID returned in the response as `sourceAccount` when [creating transfers](/guides/product/send-money/transfers).\n\n#### Creating an email recipient account\n\n{% admonition type=\"warning\" %}\nContact us before attempting to use email recipients as it is only recommended for certain use cases.\n{% /admonition %}\n\nIf you don't know recipient bank account details, you can set up an _email recipient_. Wise then collects bank details directly from the recipient.\n\nWise will email your recipient with a link to collect their bank account details securely. After the bank account details have been provided, Wise completes the transfer.\n\nConfirm this recipient type is available for your transaction by checking if the `\"type\": \"email\"` class is present in the response of the [retrieve recipient account requirements endpoint](/api-reference/recipient/recipientaccountrequirementsget).\n\nIf planning to send multiple currencies to a single recipient, you must create a separate email recipient resource for the beneficiary, for every currency you intend to send them.\n\nBe aware of the following:\n\n- Testing of transfers to email recipients in sandbox is not currently possible.\n- Recipients are required to enter bank details **every time a payment is made**.\n- We highly encourage you to provide the `profileId` if your recipient is receiving a payment from your business account, especially if you have multiple businesses or have multiple users administrating your business account.\n- Refer to our **[help page](https://wise.com/help/articles/2932105/can-i-send-money-to-someone-with-only-their-email-address)** for more details about how this works and any additional constraints not mentioned here.\n", "tags": [ "recipient" ], @@ -20217,7 +22144,7 @@ "post": { "operationId": "recipientCompatibilityCheck", "summary": "Check account and quote compatibility", - "description": "Use this endpoint to check the compatibility of a recipient account with a quote before creating a transfer. This validation includes:\n\n- Re-validating the recipient account details.\n- Checking all required fields are present (for example, recipient address for USD transfers).\n- Verifying account details with the recipient's bank (for supported currencies).\n\nThis operation is optional, but useful to identify potential issues before transfer creation.\n\n{% admonition type=\"info\" %}\nThe confirmations object is only populated for currencies that support [recipient verification](/guides/product/send-money/recipient-verification). If absent, only standard validations apply.\n{% /admonition %}\n", + "description": "Use this endpoint to check the compatibility of a recipient account with a quote before creating a transfer. This validation includes:\n\n- Re-validating the recipient account details.\n- Checking all required fields are present (for example, recipient address for USD transfers).\n- Verifying account details with the recipient's bank (for supported currencies).\n\nThis operation is optional, but useful to identify potential issues before transfer creation.\n\n{% admonition type=\"info\" %}\nThe confirmations object is only populated for currencies that support [recipient verification](/guides/product/send-money/recipients/recipient-verification). If absent, only standard validations apply.\n{% /admonition %}\n", "tags": [ "recipient" ], @@ -20253,7 +22180,7 @@ ], "responses": { "200": { - "description": "Returns the compatibility result, including any verification outcomes. See the [Recipient verification guide](/guides/product/send-money/recipient-verification) for details about handling the `confirmations` object.", + "description": "Returns the compatibility result, including any verification outcomes. See the [Recipient verification guide](/guides/product/send-money/recipients/recipient-verification) for details about handling the `confirmations` object.", "content": { "application/json": { "schema": { @@ -20404,6 +22331,354 @@ } } }, + "/settlement/allocations": { + "post": { + "summary": "Create a settlement allocation request", + "description": "Creates a new settlement allocation request with a Settlement Allocation Request (SAR) file containing payment intents.\n\nThis endpoint requires **HMAC request signing** in addition to a bearer token. See [HMAC request signing](/guides/developer/auth-and-security/hmac) for the full algorithm, a verified test vector, and troubleshooting.\n", + "operationId": "createFundsAllocationRequest", + "tags": [ + "settlement" + ], + "security": [ + { + "ClientCredentialsToken": [], + "HmacSignature": [], + "HmacSignatureTimestamp": [] + } + ], + "parameters": [ + { + "name": "X-Signature", + "in": "header", + "required": true, + "description": "HMAC-SHA256 signature of the request content, hex-encoded in lowercase (64 characters).\nMust be sent together with `X-Signature-Timestamp`.\n", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "example": "1023c8e2a19cc42260968ab2dcf1698e8344a2939ac97f686d21aacb650273e2" + }, + { + "name": "X-Signature-Timestamp", + "in": "header", + "required": true, + "description": "Unix timestamp in **seconds** at which `X-Signature` was generated, as a decimal string.\n\nThis value is part of the signed canonical string, so it must exactly match the timestamp used to compute the signature. Requests more than 300 seconds from Wise server time are rejected in either direction.\n", + "schema": { + "type": "string", + "pattern": "^[0-9]+$" + }, + "example": "1700000000" + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "command", + "file" + ], + "properties": { + "command": { + "$ref": "#/components/schemas/settlement-allocation-request" + }, + "file": { + "type": "string", + "format": "binary", + "description": "Settlement Allocation Request (SAR) file containing payment intent details" + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Settlement allocation request accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/settlement-allocation-response" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "400": { + "description": "Invalid request. Signature failures are returned with this status and a `detail` field identifying the cause:\n\n| detail | Cause |\n| -------- | ----- |\n| `Missing required X-Signature header` | The `X-Signature` header was absent or blank. |\n| `Missing required X-Signature-Timestamp header` | The `X-Signature-Timestamp` header was absent or blank. |\n| `Invalid timestamp format` | `X-Signature-Timestamp` is not a whole number of seconds. |\n| `Signature timestamp expired` | The timestamp is more than 300 seconds from Wise server time, in either direction. |\n| `Invalid signature encoding` | `X-Signature` is not valid lowercase hexadecimal. |\n| `Invalid signature` | The signature did not match the request content. |\n", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid authentication", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "403": { + "description": "Forbidden - insufficient permissions", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/settlement/allocations/{allocationId}": { + "get": { + "description": "\n Retrieves the details of a settlement allocation by its ID.\n Optionally includes paginated payment intents associated with the allocation.\n ", + "summary": "Get a settlement allocation", + "operationId": "GetSettlementAllocation", + "parameters": [ + { + "name": "allocationId", + "in": "path", + "description": "Unique identifier of the settlement allocation.", + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", + "description": "Unique identifier of the settlement allocation.", + "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + }, + "required": true + }, + { + "name": "includePaymentIntents", + "in": "query", + "description": "Whether to include payment intents in the response.", + "schema": { + "type": "boolean", + "description": "Whether to include payment intents in the response.", + "example": true + } + }, + { + "name": "pageToken", + "in": "query", + "description": "Token for fetching the next page of results.", + "schema": { + "type": "string", + "description": "Token for fetching the next page of results.", + "example": "abc123" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Number of items per page.", + "schema": { + "type": "integer", + "maximum": 50, + "description": "Number of items per page.", + "format": "int32", + "example": 20 + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "Settlement allocation details retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetSettlementAllocationResponseContent" + }, + "examples": { + "settlement-allocation-details-response": { + "summary": "Settlement allocation details with payment intents", + "value": { + "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "expectedTotalAmount": 1000.5, + "currency": "EUR", + "state": "MATCHED", + "paymentReference": "PAY-123456", + "createdAt": "2026-07-10T10:30:16.000Z", + "updatedAt": "2026-07-10T11:00:41.000Z", + "paymentIntents": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "allocationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "partnerEntityId": "PARTNER-001", + "profileId": "12345678", + "recipientType": "SELLER", + "sourceAmount": 100, + "sourceCurrency": "EUR", + "targetAmount": 85, + "targetCurrency": "GBP", + "allocationType": "CREDIT", + "paymentReference": "REF-001", + "reason": "Invoice payment", + "state": "NEW", + "fundingSource": "WISE_COLLECTION_ACCOUNT", + "createdAt": "2026-07-10T10:35:41.147522", + "updatedAt": "2026-07-10T10:45:41.147522" + } + ], + "nextPageToken": "def456" + } + }, + "settlement-allocation-details-without-payment-intents": { + "summary": "Settlement allocation details without payment intents", + "value": { + "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "expectedTotalAmount": 1000.5, + "currency": "EUR", + "state": "MATCHED", + "paymentReference": "PAY-123456", + "createdAt": "2026-07-10T10:30:16.000Z", + "updatedAt": "2026-07-10T11:00:41.000Z" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "ClientCredentialsToken": [] + } + ], + "tags": [ + "settlement" + ] + } + }, + "/settlement/allocations/{allocationId}/payment-intents/{paymentIntentId}": { + "get": { + "description": "\n Retrieves the details of a specific payment intent within a settlement allocation.\n ", + "summary": "Get a payment intent", + "operationId": "GetPaymentIntent", + "parameters": [ + { + "name": "allocationId", + "in": "path", + "description": "Unique identifier of the settlement allocation.", + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", + "description": "Unique identifier of the settlement allocation.", + "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + }, + "required": true + }, + { + "name": "paymentIntentId", + "in": "path", + "description": "Unique identifier of the payment intent.", + "schema": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", + "description": "Unique identifier of the payment intent.", + "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "required": true + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "responses": { + "200": { + "description": "Payment intent details retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetPaymentIntentResponseContent" + }, + "examples": { + "payment-intent-response": { + "summary": "Payment intent details", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "allocationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "partnerEntityId": "PARTNER-001", + "profileId": "12345678", + "recipientType": "SELLER", + "sourceAmount": 100, + "sourceCurrency": "EUR", + "targetAmount": 85, + "targetCurrency": "GBP", + "allocationType": "CREDIT", + "paymentReference": "REF-001", + "reason": "Invoice payment", + "state": "NEW", + "fundingSource": "WISE_COLLECTION_ACCOUNT", + "createdAt": "2026-07-10T10:35:16.000Z", + "updatedAt": "2026-07-10T10:45:41.000Z" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "ClientCredentialsToken": [] + } + ], + "tags": [ + "settlement" + ] + } + }, "/simulation/transfers/{transferId}/{status}": { "get": { "operationId": "simulationTransferStateChange", @@ -20645,6 +22920,285 @@ } } }, + "/simulation/transfers/{transferId}/delivery-update": { + "post": { + "operationId": "simulationTransferDeliveryUpdate", + "summary": "Simulate a transfer delivery update", + "description": "Triggers a synthetic `transfers#delivery-update` webhook for a transfer accessible to the caller.\nCreate an eligible webhook subscription before calling this endpoint. See the\n[delivery update guide](/guides/product/send-money/tracking/delivery-statuses) for subscription setup and webhook handling.\n\n{% admonition type=\"info\" %}\n- Available in sandbox only, from API version `2026Q4`.\n- Does not change the transfer or payout state and does not require a particular transfer state.\n- A `200` response confirms acceptance for webhook processing, not delivery to your callback.\n Webhook delivery is asynchronous and requires a matching subscription.\n{% /admonition %}\n\nEach successful call generates a new observation. Repeating the request creates another\nobservation rather than replaying the previous one. Correlate the response with the webhook\nusing `observation_id` and `occurred_at`.\n", + "tags": [ + "simulation" + ], + "servers": [ + { + "url": "https://api.wise-sandbox.com/2027Q1", + "description": "Sandbox Environment" + } + ], + "security": [ + { + "UserToken": [] + } + ], + "parameters": [ + { + "name": "transferId", + "in": "path", + "required": true, + "description": "The ID of the transfer to simulate. The caller must have access to this transfer.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/delivery-update-request" + }, + "examples": { + "recipientProviderAccepted": { + "summary": "Simulate an intermediate delivery signal with an estimate", + "value": { + "scheme": "sepa_instant_credit_transfer", + "delivery_update_path": [ + "recipient_provider_accepted", + "scheme_settled" + ], + "delivery_update": "recipient_provider_accepted", + "estimated_delivery_at": "2026-10-01T10:00:05.000Z" + } + }, + "fundsAvailable": { + "summary": "Simulate funds available without a scheme or estimate", + "value": { + "delivery_update_path": [ + "funds_available" + ], + "delivery_update": "funds_available" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Observation accepted for asynchronous webhook processing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/delivery-update-response" + }, + "example": { + "observation_id": "550e8400-e29b-41d4-a716-446655440000", + "occurred_at": "2026-10-01T10:00:00.123Z" + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "400": { + "description": "Invalid request. Malformed input and domain validation return a single error; field validation can return an errors array.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/simulation-error" + }, + { + "$ref": "#/components/schemas/simulation-errors" + } + ] + }, + "examples": { + "unsupportedScheme": { + "summary": "Unsupported payment scheme", + "value": { + "arguments": [], + "code": "not.valid", + "message": "scheme is not supported" + } + }, + "updateOutsidePath": { + "summary": "Selected update is not in the path", + "value": { + "arguments": [], + "code": "not.valid", + "message": "delivery_update must be contained in delivery_update_path" + } + }, + "missingPath": { + "summary": "Missing or empty delivery update path", + "value": { + "errors": [ + { + "arguments": [], + "code": "not.valid", + "message": "delivery_update_path must be non-empty", + "path": "deliveryUpdatePath" + } + ] + } + }, + "malformedBody": { + "summary": "Request body cannot be read", + "value": { + "arguments": [], + "code": "message.not.readable" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "401": { + "description": "Authentication is missing or invalid.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "403": { + "description": "Access denied by the authentication or authorization policy.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "404": { + "description": "Transfer does not exist or is not accessible to the caller.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/simulation-errors" + }, + "example": { + "errors": [ + { + "arguments": [], + "code": "transfer_not_found", + "message": "Transfer not found" + } + ] + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + }, + "500": { + "description": "Internal error while processing the simulation.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/simulation-error" + }, + { + "$ref": "#/components/schemas/simulation-errors" + } + ] + }, + "examples": { + "submissionFailure": { + "value": { + "errors": [ + { + "arguments": [], + "code": "system_error", + "message": "Something went wrong on our side. If this does not resolve, please let us know at api@wise.com" + } + ] + } + }, + "unexpectedError": { + "value": { + "arguments": [], + "code": "unexpected.error" + } + } + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "503": { + "description": "Simulation temporarily unavailable because a required dependency or transfer routing is unavailable.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/simulation-errors" + }, + "example": { + "errors": [ + { + "arguments": [], + "code": "service_unavailable", + "message": "The simulation is temporarily unavailable. Please try again." + } + ] + } + } + }, + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + } + } + } + }, "/simulation/profiles/{profileId}/verifications": { "post": { "operationId": "simulationVerification", @@ -20864,6 +23418,62 @@ ] } }, + "/simulation/settlement/funds": { + "post": { + "description": "\n Simulates the receipt of funds for a specific settlement allocation.\n This endpoint allows you to simulate the receipt of funds associated with\n a given allocation, which can be useful for testing and validation purposes.\n Upon successful simulation, a 204 No Content response is returned.\n ", + "summary": "Simulate settlement allocation funds received", + "operationId": "SimulateSettlementAllocationsFunds", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SimulateSettlementAllocationsFundsRequestContent" + }, + "examples": { + "simulate-settlement-allocations-funds": { + "summary": "Simulate settlement allocation funds received", + "value": { + "amount": 1000.5, + "currency": "JPY", + "paymentReference": "BYOPSP_test-client_A1B2C3" + } + } + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "Funds received simulation completed successfully.", + "headers": { + "X-External-Correlation-Id": { + "$ref": "#/components/headers/X-External-Correlation-Id" + }, + "x-trace-id": { + "$ref": "#/components/headers/x-trace-id" + } + } + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "ClientCredentialsToken": [] + } + ], + "tags": [ + "simulation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-External-Correlation-Id" + } + ] + } + }, "/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/authorisation": { "post": { "operationId": "simulationCardTransactionAuthorisation", @@ -23749,7 +26359,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/validation-error-2" + "$ref": "#/components/schemas/validation-error-3" }, "example": { "type": "/errors/types/validation", @@ -23948,7 +26558,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/validation-error-2" + "$ref": "#/components/schemas/validation-error-3" }, "examples": { "missingField": { @@ -24051,7 +26661,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/validation-error-2" + "$ref": "#/components/schemas/validation-error-3" }, "examples": { "unsupportedType": { @@ -24223,7 +26833,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/validation-error-2" + "$ref": "#/components/schemas/validation-error-3" }, "example": { "type": "/errors/types/validation", @@ -25384,7 +27994,7 @@ "name": "status", "in": "query", "required": false, - "description": "Comma separated list of one or more status codes to filter transfers. See [Tracking Transfers](/guides/product/send-money/tracking-transfers) for complete list of statuses", + "description": "Comma separated list of one or more status codes to filter transfers.\nSee [Transfer statuses](/guides/product/send-money/tracking/transfer-statuses) for complete list of statuses.", "schema": { "type": "string" } @@ -28532,6 +31142,69 @@ } } }, + "allocations#state-changed": { + "post": { + "operationId": "eventAllocationsStateChanged", + "summary": "Allocations state changed", + "description": "Triggered when a settlement allocation request changes state.\n\n* Event type: `allocations#state-changed`\n* Profile level subscriptions: Not supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.resource.occurred_at` to reconcile the order.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "tags": [ + "webhook-event", + "settlement" + ], + "parameters": [ + { + "$ref": "#/components/parameters/x-signature-sha256" + }, + { + "$ref": "#/components/parameters/x-delivery-id" + }, + { + "$ref": "#/components/parameters/x-test-notification" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "title": "Allocations State Changed Event", + "required": [ + "schema_version" + ], + "discriminator": { + "propertyName": "schema_version", + "mapping": { + "4.0.0": "#/components/schemas/v4.0.0-7" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/v4.0.0-7" + } + ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "ok" + } + } + } + } + }, + "description": "Return any `2xx` status to acknowledge receipt of the event." + } + } + } + }, "cards#card-status-change": { "post": { "operationId": "eventCardsCardStatusChange", @@ -28560,13 +31233,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-7", + "4.0.0": "#/components/schemas/v4.0.0-8", "2.0.0": "#/components/schemas/v2.0.0-7" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-7" + "$ref": "#/components/schemas/v4.0.0-8" }, { "$ref": "#/components/schemas/v2.0.0-7" @@ -28624,13 +31297,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-8", + "4.0.0": "#/components/schemas/v4.0.0-9", "2.0.0": "#/components/schemas/v2.0.0-8" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-8" + "$ref": "#/components/schemas/v4.0.0-9" }, { "$ref": "#/components/schemas/v2.0.0-8" @@ -28688,13 +31361,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-9", + "4.0.0": "#/components/schemas/v4.0.0-10", "2.0.0": "#/components/schemas/v2.0.0-9" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-9" + "$ref": "#/components/schemas/v4.0.0-10" }, { "$ref": "#/components/schemas/v2.0.0-9" @@ -28752,13 +31425,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-10", + "4.0.0": "#/components/schemas/v4.0.0-11", "2.0.0": "#/components/schemas/v2.0.0-10" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-10" + "$ref": "#/components/schemas/v4.0.0-11" }, { "$ref": "#/components/schemas/v2.0.0-10" @@ -28816,14 +31489,14 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-11", + "4.0.0": "#/components/schemas/v4.0.0-12", "2.1.0": "#/components/schemas/v2.1.0", "2.0.0": "#/components/schemas/v2.0.0-11" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-11" + "$ref": "#/components/schemas/v4.0.0-12" }, { "$ref": "#/components/schemas/v2.1.0" @@ -28929,7 +31602,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/v4.0.0-12" + "$ref": "#/components/schemas/v4.0.0-13" }, "examples": { "breachOpened": { @@ -29030,13 +31703,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-13", + "4.0.0": "#/components/schemas/v4.0.0-14", "2.0.0": "#/components/schemas/v2.0.0-13" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-13" + "$ref": "#/components/schemas/v4.0.0-14" }, { "$ref": "#/components/schemas/v2.0.0-13" @@ -29094,13 +31767,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-14", + "4.0.0": "#/components/schemas/v4.0.0-15", "2.0.0": "#/components/schemas/v2.0.0-14" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-14" + "$ref": "#/components/schemas/v4.0.0-15" }, { "$ref": "#/components/schemas/v2.0.0-14" @@ -29158,13 +31831,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-15", + "4.0.0": "#/components/schemas/v4.0.0-16", "2.0.0": "#/components/schemas/v2.0.0-15" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-15" + "$ref": "#/components/schemas/v4.0.0-16" }, { "$ref": "#/components/schemas/v2.0.0-15" @@ -29222,13 +31895,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-16", + "4.0.0": "#/components/schemas/v4.0.0-17", "2.0.0": "#/components/schemas/v2.0.0-16" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-16" + "$ref": "#/components/schemas/v4.0.0-17" }, { "$ref": "#/components/schemas/v2.0.0-16" @@ -29287,7 +31960,7 @@ "propertyName": "schema_version", "mapping": { "5.0.0": "#/components/schemas/v5.0.0-2", - "4.0.0": "#/components/schemas/v4.0.0-17", + "4.0.0": "#/components/schemas/v4.0.0-18", "2.0.0": "#/components/schemas/v2.0.0-17" } }, @@ -29296,7 +31969,7 @@ "$ref": "#/components/schemas/v5.0.0-2" }, { - "$ref": "#/components/schemas/v4.0.0-17" + "$ref": "#/components/schemas/v4.0.0-18" }, { "$ref": "#/components/schemas/v2.0.0-17" @@ -29328,9 +32001,10 @@ }, "users#state-change": { "post": { + "deprecated": true, "operationId": "eventUsersStateChange", "summary": "User state change", - "description": "Triggered every time a user's state is updated.\n\n* Event type: `users#state-change`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\n**User state change transitions**:\n\nPossible `previous_state` and `current_state` values:\n- `ACTIVE`: The user's account is active.\n- `WITHDRAW_ONLY`: The user has 90 calendar days to remove their money from their balance before we fully close their account. This can be done through sending from their balance to themselves and others or spending with their card. The user still cannot order new cards, convert between balances, open and close balances, and download balance statements. After 90 calendar days, the account moves into a `DEACTIVATED` state.\n- `DEACTIVATED`: The user's account is deactivated and they cannot perform any actions on their account. The end-user tokens are revoked and you will receive a `401 Unauthorized` response for API calls.\n\n{% img src=\"/images/diagrams/user-deactivation-flow.png\" alt=\"User state change flow diagram\" /%}\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "description": "Triggered every time a user's state is updated.\n\nThis webhook is deprecated and will be removed by end 2026. If you are currently subscribed to it, please migrate to the new [profiles#state-change](/api-reference/webhook-event/eventprofilesstatechange) webhook instead.\n\n* Event type: `users#state-change`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\n**User state change transitions**:\n\nPossible `previous_state` and `current_state` values:\n- `ACTIVE`: The user's account is active.\n- `WITHDRAW_ONLY`: The user has 90 calendar days to remove their money from their balance before we fully close their account. This can be done through sending from their balance to themselves and others or spending with their card. The user still cannot order new cards, convert between balances, open and close balances, and download balance statements. After 90 calendar days, the account moves into a `DEACTIVATED` state.\n- `DEACTIVATED`: The user's account is deactivated and they cannot perform any actions on their account. The end-user tokens are revoked and you will receive a `401 Unauthorized` response for API calls.\n\n{% img src=\"/images/diagrams/user-deactivation-flow.png\" alt=\"User state change flow diagram\" /%}\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", "tags": [ "webhook-event", "user" @@ -29354,13 +32028,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-18", + "4.0.0": "#/components/schemas/v4.0.0-19", "2.0.0": "#/components/schemas/v2.0.0-18" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-18" + "$ref": "#/components/schemas/v4.0.0-19" }, { "$ref": "#/components/schemas/v2.0.0-18" @@ -29418,7 +32092,7 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-19", + "4.0.0": "#/components/schemas/v4.0.0-20", "3.0.0": "#/components/schemas/v3.0.0", "2.2.0": "#/components/schemas/v2.2.0", "2.1.0": "#/components/schemas/v2.1.0-2" @@ -29426,7 +32100,7 @@ }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-19" + "$ref": "#/components/schemas/v4.0.0-20" }, { "$ref": "#/components/schemas/v3.0.0" @@ -29490,13 +32164,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-20", + "4.0.0": "#/components/schemas/v4.0.0-21", "2.0.0": "#/components/schemas/v2.0.0-19" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-20" + "$ref": "#/components/schemas/v4.0.0-21" }, { "$ref": "#/components/schemas/v2.0.0-19" @@ -29554,13 +32228,13 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-21", + "4.0.0": "#/components/schemas/v4.0.0-22", "2.0.0": "#/components/schemas/v2.0.0-20" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-21" + "$ref": "#/components/schemas/v4.0.0-22" }, { "$ref": "#/components/schemas/v2.0.0-20" @@ -29619,7 +32293,7 @@ "propertyName": "schema_version", "mapping": { "5.0.0": "#/components/schemas/v5.0.0-3", - "4.0.0": "#/components/schemas/v4.0.0-22", + "4.0.0": "#/components/schemas/v4.0.0-23", "2.0.0": "#/components/schemas/v2.0.0-21" } }, @@ -29627,86 +32301,11 @@ { "$ref": "#/components/schemas/v5.0.0-3" }, - { - "$ref": "#/components/schemas/v4.0.0-22" - }, - { - "$ref": "#/components/schemas/v2.0.0-21" - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "string", - "example": "ok" - } - } - } - } - }, - "description": "Return any `2xx` status to acknowledge receipt of the event." - } - } - } - }, - "swift-in#credit": { - "post": { - "operationId": "eventSwiftInCredit", - "summary": "Swift receive credit", - "description": "Triggered every time a SWIFT message is received and a credit is deposited into a balance account.\n\nIf you also subscribe to `balances#credit` or `transfers#state-change` on the same profile or application, you may experience some duplication of webhook events. You should make allowances for this to handle it in your implementation.\n\n* Event type: `swift-in#credit`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", - "tags": [ - "webhook-event" - ], - "parameters": [ - { - "$ref": "#/components/parameters/x-signature-sha256" - }, - { - "$ref": "#/components/parameters/x-delivery-id" - }, - { - "$ref": "#/components/parameters/x-test-notification" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Swift In Credit Event", - "discriminator": { - "propertyName": "schema_version", - "mapping": { - "4.3.0": "#/components/schemas/v4.3.0", - "4.2.0": "#/components/schemas/v4.2.0", - "4.1.0": "#/components/schemas/v4.1.0", - "4.0.0": "#/components/schemas/v4.0.0-23", - "3.0.0": "#/components/schemas/v3.0.0-2" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/v4.3.0" - }, - { - "$ref": "#/components/schemas/v4.2.0" - }, - { - "$ref": "#/components/schemas/v4.1.0" - }, { "$ref": "#/components/schemas/v4.0.0-23" }, { - "$ref": "#/components/schemas/v3.0.0-2" + "$ref": "#/components/schemas/v2.0.0-21" } ] } @@ -29733,13 +32332,14 @@ } } }, - "swift#message-received": { + "settlement#funds-received": { "post": { - "operationId": "eventSwiftMessageReceived", - "summary": "Swift message received", - "description": "Triggered when a SWIFT message (e.g., [pacs.008](/guides/product/receive-money/incoming-transfer-notifications#example-pacs008-message-content)) is received and processed by Wise on behalf of a partner.\n\n* Event type: `swift#message-received`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "operationId": "eventSettlementFundsReceived", + "summary": "Settlement funds received", + "description": "Triggered when funds are received for settlement.\n\n* Event type: `settlement#funds-received`\n* Profile level subscriptions: Not supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.resource.occurred_at` to reconcile the order.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", "tags": [ - "webhook-event" + "webhook-event", + "settlement" ], "parameters": [ { @@ -29756,7 +32356,10 @@ "content": { "application/json": { "schema": { - "title": "Swift Message Received Event", + "title": "Settlement Funds Received Event", + "required": [ + "schema_version" + ], "discriminator": { "propertyName": "schema_version", "mapping": { @@ -29792,14 +32395,13 @@ } } }, - "transaction-disputes#update": { + "swift-in#credit": { "post": { - "operationId": "eventTransactionDisputesUpdate", - "summary": "Transaction disputes update", - "description": "Triggered every time a transaction dispute is submitted or updated.\n\nYou may receive update events even when there are no apparent changes in the dispute `status` or `subStatus`, as certain underlying modifications might not directly impact these visible indicators.\n\n* Event type: `transaction-disputes#update`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "operationId": "eventSwiftInCredit", + "summary": "Swift receive credit", + "description": "Triggered every time a Swift message is received and a credit is deposited into a balance account.\nIf you also subscribe to the `balances#credit` event type on the same profile or application, you may experience some duplication of webhook events.\n\n* Event type: `swift-in#credit`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\n{% admonition type=\"warning\" %}\nThe `swift-in#credit` event type only covers transfers received via a connected BIC. It is not triggered by local scheme payments (SEPA, Faster Payments, ACH).\nIntegrations relying solely on this event will not be notified of pay-ins to Local Account Details. We recommend subscribing to the `incoming-transfer#credited` event type to receive a unified signal across all payment rails.\n{% /admonition %}\n\nEvents may not be delivered in the order they occurred. Use the `data.occurred_at` field to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", "tags": [ - "webhook-event", - "disputes" + "webhook-event" ], "parameters": [ { @@ -29816,20 +32418,32 @@ "content": { "application/json": { "schema": { - "title": "Transaction Disputes Update Event", + "title": "Swift In Credit Event", "discriminator": { "propertyName": "schema_version", "mapping": { + "4.3.0": "#/components/schemas/v4.3.0", + "4.2.0": "#/components/schemas/v4.2.0", + "4.1.0": "#/components/schemas/v4.1.0", "4.0.0": "#/components/schemas/v4.0.0-25", - "2.0.0": "#/components/schemas/v2.0.0-22" + "3.0.0": "#/components/schemas/v3.0.0-2" } }, "oneOf": [ + { + "$ref": "#/components/schemas/v4.3.0" + }, + { + "$ref": "#/components/schemas/v4.2.0" + }, + { + "$ref": "#/components/schemas/v4.1.0" + }, { "$ref": "#/components/schemas/v4.0.0-25" }, { - "$ref": "#/components/schemas/v2.0.0-22" + "$ref": "#/components/schemas/v3.0.0-2" } ] } @@ -29856,14 +32470,13 @@ } } }, - "bulk-settlement#payment-received": { + "swift#message-received": { "post": { - "operationId": "eventBulkSettlementPaymentReceived", - "summary": "Bulk settlement payment received", - "description": "Triggered when a bulk settlement fund is received. Once there is a match, meaning the amount for this settlement journal is fully settled, the `amount_matched` is set to `true`. If it is not matched, check the difference between `source_amount` and `target_amount` to determine how much more needs to be paid.\n\nThis event can also be triggered when our operations team reallocates funds between settlements. Therefore, the `received_amount` in version 2.0.0 of the webhook is inaccurate. Please use the latest version, 4.0.0. Version 2.0.0 is deprecated.\n\n* Event type: `bulk-settlement#payment-received`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "operationId": "eventSwiftMessageReceived", + "summary": "Swift message received", + "description": "Triggered when a SWIFT message (e.g., [pacs.008](/guides/product/receive-money/incoming-transfer-notifications#example-pacs008-message-content)) is received and processed by Wise on behalf of a partner.\n\n* Event type: `swift#message-received`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", "tags": [ - "webhook-event", - "bulk-settlement" + "webhook-event" ], "parameters": [ { @@ -29880,24 +32493,16 @@ "content": { "application/json": { "schema": { - "title": "Bulk Settlement Payment Received Event", + "title": "Swift Message Received Event", "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-26", - "3.0.0": "#/components/schemas/v3.0.0-3", - "2.0.0": "#/components/schemas/v2.0.0-23" + "4.0.0": "#/components/schemas/v4.0.0-26" } }, "oneOf": [ { "$ref": "#/components/schemas/v4.0.0-26" - }, - { - "$ref": "#/components/schemas/v3.0.0-3" - }, - { - "$ref": "#/components/schemas/v2.0.0-23" } ] } @@ -29924,14 +32529,14 @@ } } }, - "incoming-transfer#credited": { + "transaction-disputes#update": { "post": { - "operationId": "eventIncomingTransferCredited", - "summary": "Incoming transfer credited", - "description": "Triggered when an incoming transfer is credited to a Wise balance.\n\nThis is a thin event, containing just the `incoming_transfer_id`. Fetch the full resource via the \n[incoming transfer endpoint](/api-reference/incoming-transfer).\n\n* Event type: `incoming-transfer#credited`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "operationId": "eventTransactionDisputesUpdate", + "summary": "Transaction disputes update", + "description": "Triggered every time a transaction dispute is submitted or updated.\n\nYou may receive update events even when there are no apparent changes in the dispute `status` or `subStatus`, as certain underlying modifications might not directly impact these visible indicators.\n\n* Event type: `transaction-disputes#update`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", "tags": [ "webhook-event", - "incoming-transfer" + "disputes" ], "parameters": [ { @@ -29948,16 +32553,148 @@ "content": { "application/json": { "schema": { - "title": "Incoming Transfer Credited Event", + "title": "Transaction Disputes Update Event", "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-27" + "4.0.0": "#/components/schemas/v4.0.0-27", + "2.0.0": "#/components/schemas/v2.0.0-22" } }, "oneOf": [ { "$ref": "#/components/schemas/v4.0.0-27" + }, + { + "$ref": "#/components/schemas/v2.0.0-22" + } + ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "ok" + } + } + } + } + }, + "description": "Return any `2xx` status to acknowledge receipt of the event." + } + } + } + }, + "bulk-settlement#payment-received": { + "post": { + "operationId": "eventBulkSettlementPaymentReceived", + "summary": "Bulk settlement payment received", + "description": "Triggered when a bulk settlement fund is received. Once there is a match, meaning the amount for this settlement journal is fully settled, the `amount_matched` is set to `true`. If it is not matched, check the difference between `source_amount` and `target_amount` to determine how much more needs to be paid.\n\nThis event can also be triggered when our operations team reallocates funds between settlements. Therefore, the `received_amount` in version 2.0.0 of the webhook is inaccurate. Please use the latest version, 4.0.0. Version 2.0.0 is deprecated.\n\n* Event type: `bulk-settlement#payment-received`\n* Profile level subscriptions: Not Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "tags": [ + "webhook-event", + "bulk-settlement" + ], + "parameters": [ + { + "$ref": "#/components/parameters/x-signature-sha256" + }, + { + "$ref": "#/components/parameters/x-delivery-id" + }, + { + "$ref": "#/components/parameters/x-test-notification" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "title": "Bulk Settlement Payment Received Event", + "discriminator": { + "propertyName": "schema_version", + "mapping": { + "4.0.0": "#/components/schemas/v4.0.0-28", + "3.0.0": "#/components/schemas/v3.0.0-3", + "2.0.0": "#/components/schemas/v2.0.0-23" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/v4.0.0-28" + }, + { + "$ref": "#/components/schemas/v3.0.0-3" + }, + { + "$ref": "#/components/schemas/v2.0.0-23" + } + ] + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "ok" + } + } + } + } + }, + "description": "Return any `2xx` status to acknowledge receipt of the event." + } + } + } + }, + "incoming-transfer#credited": { + "post": { + "operationId": "eventIncomingTransferCredited", + "summary": "Incoming transfer credited", + "description": "Triggered when an incoming transfer is credited to a Wise balance.\n\nThis is a thin event that provides the `incoming_transfer_id`. Use this ID to [fetch the full incoming transfer resource](/api-reference/incoming-transfer).\n\n* Event type: `incoming-transfer#credited`\n* Profile level subscriptions: Supported\n* Application level subscriptions: Supported\n\nEvents may not be delivered in the order they occurred. Use the `data.occurred_at` field to reconcile the order.\nSee the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.\n\nSee the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.\n", + "tags": [ + "webhook-event", + "incoming-transfer" + ], + "parameters": [ + { + "$ref": "#/components/parameters/x-signature-sha256" + }, + { + "$ref": "#/components/parameters/x-delivery-id" + }, + { + "$ref": "#/components/parameters/x-test-notification" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "title": "Incoming Transfer Credited Event", + "discriminator": { + "propertyName": "schema_version", + "mapping": { + "4.0.0": "#/components/schemas/v4.0.0-29" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/v4.0.0-29" } ] } @@ -30012,12 +32749,12 @@ "discriminator": { "propertyName": "schema_version", "mapping": { - "4.0.0": "#/components/schemas/v4.0.0-28" + "4.0.0": "#/components/schemas/v4.0.0-30" } }, "oneOf": [ { - "$ref": "#/components/schemas/v4.0.0-28" + "$ref": "#/components/schemas/v4.0.0-30" } ] } @@ -30147,18 +32884,46 @@ } } }, - "schemas": { - "CurrencyCode": { - "type": "string", - "description": "ISO 4217 currency code", - "pattern": "^[A-Z]{3}$", - "example": "USD" + "securitySchemes": { + "UserToken": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "User Access Token for making API calls on behalf of a Wise user.\n\nCan be obtained via two OAuth 2.0 flows:\n- **registration_code grant**: For partners creating users via API\n- **authorization_code grant**: For partners using Wise's authorization page\n\nAccess tokens are valid for 12 hours and can be refreshed using a refresh token.\n" }, - "Bic": { - "description": "Business Identifier Code, also known as Swift Code.", - "type": "string", - "pattern": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$" + "PersonalToken": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "Personal API Token for individual personal or small business users.\nGenerated from Wise.com > Settings > Connect and manage apps > API tokens.\nHas limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).\n" + }, + "ClientCredentialsToken": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "Application-level token for partner operations that don't require a specific user context, such as bulk settlement and card spend controls.\n\nObtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.\n\nValid for 12 hours. No refresh token — fetch a new token when expired.\n\nSee [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.\n" }, + "BasicAuth": { + "type": "http", + "scheme": "basic", + "x-defaultUsername": "", + "x-defaultPassword": "", + "description": "Basic Authentication using your Client ID and Client Secret as the username and password.\n\nClient credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.\n" + }, + "HmacSignature": { + "type": "apiKey", + "in": "header", + "name": "X-Signature", + "description": "HMAC-SHA256 signature proving the request body has not been tampered with, hex-encoded in lowercase.\n\nCheck the API reference for the endpoint you are calling to see whether it requires HMAC signing. Where it applies, it is used **in addition to** a bearer token, not instead of one.\n\nThe signature is computed over a canonical string built from the request timestamp and a SHA-256 hash of each signed part:\n\n```\n{timestamp}.{sha256_hex(json_part)}.{sha256_hex(file_part)}\n```\n\nMust be sent together with the `X-Signature-Timestamp` header. Signatures are accepted within 300 seconds of Wise server time.\n\nSee [HMAC request signing](/guides/developer/auth-and-security/hmac) for the full algorithm, a verified test vector, and troubleshooting.\n" + }, + "HmacSignatureTimestamp": { + "type": "apiKey", + "in": "header", + "name": "X-Signature-Timestamp", + "description": "The Unix timestamp in **seconds** at which the `X-Signature` value was generated, as a decimal string.\n\nThis value is part of the signed canonical string, so it must match the timestamp used when computing the signature exactly. Requests more than 300 seconds away from Wise server time are rejected in either direction, which limits how long a captured request can be replayed.\n\nSee [HMAC request signing](/guides/developer/auth-and-security/hmac) for details.\n" + } + }, + "schemas": { "ChallengeResultRequest": { "type": "object", "required": [ @@ -30865,216 +33630,279 @@ } } }, - "BankAccountDetails": { + "AccountDetailsState": { + "type": "string", + "description": "Current state of the account details.", + "enum": [ + "ACTIVE", + "INACTIVE" + ] + }, + "Iso20022Address": { "type": "object", - "title": "Bank Account Details", - "x-tags": [ - "bank-account-details" - ], - "description": "Bank account details for receiving money into a Wise Multi-Currency Account.", + "description": "An ISO 20022 structured address with optional free-form address lines.", "properties": { - "id": { - "type": [ - "integer", - "null" - ], - "format": "int64", - "description": "Bank account details ID. Returns `null` for preview account details that have not yet been issued.", - "example": 14000001 + "streetName": { + "type": "string", + "description": "Street name", + "example": "Clifton Street, London" }, - "currency": { - "type": "object", - "description": "Currency information for the bank account details.", - "properties": { - "code": { - "type": "string", - "description": "Currency code (ISO 4217 Alphabetic Code).", - "example": "EUR" - }, - "name": { - "type": "string", - "description": "Currency name.", - "example": "Euro" - } - } + "buildingNumber": { + "type": "string", + "description": "Building number", + "example": "65" }, - "title": { + "townName": { "type": "string", - "description": "Account title.", - "example": "Your EUR account details" + "description": "City or town", + "example": "London" }, - "subtitle": { + "postCode": { "type": "string", - "description": "Account subtitle.", - "example": "IBAN, SWIFT/BIC" + "description": "Postal or ZIP code", + "example": "EC2A 4JE" }, - "status": { + "countrySubDivision": { "type": "string", - "description": "Account details status:\n- `AVAILABLE`: Account details do not exist for the user but may be created\n- `ACTIVE`: Account details are ready to be used by this user\n", - "enum": [ - "AVAILABLE", - "ACTIVE" - ], - "example": "ACTIVE" + "description": "State, province, or region", + "example": "Greater London" }, - "deprecated": { - "type": "boolean", - "description": "When `true`, Wise has issued new account details for the same currency. Users should not use the deprecated account but may still have external references to it.", - "example": false + "country": { + "type": "string", + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z]{2}$", + "description": "ISO 3166-1 alpha-2 country code", + "example": "GB" }, - "receiveOptions": { + "addressLines": { "type": "array", - "description": "Available receive options for the given currency:\n- `LOCAL`: Local bank details to receive money in the account currency\n- `INTERNATIONAL`: SWIFT bank details to receive money internationally\n", "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Receive option type.", - "enum": [ - "LOCAL", - "INTERNATIONAL" - ], - "example": "LOCAL" - }, - "title": { - "type": "string", - "description": "Display title for this receive option.", - "example": "Local" - }, - "description": { - "type": [ - "object", - "null" - ], - "description": "Description for this receive option.", - "properties": { - "title": { - "type": "string", - "description": "Description title.", - "example": "Your EUR account details" - }, - "body": { - "type": "string", - "description": "Description body text.", - "example": "Receive from a bank in the Eurozone" - }, - "cta": { - "type": [ - "object", - "null" - ], - "description": "Call-to-action details.", - "properties": { - "label": { - "type": "string", - "description": "CTA label.", - "example": "IBAN" - }, - "content": { - "type": "string", - "description": "CTA content.", - "example": "BE12 3456 7890 1234" - } - } - } - } - }, - "details": { - "type": "array", - "description": "Account details to display to users. This array varies by currency.\nFor example, EUR returns `ACCOUNT_HOLDER`, `SWIFT_CODE`, `IBAN` and `BANK_NAME_AND_ADDRESS`.\n", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Account detail type.", - "example": "IBAN" - }, - "title": { - "type": "string", - "description": "Label to display in the UI.", - "example": "IBAN" - }, - "body": { - "type": "string", - "description": "Value to display in the UI.", - "example": "BE12 3456 7890 1234" - }, - "description": { - "type": [ - "object", - "null" - ], - "description": "Tooltip/popup hint content when present.", - "properties": { - "title": { - "type": "string", - "description": "Description title.", - "example": "What is an IBAN?" - }, - "body": { - "type": "string", - "description": "Description body (may contain HTML).", - "example": "

IBAN stands for International Bank Account Number.

" - }, - "cta": { - "type": [ - "object", - "null" - ], - "description": "Call-to-action details.", - "properties": { - "label": { - "type": "string", - "description": "CTA label.", - "example": "IBAN" - }, - "content": { - "type": "string", - "description": "CTA content.", - "example": "BE12 3456 7890 1234" - } - } - } - } - }, - "hidden": { - "type": "boolean", - "description": "Whether the field should be hidden in the UI.", - "example": false - } - } - } - } + "type": "string" + }, + "maxItems": 2, + "description": "Address lines. May be empty; up to two lines can be populated alongside structured fields.", + "example": [ + "1st Floor, Worship Square", + "EV2A 4JE" + ] + } + }, + "required": [ + "addressLines", + "country", + "townName" + ] + }, + "BeAccountIdentification": { + "type": "object", + "properties": { + "bic": { + "type": "string", + "maxLength": 11, + "minLength": 8, + "description": "SWIFT BIC (Business Identifier Code) of the financial institution.", + "example": "TRWIBEB1" + }, + "iban": { + "type": "string", + "maxLength": 34, + "description": "International Bank Account Number.", + "example": "BE71096123456769" + }, + "institutionName": { + "type": "string", + "maxLength": 140, + "description": "Name of the financial institution.", + "example": "Wise" + }, + "institutionAddress": { + "$ref": "#/components/schemas/Iso20022Address", + "description": "Postal address of the financial institution." + } + }, + "required": [ + "iban", + "institutionAddress" + ] + }, + "GbAccountIdentification": { + "type": "object", + "properties": { + "bic": { + "type": "string", + "maxLength": 11, + "minLength": 8, + "description": "SWIFT BIC (Business Identifier Code) of the financial institution.", + "example": "TRWIGB2L" + }, + "iban": { + "type": "string", + "maxLength": 34, + "description": "International Bank Account Number.", + "example": "GB29NWBK60161331926819" + }, + "sortCode": { + "type": "string", + "maxLength": 6, + "minLength": 6, + "description": "UK sort code identifying the bank and branch.", + "example": "230801" + }, + "accountNumber": { + "type": "string", + "maxLength": 34, + "description": "Domestic account number.", + "example": "12345678" + }, + "institutionName": { + "type": "string", + "maxLength": 140, + "description": "Name of the financial institution.", + "example": "Wise Payments Ltd" + }, + "institutionAddress": { + "$ref": "#/components/schemas/Iso20022Address", + "description": "Postal address of the financial institution." + } + }, + "required": [ + "accountNumber", + "iban", + "institutionAddress", + "sortCode" + ] + }, + "UsAccountIdentification": { + "type": "object", + "properties": { + "bic": { + "type": "string", + "maxLength": 11, + "minLength": 8, + "description": "SWIFT BIC (Business Identifier Code) of the financial institution.", + "example": "TRWIUS35XXX" + }, + "routingNumber": { + "type": "string", + "maxLength": 9, + "minLength": 9, + "description": "US ABA routing number identifying the financial institution.", + "example": "101019628" + }, + "accountNumber": { + "type": "string", + "maxLength": 34, + "description": "Domestic account number.", + "example": "9900000000" + }, + "institutionName": { + "type": "string", + "maxLength": 140, + "description": "Name of the financial institution.", + "example": "Wise" + }, + "institutionAddress": { + "$ref": "#/components/schemas/Iso20022Address", + "description": "Postal address of the financial institution." + } + }, + "required": [ + "accountNumber", + "institutionAddress", + "routingNumber" + ] + }, + "AccountIdentification": { + "description": "Country/scheme-specific account identification.", + "oneOf": [ + { + "type": "object", + "title": "beAccountIdentification", + "properties": { + "beAccountIdentification": { + "$ref": "#/components/schemas/BeAccountIdentification", + "description": "Belgian (SEPA) account details format." } - } + }, + "required": [ + "beAccountIdentification" + ] }, - "bankFeatures": { - "type": "array", - "description": "Features enabled on the account.", - "items": { - "type": "object", - "properties": { - "key": { - "type": "string", - "description": "Feature identifier.", - "example": "LOCAL_RECEIVE" - }, - "title": { - "type": "string", - "description": "Human-readable feature name.", - "example": "Receive locally" - }, - "supported": { - "type": "boolean", - "description": "Whether the feature is supported.", - "example": true - } + { + "type": "object", + "title": "gbAccountIdentification", + "properties": { + "gbAccountIdentification": { + "$ref": "#/components/schemas/GbAccountIdentification", + "description": "UK account details format." } - } + }, + "required": [ + "gbAccountIdentification" + ] + }, + { + "type": "object", + "title": "usAccountIdentification", + "properties": { + "usAccountIdentification": { + "$ref": "#/components/schemas/UsAccountIdentification", + "description": "US account details format." + } + }, + "required": [ + "usAccountIdentification" + ] } - } + ] + }, + "AccountDetails": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Unique identifier for the account details.", + "format": "int64", + "example": 12345678 + }, + "profileId": { + "type": "integer", + "description": "Profile ID of the account details owner.", + "format": "int64", + "example": 12345678 + }, + "state": { + "$ref": "#/components/schemas/AccountDetailsState", + "description": "Current state of the account details." + }, + "accountHolderName": { + "type": "string", + "maxLength": 140, + "description": "Name of the account holder as it appears on the account details.", + "example": "Sarah Jenkins" + }, + "country": { + "type": "string", + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z]{2}$", + "description": "ISO 3166-1 alpha-2 country code the account details belong to.", + "example": "GB" + }, + "accountIdentification": { + "$ref": "#/components/schemas/AccountIdentification", + "description": "Country/scheme-specific account identification." + } + }, + "required": [ + "accountHolderName", + "accountIdentification", + "country", + "id", + "profileId", + "state" + ] }, "PayInDetails": { "type": "object", @@ -31362,7 +34190,56 @@ } } }, - "PaymentInitiation": { + "PaymentInitiationDirectDebitRequest": { + "title": "Direct debit", + "type": "object", + "description": "Funds all transfers in the batch group via direct debit.\n\nTo use this funding method, you must link an external bank account first. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate) for more information.\n", + "required": [ + "type", + "accountId" + ], + "properties": { + "type": { + "type": "string", + "description": "The method of payment to use.", + "enum": [ + "DIRECT_DEBIT" + ], + "example": "DIRECT_DEBIT" + }, + "accountId": { + "type": "integer", + "format": "int64", + "description": "Direct debit account ID. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate).", + "example": 1 + }, + "reference": { + "type": "string", + "description": "Optional payment initiation reference. Maximum 10 characters. If not provided, a reference will be generated automatically.", + "example": "B1234567" + } + } + }, + "PaymentInitiationPayinSessionRequest": { + "title": "Payin session", + "type": "object", + "description": "Funds all transfers in the batch group using the payin session associated with the batch group (see `payinSessionId` on the [batch group](/api-reference/batch-group)).\n", + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "description": "The method of payment to use.", + "enum": [ + "PAYIN_SESSION" + ], + "example": "PAYIN_SESSION" + } + } + }, + "PaymentInitiationDirectDebit": { + "title": "Direct debit", "type": "object", "description": "Payment initiation for funding a batch group via direct debit.", "properties": { @@ -31428,7 +34305,75 @@ ], "format": "int64", "description": "Transfer ID of the direct debit payment. Present only after the direct debit is initiated.", - "example": null + "example": 2149510998 + }, + "createdTime": { + "type": "string", + "format": "date-time", + "description": "Date and time when the payment initiation was created.", + "example": "2022-01-01T19:51:41.423404Z" + } + } + }, + "PaymentInitiationPayinSession": { + "title": "Payin session", + "type": "object", + "description": "Payment initiation for funding a batch group via payin session.", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "Payment initiation ID.", + "example": 12345 + }, + "batchGroupId": { + "type": "string", + "format": "uuid", + "description": "Batch group ID.", + "example": "068e186d-9632-4937-b753-af3e53f4d0b0" + }, + "reference": { + "type": "string", + "description": "Payment reference that will be passed to the network. Can be used for reconciliation.", + "example": "B1234567" + }, + "userId": { + "type": "integer", + "format": "int64", + "description": "The ID of the user who initiated this payment.", + "example": 33333333 + }, + "profileId": { + "type": "integer", + "format": "int64", + "description": "The ID of the profile this payment belongs to.", + "example": 44444444 + }, + "type": { + "type": "string", + "description": "Payment type.", + "enum": [ + "PAYIN_SESSION" + ], + "example": "PAYIN_SESSION" + }, + "status": { + "type": "string", + "description": "Payment initiation status:\n- `NEW` — Payment initiation created\n- `PROCESSING` — Payment is being processed\n- `COMPLETED` — Payment completed successfully\n- `FAILED` — Payment failed\n- `CHARGED_BACK` — Payment was charged back\n", + "enum": [ + "NEW", + "PROCESSING", + "COMPLETED", + "FAILED", + "CHARGED_BACK" + ], + "example": "NEW" + }, + "payinSessionId": { + "type": "string", + "format": "uuid", + "description": "ID of the payin session used to fund the batch group.", + "example": "7c1f3a52-9d4e-4b8a-a6f2-3e5d8c9b0a17" }, "createdTime": { "type": "string", @@ -31438,6 +34383,24 @@ } } }, + "PaymentInitiation": { + "description": "Payment initiation for funding a batch group. The response shape depends on the funding method used.\n", + "discriminator": { + "propertyName": "type", + "mapping": { + "DIRECT_DEBIT": "#/components/schemas/PaymentInitiationDirectDebit", + "PAYIN_SESSION": "#/components/schemas/PaymentInitiationPayinSession" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/PaymentInitiationDirectDebit" + }, + { + "$ref": "#/components/schemas/PaymentInitiationPayinSession" + } + ] + }, "Card": { "type": "object", "description": "The Card resource represents a Wise card linked to a profile.", @@ -33158,6 +36121,2369 @@ } } }, + "select-requirement-type": { + "title": "Select a requirement type", + "description": "The request body depends on the requirement type being submitted. Select it from the list to see the `submissionData` fields and whether `files` are needed; the request sample updates to match.", + "not": {} + }, + "version": { + "type": "string", + "description": "The submission version.", + "enum": [ + "V1" + ], + "example": "V1" + }, + "kyc-review-id": { + "type": "string", + "format": "uuid", + "description": "The ID of the KYC Review this submission belongs to.", + "example": "93a903ea-636c-4c86-a25c-cf6d2bd00e81" + }, + "account-intent": { + "title": "ACCOUNT_INTENT", + "description": "How the customer intends to use their Wise account.\n\nSee [ACCOUNT_INTENT](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#account_intent) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"accountIntent\": \"PAYING_FOR_GOODS_OR_SERVICES_ABROAD\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "accountIntent" + ], + "properties": { + "accountIntent": { + "type": "string", + "description": "How the customer intends to use their Wise account. The accepted values depend on whether the profile is personal or business.\n\nDepending on what triggered the KYC review, only some of these values may be accepted. Other values are rejected with a `400` error.\n", + "anyOf": [ + { + "title": "Personal profiles", + "type": "string", + "enum": [ + "CONTRIBUTING_TO_PERSONAL_SAVINGS", + "GENERAL_MONTHLY_LIVING_EXPENSES", + "INVESTING_IN_FUNDS_STOCKS_BONDS_OPTIONS_FUTURES_OR_OTHER", + "PAYING_FOR_GOODS_OR_SERVICES_ABROAD", + "PAYING_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT", + "PAYING_RENT_UTILITIES_OR_PROPERTY_CHARGES", + "RECEIVE_SALARY_IN_DIFFERENT_CURRENCY", + "RECEIVE_PENSION_IN_DIFFERENT_CURRENCY", + "SENDING_MONEY_REGULARLY_TO_FAMILY", + "SENDING_MONEY_TO_MY_OWN_ACCOUNT_TO_BENEFIT_FROM_EXHCANGE_RATE", + "EDD_BORDERLESS_PERSONAL_RECEIVING_SALARY_IN_DIFFERENT_CURRENCY", + "EDD_BORDERLESS_PERSONAL_RECEIVING_FINANCIAL_SUPPORT_FROM_FAMILY", + "EDD_BORDERLESS_PERSONAL_RECEIVING_MONEY_FOR_FREELANCE_OR_CONTRACTOR_SERVICES", + "EDD_BORDERLESS_PERSONAL_STORING_MONEY_TO_MANAGE_RATE_FLUCTUATION_RISK", + "EDD_BORDERLESS_PERSONAL_USING_AS_LOCAL_BANK_ACCOUNT_IN_FOREIGN_COUNTRY", + "EDD_BORDERLESS_PERSONAL_PAYING_FOR_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT_CARD" + ] + }, + { + "title": "Business profiles", + "type": "string", + "enum": [ + "EDD_BORDERLESS_BUSINESS_PAYING_SUPPLIERS_CONTRACTORS_EMPLOYEES", + "EDD_BORDERLESS_BUSINESS_PAYING_SUPPLIERS_CONTRACTORS_EMPLOYEES_AND_RECEIVING_MONEY_FOR_SERVICES", + "PAYING_SUPPLIERS_CONTRACTORS_EMPLOYEES_AND_RECEIVING_MONEY_FOR_SERVICES", + "INVESTING_IN_FUNDS_STOCKS_BONDS_OPTIONS_FUTURES_OR_OTHER", + "DISTRIBUTING_COMPANY_PROFITS_OR_PAYING_DIVIDENDS", + "PAYING_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT", + "PAYING_FOR_GOODS_SERVICES_ABROAD", + "PAYING_RENT_UTILITIES_OR_PROPERTY_CHARGES", + "PAYING_SUPPLIERS_CONTRACTORS_EMPLOYEES", + "PAYING_TAX_ON_PROFIT_OR_PROPERTY", + "TRANSFER_WITHIN_COMPANY_OR_GROUP", + "EDD_BORDERLESS_BUSINESS_MAKING_INTRA_COMPANY_TRANSFERS" + ] + } + ], + "example": "PAYING_FOR_GOODS_OR_SERVICES_ABROAD" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "account-purpose": { + "title": "ACCOUNT_PURPOSE", + "description": "The purpose of the account.\n\nSee [ACCOUNT_PURPOSE](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#account_purpose) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"accountPurpose\": \"SENDING_MONEY_TO_FRIENDS_OR_FAMILY\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "accountPurpose" + ], + "properties": { + "accountPurpose": { + "type": "string", + "enum": [ + "SENDING_MONEY_TO_FRIENDS_OR_FAMILY", + "MOVING_SAVINGS", + "GENERAL_LIVING_EXPENSES", + "BUYING_GOODS_OR_SERVICES_ABROAD", + "PAYING_FOR_MORTGAGE_OR_LOAN", + "PAYING_BILLS", + "RECEIVING_SALARY_OR_PENSION", + "INVESTING" + ], + "example": "SENDING_MONEY_TO_FRIENDS_OR_FAMILY" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "currency": { + "type": "string", + "description": "The currency code (e.g. `USD`, `EUR`).", + "example": "USD" + }, + "annual-volume": { + "title": "ANNUAL_VOLUME", + "description": "A rough estimate of the yearly volume the customer intends to send or receive.\n\nSee [ANNUAL_VOLUME](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#annual_volume) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"amount\": 10000.00,\n \"currency\": \"USD\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "type": "number", + "exclusiveMinimum": 0, + "description": "The estimated annual volume amount. Must be greater than zero.", + "example": 10000 + }, + "currency": { + "$ref": "#/components/schemas/currency" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-annual-income": { + "title": "BUSINESS_ANNUAL_INCOME", + "description": "The organisation's approximate gross yearly income.\n\nSee [BUSINESS_ANNUAL_INCOME](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_annual_income) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"amount\": 4500.00,\n \"currency\": \"USD\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "type": "number", + "exclusiveMinimum": 0, + "description": "The gross yearly income amount. Must be greater than zero.", + "example": 4500 + }, + "currency": { + "$ref": "#/components/schemas/currency" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-authorisation-id": { + "title": "BUSINESS_AUTHORISATION_ID", + "description": "The identification document of one company Director. This document is required to verify authorisation to act on the account on behalf of the organisation. It is only asked for if the Business Representative (the account creator) is not listed as a Director of the company.\n\nNo `data` field is needed. See [BUSINESS_AUTHORISATION_ID](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_authorisation_id) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the identification document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-authorisation-letter": { + "title": "BUSINESS_AUTHORISATION_LETTER", + "description": "A document authorising the Business Representative to act on the account on behalf of the organisation. When the Business Representative is also a Director, they are automatically authorised and this document is not needed.\n\nThe document must include:\n- Business name, legal type, registration number, country of incorporation and registered address.\n- Legal Representative's (the Director) name, date of birth, function in the company (such as Director), permission to act on behalf of the organisation and signature.\n- Authorised Representative's (the Business Representative) name, date of birth, authority to act on the account and signature.\n- Date of issue.\n\nNo `data` field is needed. See [BUSINESS_AUTHORISATION_LETTER](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_authorisation_letter) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the authorisation letter.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-controlling-person": { + "title": "BUSINESS_CONTROLLING_PERSON", + "description": "Declare exactly one shareholder as the person who controls the business and provide their business title.\n\nSee [BUSINESS_CONTROLLING_PERSON](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_controlling_person) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"shareholderId\": \"7ff6c4998a59d71ad9834041727017d2\",\n \"businessTitle\": \"CEO\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "shareholderId", + "businessTitle" + ], + "properties": { + "shareholderId": { + "type": "string", + "description": "The ID of the shareholder declared as the controlling person. Use the `id` returned by the [List UBOs](/api-reference/profile/profileubolist) endpoint.", + "example": "7ff6c4998a59d71ad9834041727017d2" + }, + "businessTitle": { + "type": "string", + "description": "The controlling person's title or role in the business.", + "enum": [ + "GENERAL_PARTNER", + "FOUNDER", + "CEO", + "PRESIDENT", + "MANAGING_DIRECTOR", + "COO", + "CFO", + "TREASURER", + "EXECUTIVE_DIRECTOR", + "VICE_PRESIDENT" + ], + "example": "CEO" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-directors-check": { + "title": "BUSINESS_DIRECTORS_CHECK", + "description": "Confirm the directors of the business. Directors can be members of the board of directors, general partners or part of executive management. If a director is another business, a document identifying the individuals directing that business is needed.\n\nNo `data` field is needed. See [BUSINESS_DIRECTORS_CHECK](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_directors_check) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the relevant documents.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-income-classification": { + "title": "BUSINESS_INCOME_CLASSIFICATION", + "description": "Under the Common Reporting Standard (CRS), we are required to collect your business's tax classification based on how it earns income. Depending on your selection, we may need to ask for additional information (such as tax details on controlling persons).\n\nSee [BUSINESS_INCOME_CLASSIFICATION](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_income_classification) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"classificationType\": \"ACTIVE_NFE\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "classificationType" + ], + "properties": { + "classificationType": { + "type": "string", + "description": "The business's CRS classification.\n- `ACTIVE_NFE` - Active non-financial entity: more than 50% of the business's income comes from sales, services, donations, or grants.\n- `PASSIVE_NFE` - Passive non-financial entity: more than 50% of the business's income comes from dividends, interest, rent, or royalties.\n- `FI_INVESTMENT_ENTITY` - Financial institution (FI) that manages investment, hedge, or private equity funds, or is a foundation funded by investments.\n- `FI_NON_INVESTMENT_ENTITY` - FI such as a bank, credit union, custodial institution, or similar.\n", + "enum": [ + "ACTIVE_NFE", + "PASSIVE_NFE", + "FI_INVESTMENT_ENTITY", + "FI_NON_INVESTMENT_ENTITY" + ], + "example": "ACTIVE_NFE" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-monthly-volume": { + "title": "BUSINESS_MONTHLY_VOLUME", + "description": "A rough estimate of the monthly volumes the business intends to send or receive.\n\nSee [BUSINESS_MONTHLY_VOLUME](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_monthly_volume) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"amount\": 4500.00,\n \"currency\": \"USD\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "amount", + "currency" + ], + "properties": { + "amount": { + "type": "number", + "exclusiveMinimum": 0, + "description": "The estimated monthly volume. Must be greater than zero.", + "example": 4500 + }, + "currency": { + "$ref": "#/components/schemas/currency" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-registration-docs": { + "title": "BUSINESS_REGISTRATION_DOCS", + "description": "Proof of Business Registration, such as a certificate of incorporation, articles of association, or an official registry excerpt. It should be the document on record with the local business or tax authority. It must show:\n- The business name, identification number and full registered address.\n- The directors, managers, partners, trustees or members of the executive board.\n- The owners, members or shareholders and their respective holdings.\n\nIf any of the above information has changed since formation, upload a document showing the most up to date details.\n\nNo `data` field is needed. See [BUSINESS_REGISTRATION_DOCS](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_registration_docs) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the registration documents.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-shareholder-contact-details": { + "title": "BUSINESS_SHAREHOLDER_CONTACT_DETAILS", + "description": "Provide contact details, including email addresses, for all current shareholders of the business. Submit all contact details in a single request; requests that omit any shareholders are rejected.\n\nSee [BUSINESS_SHAREHOLDER_CONTACT_DETAILS](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_shareholder_contact_details) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"businessShareholderContactDetails\": [\n {\n \"shareholderId\": \"7ff6c4998a59d71ad9834041727017d2\",\n \"email\": \"shareholder-one@example.com\"\n },\n {\n \"shareholderId\": \"a9578a5a0544d06fd737566c627518a4\",\n \"email\": \"shareholder-two@example.com\"\n }\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "businessShareholderContactDetails" + ], + "properties": { + "businessShareholderContactDetails": { + "type": "array", + "description": "Provide each current shareholder exactly once.", + "items": { + "type": "object", + "required": [ + "shareholderId", + "email" + ], + "properties": { + "shareholderId": { + "type": "string", + "description": "The shareholder ID. Use the `id` returned by the [List UBOs](/api-reference/profile/profileubolist) endpoint.", + "example": "7ff6c4998a59d71ad9834041727017d2" + }, + "email": { + "type": "string", + "format": "email", + "maxLength": 255, + "description": "The shareholder's email address. It must be a valid email address with no more than 255 characters.", + "example": "shareholder-one@example.com" + } + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-shareholders-check": { + "title": "BUSINESS_SHAREHOLDERS_CHECK", + "description": "Documents showing who ultimately owns and controls the company (e.g. a recent shareholder register, operating agreement, or partnership deed). If an owner is another business, a document identifying the individuals who are the ultimate beneficial owners of that business is needed.\n\nNo `data` field is needed. See [BUSINESS_SHAREHOLDERS_CHECK](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_shareholders_check) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the relevant documents.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-source-of-wealth": { + "title": "BUSINESS_SOURCE_OF_WEALTH", + "description": "The source of the business's wealth.\n\nSee [BUSINESS_SOURCE_OF_WEALTH](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_source_of_wealth) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"sourceOfWealthList\": [\n \"BUSINESS_ACTIVITIES\",\n \"OTHER\"\n ],\n \"otherSourceOfWealthDescription\": \"Loan from friends\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "sourceOfWealthList" + ], + "properties": { + "sourceOfWealthList": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "BUSINESS_ACTIVITIES", + "INVESTMENTS", + "LOAN_OR_OTHER_FINANCING", + "DONATION", + "GRANTS", + "OTHER" + ] + }, + "example": [ + "BUSINESS_ACTIVITIES", + "OTHER" + ] + }, + "otherSourceOfWealthDescription": { + "type": "string", + "description": "Required if `OTHER` is provided in `sourceOfWealthList`.", + "example": "Loan from friends" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-source-of-wealth-info": { + "title": "BUSINESS_SOURCE_OF_WEALTH_INFO", + "description": "The source of the business's wealth and whether it is used to fund the action.\n\nSee [BUSINESS_SOURCE_OF_WEALTH_INFO](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_source_of_wealth_info) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"sourceOfWealthList\": [\n {\n \"businessSourceOfWealthInfo\": \"BUSINESS_LOAN\",\n \"isSourceOfFund\": false\n },\n {\n \"businessSourceOfWealthInfo\": \"GRANTS\",\n \"isSourceOfFund\": true\n }\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "sourceOfWealthList" + ], + "properties": { + "sourceOfWealthList": { + "type": "array", + "items": { + "type": "object", + "properties": { + "businessSourceOfWealthInfo": { + "type": "string", + "enum": [ + "REVENUE", + "PERSONAL_FUNDING", + "BUSINESS_LOAN", + "FUNDING_AND_SHAREHOLDER_INVESTMENTS", + "INVESTMENT_INCOME", + "DONATIONS", + "GRANTS", + "LEGAL" + ], + "example": "BUSINESS_LOAN" + }, + "isSourceOfFund": { + "type": "boolean", + "description": "Whether this source of wealth is used to fund the action.", + "example": false + } + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "business-source-of-wealth-proof": { + "title": "BUSINESS_SOURCE_OF_WEALTH_PROOF", + "description": "A high-quality photo or PDF of a document proving the source of the business's wealth. The required documentation varies depending on the selected source category. Examples include the most recent 3-6 months worth of bank statements, latest audited financials, latest tax returns, loan agreements, or investment contracts that are less than 12 months old. The document should display the business income amount (if you have more than one type of income, you will have to upload documents for each of them), the business name, the issue date and signatures, if applicable.\n\nSee [BUSINESS_SOURCE_OF_WEALTH_PROOF](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_source_of_wealth_proof) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"sourceOfWealthType\": \"REVENUE\",\n \"documentType\": \"SAVINGS_STATEMENT\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "sourceOfWealthType": { + "type": "string", + "enum": [ + "REVENUE", + "PERSONAL_FUNDING", + "BUSINESS_LOAN", + "FUNDING_AND_SHAREHOLDER_INVESTMENTS", + "INVESTMENT_INCOME", + "DONATIONS", + "GRANTS", + "LEGAL" + ], + "example": "REVENUE" + }, + "documentType": { + "type": "string", + "enum": [ + "PAYSLIP", + "INVOICES", + "CONTRACTS", + "TAX_DOCUMENTS", + "AUDITED_FINANCIAL_STATEMENTS", + "E_COMMERCE_STATEMENTS", + "PERSONAL_INVESTMENT", + "PERSONAL_LOAN_AGREEMENT", + "PERSONAL_TAX_DECLARATION", + "LOAN_AGREEMENT", + "EQUITY_AGREEMENT", + "SUBSCRIPTION_AGREEMENT", + "SAVINGS_STATEMENT", + "ASSET_SALE_AGREEMENT", + "SHARE_SALE_CERTIFICATE", + "DONATION_RECEIPTS", + "GRANT_APPROVAL_LETTER", + "WRITTEN_CONFIRMATION", + "BANK_STATEMENT" + ], + "example": "SAVINGS_STATEMENT" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the proof document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "business-ultimate-beneficial-owner-id": { + "title": "BUSINESS_ULTIMATE_BENEFICIAL_OWNER_ID", + "description": "The Ultimate Beneficial Owner (UBO) ID document should be submitted for all UBOs that have more than 25% share. While this requirement is `NOT_PROVIDED`, its `attributes.requiredUbos` lists the shareholder IDs that still need an ID document.\n\nProvide a clear copy of the ID document. The full document needs to be in frame and all information on the document needs to be visible. If the document has information on the backside, both sides are needed. Expired documents and documents issued over 15 years ago cannot be accepted.\n\nWhen `data.documentType` is `SSN`, set `data.ssn` instead of the file names and don't upload files.\n\nSee [BUSINESS_ULTIMATE_BENEFICIAL_OWNER_ID](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_ultimate_beneficial_owner_id) in the KYC requirement types guide for more details.\n", + "type": "object", + "anyOf": [ + { + "title": "Document upload", + "description": "Submit an ID document for the UBO. Upload the document in `files`, with file names matching `frontSideFileName` and `backSideFileName`.", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"documentType\": \"NATIONAL_ID\",\n \"shareholderId\": \"489209\",\n \"frontSideFileName\": \"image1.jpeg\",\n \"backSideFileName\": \"image2.jpeg\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "documentType", + "shareholderId" + ], + "properties": { + "documentType": { + "type": "string", + "description": "Accepted document types vary by the region the business is located in.\n\n**US business address** (United States, American Samoa, Guam, North Mariana Islands, Puerto Rico, United States Virgin Islands, United States Minor Outlying Islands):\n- `NON_US_DRIVING_LICENSE`\n- `NON_US_NATIONAL_ID`\n- `NON_US_PASSPORT`\n\n**EEA business address:**\n- `NATIONAL_ID`\n- `PASSPORT`\n\n**Other regions:**\n- `DRIVING_LICENSE`\n- `NATIONAL_ID`\n- `PASSPORT`\n\nUS businesses can submit an SSN instead of a document; select **SSN** above.\n", + "enum": [ + "NON_US_DRIVING_LICENSE", + "NON_US_NATIONAL_ID", + "NON_US_PASSPORT", + "DRIVING_LICENSE", + "NATIONAL_ID", + "PASSPORT" + ], + "example": "NATIONAL_ID" + }, + "shareholderId": { + "type": "string", + "description": "The UBO's shareholder ID. Use the `id` returned by the [Create UBO](/api-reference/profile/profileubocreate) or [List UBOs](/api-reference/profile/profileubolist) endpoints.", + "example": "489209" + }, + "frontSideFileName": { + "type": "string", + "description": "Filename of the front side image. Required for document types with front and back.", + "example": "image1.jpeg" + }, + "backSideFileName": { + "type": "string", + "description": "Filename of the back side image. Required for document types with front and back.", + "example": "image2.jpeg" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "image1.jpeg", + "image2.jpeg" + ] + ], + "description": "Upload the ID document, with file names matching `data.frontSideFileName` and `data.backSideFileName`.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"image1.jpeg\", \"image2.jpeg\"]\n```\n" + } + } + }, + { + "title": "SSN", + "description": "For businesses with a US business address, submit the UBO's Social Security Number instead of an ID document. No files are needed.", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"documentType\": \"SSN\",\n \"shareholderId\": \"489209\",\n \"ssn\": \"555501234\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "documentType", + "shareholderId", + "ssn" + ], + "properties": { + "documentType": { + "type": "string", + "enum": [ + "SSN" + ], + "example": "SSN" + }, + "shareholderId": { + "type": "string", + "description": "The UBO's shareholder ID. Use the `id` returned by the [Create UBO](/api-reference/profile/profileubocreate) or [List UBOs](/api-reference/profile/profileubolist) endpoints.", + "example": "489209" + }, + "ssn": { + "type": "string", + "description": "The UBO's Social Security Number, as 9 digits without dashes.", + "pattern": "^[0-9]{9}$", + "example": "555501234" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + } + ] + }, + "business-use-case": { + "title": "BUSINESS_USE_CASE", + "description": "How the business intends to use the Wise account.\n\nSee [BUSINESS_USE_CASE](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#business_use_case) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"useCases\": [\n \"DONATION\",\n \"PAYING_RENT_OR_UTILITIES\"\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "useCases" + ], + "properties": { + "useCases": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "INVESTING_IN_FUNDS_STOCKS_BONDS_OR_SIMILAR", + "DISTRIBUTING_COMPANY_PROFITS_OR_PAYING_DIVIDENDS", + "PAYING_MORTGAGE_BANK_LOAN_INSURANCE_OR_CREDIT", + "PAYING_FOR_GOODS_PROPERTIES_OR_SERVICES_ABROAD", + "PAYING_RENT_OR_UTILITIES", + "PAYING_SUPPLIERS_CONTRACTORS_OR_EMPLOYEES", + "PAYING_TAX_ON_PROFIT_OR_PROPERTY", + "TRANSFER_WITHIN_COMPANY_OR_GROUP", + "RECEIVE_INVESTMENTS_OR_FUNDS", + "RECEIVE_PAYMENTS_FROM_CLIENTS", + "DONATION", + "OTHER" + ] + }, + "example": [ + "DONATION", + "PAYING_RENT_OR_UTILITIES" + ] + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "id-document": { + "title": "ID_DOCUMENT", + "description": "Provide a clear copy of the ID document. The full document needs to be in frame and all information on the document needs to be visible. If the document has information on the backside, both sides are needed. Expired documents and documents issued over 15 years ago cannot be accepted.\n\nSee [ID_DOCUMENT](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#id_document) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"issuingCountry\": \"GB\",\n \"documentType\": \"DRIVERS_LICENSE\",\n \"frontSideFileName\": \"front_side.jpg\",\n \"backSideFileName\": \"back_side.jpg\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "issuingCountry": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code.", + "example": "GB" + }, + "documentType": { + "type": "string", + "enum": [ + "PASSPORT", + "ID_CARD", + "DRIVERS_LICENSE", + "TAX_ID", + "RESIDENCE_PERMIT" + ], + "example": "DRIVERS_LICENSE" + }, + "frontSideFileName": { + "type": "string", + "description": "Filename of the front side image. Required for `ID_CARD`, `DRIVERS_LICENSE`, `TAX_ID`, `RESIDENCE_PERMIT`.", + "example": "front_side.jpg" + }, + "backSideFileName": { + "type": "string", + "description": "Filename of the back side image. Required for `ID_CARD`, `DRIVERS_LICENSE`, `TAX_ID`, `RESIDENCE_PERMIT`.", + "example": "back_side.jpg" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "front_side.jpg", + "back_side.jpg" + ] + ], + "description": "Upload the ID document, with file names matching `frontSideFileName` and `backSideFileName`.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"front_side.jpg\", \"back_side.jpg\"]\n```\n" + } + } + }, + "income": { + "title": "INCOME", + "description": "Approximate gross yearly income.\n\nSee [INCOME](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#income) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"amount\": 50000.00,\n \"currency\": \"USD\",\n \"incomeType\": \"SALARY\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "amount": { + "type": "number", + "exclusiveMinimum": 0, + "description": "The gross yearly income amount. Must be greater than zero.", + "example": 50000 + }, + "currency": { + "$ref": "#/components/schemas/currency" + }, + "incomeType": { + "type": "string", + "enum": [ + "SALARY", + "INVESTMENTS", + "PENSION", + "INHERITANCE", + "LOAN", + "PROPERTY_SALE", + "FREELANCER", + "FAMILY", + "STUDENT", + "GOVERNMENT_BENEFITS" + ], + "example": "SALARY" + }, + "incomeExplanation": { + "type": [ + "string", + "null" + ], + "description": "Optional. A free-text description of the income source.", + "example": "Salary from full-time employment" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "india-transfer-purpose": { + "title": "INDIA_TRANSFER_PURPOSE", + "description": "The code representing the purpose of the profile's transfer, along with supporting documents based on the code provided. This only appears for transfers from INR to one of GBP, USD, EUR, AUD, CAD, SGD.\n\nSee [INDIA_TRANSFER_PURPOSE](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#india_transfer_purpose) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"code\": \"OVERSEAS_EDUCATION\",\n \"tcsTaxApplies\": false,\n \"educationPaidWithLoan\": true,\n \"passportFileName\": \"file1.png\",\n \"additionalDocumentFileName\": \"file2.png\",\n \"loanDocumentFileName\": \"file3.png\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "code", + "tcsTaxApplies", + "educationPaidWithLoan", + "passportFileName", + "additionalDocumentFileName" + ], + "properties": { + "code": { + "type": "string", + "description": "Represents the purpose of the profile's transfer.", + "enum": [ + "OVERSEAS_EDUCATION", + "EDUCATION_EXPENSES", + "BUSINESS_TRAVEL", + "VACATION", + "MEDICAL_TREATMENT" + ], + "example": "OVERSEAS_EDUCATION" + }, + "tcsTaxApplies": { + "type": "boolean", + "description": "Must be set to `true` if the profile has remitted more than INR 10 lakhs (including the current transaction) in the current financial year.", + "example": false + }, + "educationPaidWithLoan": { + "type": "boolean", + "description": "If `code` is `OVERSEAS_EDUCATION` or `EDUCATION_EXPENSES`, set to `true` if the profile is paying for this transfer with a loan from a financial institution. For other codes set to `false`.", + "example": true + }, + "passportFileName": { + "type": "string", + "description": "Filename for the profile's passport image.", + "example": "file1.png" + }, + "additionalDocumentFileName": { + "type": "string", + "description": "Filename for the additional document provided. The type of file supplied as additional document must be based on the `code`, and must be in the profile's name.\n- For `OVERSEAS_EDUCATION` or `EDUCATION_EXPENSES` this can be a visa or university admission letter.\n- For `BUSINESS_TRAVEL` or `VACATION` this can be a visa or travel ticket.\n- For `MEDICAL_TREATMENT` this can be a hospital invoice, doctor's confirmation, or appointment letter.\n", + "example": "file2.png" + }, + "loanDocumentFileName": { + "type": "string", + "description": "Required when `educationPaidWithLoan` is `true`. Filename for the loan sanction letter including sanctioned amount and borrower details.", + "example": "file3.png" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "file1.png", + "file2.png", + "file3.png" + ] + ], + "description": "Upload the supporting documents, with file names matching the `*FileName` fields.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"file1.png\", \"file2.png\", \"file3.png\"]\n```\n" + } + } + }, + "jpn-business-cert": { + "title": "JPN_BUSINESS_CERT", + "description": "Certificate of Registered Matters for the business. Required for corporations only in Japan. The document verifies: business name, registered address, registration date, business activities, directors, and must be issued within 6 months.\n\nNo `data` field is needed. See [JPN_BUSINESS_CERT](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#jpn_business_cert) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the business document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "jpn-personal-mynumber": { + "title": "JPN_PERSONAL_MYNUMBER", + "description": "Proof of My Number for the customer. My Number is a 12-digit ID number issued to all Japan citizens and residents, including resident foreigners living in Japan for over 90 days. All the information (name, DOB, address) on a My Number document has to match the information on the profile and on the ID document.\n\nSee [JPN_PERSONAL_MYNUMBER](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#jpn_personal_mynumber) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"documentType\": \"MY_NUMBER_CARD\",\n \"frontSideFileName\": \"front.jpg\",\n \"backSideFileName\": \"back.jpg\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "documentType": { + "type": "string", + "description": "The type of My Number document being submitted.", + "enum": [ + "MY_NUMBER_CARD", + "MY_NUMBER_NOTIFICATION_CARD", + "RESIDENCE_CERTIFICATE" + ], + "example": "MY_NUMBER_CARD" + }, + "frontSideFileName": { + "type": "string", + "description": "The file name of the front-side image. Must match the name of one of the uploaded files. Required for `MY_NUMBER_CARD` and `MY_NUMBER_NOTIFICATION_CARD`; not required for `RESIDENCE_CERTIFICATE`.", + "example": "front.jpg" + }, + "backSideFileName": { + "type": "string", + "description": "The file name of the back-side image. Must match the name of one of the uploaded files. Required for `MY_NUMBER_CARD` and `MY_NUMBER_NOTIFICATION_CARD`; not required for `RESIDENCE_CERTIFICATE`.", + "example": "back.jpg" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "front.jpg", + "back.jpg" + ] + ], + "description": "The required number of files depends on `documentType`:\n\n| Document type | File requirements |\n|---|---|\n| `MY_NUMBER_CARD` | 2 files (front and back) |\n| `MY_NUMBER_NOTIFICATION_CARD` | 2 files (front and back) |\n| `RESIDENCE_CERTIFICATE` | 1 or more files (all pages) |\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"front.jpg\", \"back.jpg\"]\n```\n" + } + } + }, + "legal-entity-shareholder": { + "title": "LEGAL_ENTITY_SHAREHOLDER", + "description": "A legal entity shareholder is another business or organisation that directly or indirectly owns part or all of the business being onboarded. Provide the name, registered country and ownership percentage of every legal entity shareholder that owns 25% or more, directly or indirectly. Do not include individual shareholders or the business being onboarded. If there are no qualifying legal entity shareholders, submit an empty list.\n\nSee [LEGAL_ENTITY_SHAREHOLDER](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#legal_entity_shareholder) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"legalEntityShareholders\": [\n {\n \"name\": \"Example Holdings Inc\",\n \"country\": \"US\",\n \"ownershipPercentage\": 40\n }\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "legalEntityShareholders" + ], + "properties": { + "legalEntityShareholders": { + "type": "array", + "description": "The legal entity shareholders of the business.", + "items": { + "type": "object", + "required": [ + "name", + "country", + "ownershipPercentage" + ], + "properties": { + "name": { + "type": "string", + "description": "The shareholder's name. Must not match the business name.", + "example": "Example Holdings Inc" + }, + "country": { + "type": "string", + "description": "The shareholder's country as an uppercase ISO 3166-1 alpha-2 country code.", + "example": "US" + }, + "ownershipPercentage": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "The shareholder's ownership percentage, between 1 and 100 inclusive. The combined total may exceed 100. This is expected behaviour for multi-layered corporate structures.", + "example": 40 + } + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "proof-of-trading-address": { + "title": "PROOF_OF_TRADING_ADDRESS", + "description": "High-quality image or PDF of a document verifying the physical location of the business operations. The document must clearly display the business name (or owner's name), the full trading address, an issue date, and the issuer's identity (e.g. bank or utility logo). Utility bills and bank statements must be less than 3 months old. Other documents (like tax bills, insurance policies, or licences) must be less than 12 months old.\n\nSee [PROOF_OF_TRADING_ADDRESS](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#proof_of_trading_address) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"documentType\": \"UTILITY_BILL\",\n \"tradingAddressId\": 4711\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "documentType": { + "type": "string", + "enum": [ + "ID_DOCUMENT", + "UTILITY_BILL", + "PHONE_BILL", + "LEASE_AGREEMENT", + "BANK_STATEMENT", + "BUSINESS_REGISTRATION", + "TAX_BILL", + "TAX_DOCUMENT", + "INSURANCE_POLICY", + "OTHER" + ], + "example": "UTILITY_BILL" + }, + "tradingAddressId": { + "type": "integer", + "format": "int64", + "description": "The trading address ID, from the addresses on the business profile.", + "example": 4711 + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the proof document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "source-of-funds": { + "title": "SOURCE_OF_FUNDS", + "description": "The origin category of the money used to finance a specific transaction or operation.\n\nSee [SOURCE_OF_FUNDS](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#source_of_funds) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"category\": \"SALARY\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "category": { + "type": "string", + "description": "The origin category of the money. The accepted values depend on whether the profile is personal or business.", + "anyOf": [ + { + "title": "Personal profiles", + "type": "string", + "enum": [ + "SALARY", + "INVESTMENT", + "INHERITANCE", + "LOAN", + "PROPERTY_SALE", + "FROM_FAMILY", + "OTHER" + ] + }, + { + "title": "Business profiles", + "type": "string", + "enum": [ + "BUSINESS_OPERATING", + "BUSINESS_INVESTING", + "BUSINESS_FINANCING", + "OTHER" + ] + } + ], + "example": "SALARY" + }, + "explanation": { + "type": [ + "string", + "null" + ], + "description": "Required if `category` is `OTHER`.", + "example": "Monthly salary from my employer" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "source-of-wealth": { + "title": "SOURCE_OF_WEALTH", + "description": "Source of wealth document upload.\n\nNo `data` field is needed. See [SOURCE_OF_WEALTH](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#source_of_wealth) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "version", + "kycReviewId" + ], + "properties": { + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the source of wealth document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "source-of-wealth-info": { + "title": "SOURCE_OF_WEALTH_INFO", + "description": "Whether there is a secondary source of income, and if so its type and amount. When `hasSecondaryIncome` is `false`, no other fields are required.\n\nSee [SOURCE_OF_WEALTH_INFO](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#source_of_wealth_info) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"hasSecondaryIncome\": true,\n \"secondaryIncomeType\": \"SALARY\",\n \"amount\": 20000.00,\n \"currency\": \"USD\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "hasSecondaryIncome" + ], + "properties": { + "hasSecondaryIncome": { + "type": "boolean", + "description": "Set to `true` if there's a secondary source of income.", + "example": true + }, + "secondaryIncomeType": { + "type": "string", + "description": "Required when `hasSecondaryIncome` is `true`. Accepted values for personal profiles.", + "enum": [ + "SALARY", + "PENSION", + "INHERITANCE", + "PROPERTY_SALE", + "LOAN", + "INVESTMENTS", + "OTHER" + ], + "example": "SALARY" + }, + "secondaryIncomeDescription": { + "type": [ + "string", + "null" + ], + "description": "Optional. A free-text description of the secondary income source.", + "example": "Part-time salary from a second job" + }, + "amount": { + "type": "number", + "exclusiveMinimum": 0, + "description": "Required when `hasSecondaryIncome` is `true`. The secondary income amount. Must be greater than zero.", + "example": 20000 + }, + "currency": { + "$ref": "#/components/schemas/currency", + "description": "Required when `hasSecondaryIncome` is `true`. The currency code (e.g. `USD`, `EUR`)." + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "source-of-wealth-proof": { + "title": "SOURCE_OF_WEALTH_PROOF", + "description": "A document proving the secondary source of wealth income. The accepted document types depend on the `secondaryIncomeType` provided.\n\nSee [SOURCE_OF_WEALTH_PROOF](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#source_of_wealth_proof) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData", + "files" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"secondaryIncomeType\": \"SALARY\",\n \"secondaryIncomeDocumentType\": \"PAYSLIP\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "properties": { + "secondaryIncomeType": { + "type": "string", + "description": "Accepted values for personal profiles.", + "enum": [ + "SALARY", + "PENSION", + "INHERITANCE", + "PROPERTY_SALE", + "LOAN", + "INVESTMENTS", + "OTHER" + ], + "example": "SALARY" + }, + "secondaryIncomeDocumentType": { + "type": "string", + "description": "The type of document being uploaded.", + "examples": [ + "PAYSLIP" + ], + "anyOf": [ + { + "title": "Select an income type", + "description": "The accepted values depend on `secondaryIncomeType`. Select the income type from the list to see its document types.", + "not": {} + }, + { + "title": "SALARY", + "description": "Document types accepted when `secondaryIncomeType` is `SALARY`.", + "type": "string", + "enum": [ + "PAYSLIP", + "TAX_RETURN", + "EMPLOYMENT_CONTRACT", + "PROOF_OF_EMPLOYMENT", + "BANK_STATEMENT" + ] + }, + { + "title": "INVESTMENTS", + "description": "Document types accepted when `secondaryIncomeType` is `INVESTMENTS`.", + "type": "string", + "enum": [ + "TAX_RETURN", + "STOCK_PLAN_EXERCISE_CONFIRMATION", + "PORTFOLIO_STATEMENT", + "DIVIDEND_VOUCHER", + "BANK_STATEMENT" + ] + }, + { + "title": "INHERITANCE", + "description": "Document types accepted when `secondaryIncomeType` is `INHERITANCE`.", + "type": "string", + "enum": [ + "TAX_RETURN", + "GRANT_OF_PROBATE", + "WILL", + "TRUST_DEED" + ] + }, + { + "title": "PENSION", + "description": "Document types accepted when `secondaryIncomeType` is `PENSION`.", + "type": "string", + "enum": [ + "TAX_RETURN", + "PENSION_STATEMENT", + "BANK_STATEMENT" + ] + }, + { + "title": "PROPERTY_SALE", + "description": "Document types accepted when `secondaryIncomeType` is `PROPERTY_SALE`.", + "type": "string", + "enum": [ + "TAX_RETURN", + "SALE_CONTRACT", + "SETTLEMENT_STATEMENT", + "BANK_STATEMENT" + ] + }, + { + "title": "LOAN", + "description": "Document types accepted when `secondaryIncomeType` is `LOAN`.", + "type": "string", + "enum": [ + "LOAN_AGREEMENT", + "BANK_STATEMENT" + ] + }, + { + "title": "OTHER", + "description": "Document types accepted when `secondaryIncomeType` is `OTHER`.", + "type": "string", + "enum": [ + "GIFT_LETTER", + "SCHOLARSHIP", + "LEASE_AGREEMENT", + "BANK_STATEMENT", + "OTHER" + ] + } + ] + }, + "secondaryIncomeDescription": { + "type": [ + "string", + "null" + ], + "description": "Optional. A free-text description of the secondary income source.", + "example": "Payslip from a second, part-time job" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + }, + "examples": [ + [ + "document.pdf" + ] + ], + "description": "Upload the proof document.\n\nAccepted file types: `image/png` (`.png`), `image/jpeg` (`.jpg` or `.jpeg`) and `application/pdf` (`.pdf`). The content type must match the file extension.\n\n```json {% title=\"Example\" %}\n[\"document.pdf\"]\n```\n" + } + } + }, + "ssn-declaration": { + "title": "SSN_DECLARATION", + "description": "Declaration of the customer's US Social Security Number (SSN). This requirement only applies to customers in the US region.\n\nCustomers either provide their SSN or, if they don't have one, a reason why it is unavailable. Exactly one of `ssnNumber` or `ssnUnavailableReason` must be provided; the other must be `null`. Files are not required for either scenario.\n\nSee [SSN_DECLARATION](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#ssn_declaration) in the KYC requirement types guide for more details and sandbox test data.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "anyOf": [ + { + "title": "SSN available", + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"ssnNumber\": \"123-45-6789\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "ssnNumber" + ], + "properties": { + "ssnNumber": { + "type": "string", + "description": "The customer's 9-digit Social Security Number (including or excluding dashes).", + "example": "123-45-6789" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + { + "title": "SSN unavailable", + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"ssnUnavailableReason\": \"NON_US_CITIZEN\"\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "ssnUnavailableReason" + ], + "properties": { + "ssnUnavailableReason": { + "type": "string", + "description": "The reason the customer can't provide an SSN.", + "enum": [ + "NON_US_CITIZEN" + ], + "example": "NON_US_CITIZEN" + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + ] + } + } + }, + "tax-residency": { + "title": "TAX_RESIDENCY", + "description": "Users must declare all countries where they hold tax residency. While this is usually where a user lives and works, those with more complex setups (e.g. digital nomads) must list all applicable jurisdictions.\n\nDepending on the user's situation and the Wise entity they are onboarded to, there are three distinct submission scenarios for tax residency. Files are not required for any scenario.\n\nSee [TAX_RESIDENCY](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#tax_residency) in the KYC requirement types guide for more details and the TIN types accepted per country.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "anyOf": [ + { + "title": "Local Entity TIN Exemptions", + "description": "If a customer is onboarded to a local Wise entity, providing a TIN for that specific country is not required. View the full list of Wise Group Entities [here](https://wise.com/help/articles/2974131/what-are-the-wise-group-entities). If you are unsure which entity your customers are onboarded to, please contact your Account Manager.\n\n```json {% title=\"Example\" %}\n{\n \"data\": {\n \"taxInfoList\": [\n {\n \"taxCountry\": \"SG\"\n }\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "taxInfoList" + ], + "properties": { + "taxInfoList": { + "type": "array", + "description": "A list of tax residency objects for every country where the user is a tax resident.", + "examples": [ + [ + { + "taxCountry": "SG" + } + ] + ], + "items": { + "type": "object", + "required": [ + "taxCountry" + ], + "properties": { + "taxCountry": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code of the tax residency.", + "example": "SG" + } + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + { + "title": "Standard CRS Collection", + "description": "For customers not onboarded to a local Wise entity, a Tax Identification Number (TIN) is mandatory for all declared tax residencies. If a TIN cannot be provided, a `skipReason` must be given instead.\n\n```json {% title=\"Example\" %}\n{\n \"data\": {\n \"taxInfoList\": [\n {\n \"taxCountry\": \"SG\",\n \"taxId\": {\n \"type\": \"SG_NRIC\",\n \"number\": \"S1234567A\"\n }\n },\n {\n \"taxCountry\": \"BR\",\n \"skipReason\": \"TAX_EXEMPT\"\n }\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "taxInfoList" + ], + "properties": { + "taxInfoList": { + "type": "array", + "description": "A list of tax residency objects for every country where the user is a tax resident.", + "examples": [ + [ + { + "taxCountry": "SG", + "taxId": { + "type": "SG_NRIC", + "number": "S1234567A" + } + }, + { + "taxCountry": "BR", + "skipReason": "NO_TAXABLE_INCOME" + } + ] + ], + "items": { + "type": "object", + "required": [ + "taxCountry" + ], + "anyOf": [ + { + "title": "With TIN", + "required": [ + "taxId" + ] + }, + { + "title": "With skip reason", + "required": [ + "skipReason" + ] + } + ], + "properties": { + "taxCountry": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code of the tax residency.", + "example": "SG" + }, + "taxId": { + "type": "object", + "description": "An object containing tax identification details. Provide either `taxId` or `skipReason`.", + "required": [ + "type", + "number" + ], + "properties": { + "type": { + "type": "string", + "description": "The specific TIN identifier type for that country. Must be one of the types listed for the `taxCountry` in the [TIN types reference](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#tin-types-reference). Any other value is rejected.", + "example": "SG_NRIC" + }, + "number": { + "type": "string", + "description": "The actual tax identification number. Must match the format of the selected `type`.", + "example": "S1234567A" + } + } + }, + "skipReason": { + "type": "string", + "description": "Justification for not providing a TIN. Provide either `taxId` or `skipReason`.\n- `TAX_EXEMPT` — the customer's income is exempt from taxation.\n- `RETIRED_OR_UNEMPLOYED` — the customer is currently retired or unemployed.\n- `NO_TAXABLE_INCOME` — the customer does not have any taxable income.\n", + "enum": [ + "TAX_EXEMPT", + "RETIRED_OR_UNEMPLOYED", + "NO_TAXABLE_INCOME" + ] + } + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + }, + { + "title": "Golden Visa Declarations", + "description": "For customers whose only tax residency is in a Golden Visa sponsor country, a mandatory Golden Visa Declaration must be completed. All fields within the `goldenVisaDeclaration` object must be set to `true`. Refer to the [full list of Golden Visa countries](https://wise.com/us/blog/golden-visa-countries#which-countries-have-golden-visa-programs) to identify applicable jurisdictions. If any declaration value is `false`, the customer defaults to Standard CRS Collection and must provide a TIN.\n\n```json {% title=\"Example\" %}\n{\n \"data\": {\n \"taxInfoList\": [\n {\n \"taxCountry\": \"AE\",\n \"skipReason\": \"NO_TAXABLE_INCOME\"\n },\n {\n \"taxCountry\": \"AG\",\n \"skipReason\": \"NO_TAXABLE_INCOME\"\n },\n {\n \"taxCountry\": \"BS\",\n \"skipReason\": \"TAX_EXEMPT\"\n }\n ],\n \"goldenVisaDeclaration\": {\n \"NO_OTHER_RESIDENCE\": true,\n \"WITHIN_TIME_FRAME\": true,\n \"DID_NOT_FILE_INCOME\": true\n }\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "taxInfoList", + "goldenVisaDeclaration" + ], + "properties": { + "taxInfoList": { + "type": "array", + "description": "A list of tax residency objects for every country where the user is a tax resident.", + "examples": [ + [ + { + "taxCountry": "AE", + "skipReason": "NO_TAXABLE_INCOME" + }, + { + "taxCountry": "AG", + "skipReason": "NO_TAXABLE_INCOME" + }, + { + "taxCountry": "BS", + "skipReason": "TAX_EXEMPT" + } + ] + ], + "items": { + "type": "object", + "required": [ + "taxCountry" + ], + "properties": { + "taxCountry": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code of the tax residency.", + "example": "AE" + }, + "skipReason": { + "type": "string", + "description": "Justification for not providing a TIN.\n- `TAX_EXEMPT` — the customer's income is exempt from taxation.\n- `RETIRED_OR_UNEMPLOYED` — the customer is currently retired or unemployed.\n- `NO_TAXABLE_INCOME` — the customer does not have any taxable income.\n", + "enum": [ + "TAX_EXEMPT", + "RETIRED_OR_UNEMPLOYED", + "NO_TAXABLE_INCOME" + ] + } + } + } + }, + "goldenVisaDeclaration": { + "type": "object", + "description": "A set of affirmations required for users holding specific residency-by-investment visas. All values must be set to `true`.", + "required": [ + "NO_OTHER_RESIDENCE", + "WITHIN_TIME_FRAME", + "DID_NOT_FILE_INCOME" + ], + "properties": { + "NO_OTHER_RESIDENCE": { + "type": "boolean", + "description": "Customer does not hold residency rights in any other jurisdiction.", + "example": true + }, + "WITHIN_TIME_FRAME": { + "type": "boolean", + "description": "Customer did not spend more than 90 days in any other jurisdiction in the previous year.", + "example": true + }, + "DID_NOT_FILE_INCOME": { + "type": "boolean", + "description": "Customer did not file a tax return in any other jurisdiction during the previous year.", + "example": true + } + } + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + ] + } + } + }, + "use-case-countries": { + "title": "USE_CASE_COUNTRIES", + "description": "Country codes where the business intends to send money. If unsure, select the country codes that correspond with the target currencies.\n\nSee [USE_CASE_COUNTRIES](/guides/product/account-setup/customer-onboarding/kyc-requirement-types#use_case_countries) in the KYC requirement types guide for more details.\n", + "type": "object", + "required": [ + "submissionData" + ], + "properties": { + "submissionData": { + "description": "```json {% title=\"Example\" %}\n{\n \"data\": {\n \"useCaseCountries\": [\n \"usa\",\n \"gbr\",\n \"deu\"\n ]\n },\n \"version\": \"V1\",\n \"kycReviewId\": \"93a903ea-636c-4c86-a25c-cf6d2bd00e81\"\n}\n```\n", + "type": "object", + "required": [ + "data", + "version", + "kycReviewId" + ], + "properties": { + "data": { + "type": "object", + "required": [ + "useCaseCountries" + ], + "properties": { + "useCaseCountries": { + "type": "array", + "description": "Country codes in ISO 3166-1 alpha-3 standard.", + "items": { + "type": "string" + }, + "example": [ + "usa", + "gbr", + "deu" + ] + } + } + }, + "version": { + "$ref": "#/components/schemas/version" + }, + "kycReviewId": { + "$ref": "#/components/schemas/kyc-review-id" + } + } + } + } + }, + "request-body": { + "type": "object", + "description": "The request body depends on the `requirementKey`. Select the requirement type you are submitting to see its `submissionData` fields and whether `files` are needed.\n\nSee the [KYC requirement types](/guides/product/account-setup/customer-onboarding/kyc-requirement-types) guide for an overview of all requirement types.\n", + "anyOf": [ + { + "$ref": "#/components/schemas/select-requirement-type" + }, + { + "$ref": "#/components/schemas/account-intent" + }, + { + "$ref": "#/components/schemas/account-purpose" + }, + { + "$ref": "#/components/schemas/annual-volume" + }, + { + "$ref": "#/components/schemas/business-annual-income" + }, + { + "$ref": "#/components/schemas/business-authorisation-id" + }, + { + "$ref": "#/components/schemas/business-authorisation-letter" + }, + { + "$ref": "#/components/schemas/business-controlling-person" + }, + { + "$ref": "#/components/schemas/business-directors-check" + }, + { + "$ref": "#/components/schemas/business-income-classification" + }, + { + "$ref": "#/components/schemas/business-monthly-volume" + }, + { + "$ref": "#/components/schemas/business-registration-docs" + }, + { + "$ref": "#/components/schemas/business-shareholder-contact-details" + }, + { + "$ref": "#/components/schemas/business-shareholders-check" + }, + { + "$ref": "#/components/schemas/business-source-of-wealth" + }, + { + "$ref": "#/components/schemas/business-source-of-wealth-info" + }, + { + "$ref": "#/components/schemas/business-source-of-wealth-proof" + }, + { + "$ref": "#/components/schemas/business-ultimate-beneficial-owner-id" + }, + { + "$ref": "#/components/schemas/business-use-case" + }, + { + "$ref": "#/components/schemas/id-document" + }, + { + "$ref": "#/components/schemas/income" + }, + { + "$ref": "#/components/schemas/india-transfer-purpose" + }, + { + "$ref": "#/components/schemas/jpn-business-cert" + }, + { + "$ref": "#/components/schemas/jpn-personal-mynumber" + }, + { + "$ref": "#/components/schemas/legal-entity-shareholder" + }, + { + "$ref": "#/components/schemas/proof-of-trading-address" + }, + { + "$ref": "#/components/schemas/source-of-funds" + }, + { + "$ref": "#/components/schemas/source-of-wealth" + }, + { + "$ref": "#/components/schemas/source-of-wealth-info" + }, + { + "$ref": "#/components/schemas/source-of-wealth-proof" + }, + { + "$ref": "#/components/schemas/ssn-declaration" + }, + { + "$ref": "#/components/schemas/tax-residency" + }, + { + "$ref": "#/components/schemas/use-case-countries" + } + ] + }, "client-credentials-grant": { "type": "object", "required": [ @@ -34573,7 +39899,7 @@ "submission-data-file": { "type": "object", "title": "FILE_SUBMISSION Submission Data", - "description": "Submission data for FILE_SUBMISSION message type.\nUsed to attach previously uploaded files to a case.\n\n**Prerequisites:**\n- Files must be uploaded via `POST /cases/{caseId}/files` before submitting\n- Case must not be in RESOLVED or FAILED status\n- Files must belong to the specified profile\n- Files must have been uploaded by the same partner\n\n**Validation Rules:**\n- `profileId` is REQUIRED\n- `fileIds` is REQUIRED and must not be empty\n- `fileIds` must not contain duplicates\n- All file IDs must reference existing files\n- All files must belong to the specified `profileId`\n- All files must have been created by the submitting partner\n", + "description": "Submission data for FILE_SUBMISSION message type.\nUsed to attach previously uploaded files to a case.\n\n**Prerequisites:**\n- Files must be uploaded via `POST /cases/{caseId}/files` before submitting\n- Case must not be in RESOLVED or FAILED status\n- Files must belong to the specified profile\n\n**Validation Rules:**\n- `profileId` is REQUIRED\n- `fileIds` is REQUIRED and must not be empty\n- `fileIds` must not contain duplicates\n- All file IDs must reference existing files\n- All files must belong to the specified `profileId`\n", "properties": { "profileId": { "type": "integer", @@ -34746,6 +40072,586 @@ } ] }, + "listed-file": { + "type": "object", + "description": "Metadata for an uploaded file.", + "properties": { + "profileId": { + "type": "integer", + "format": "int64", + "description": "The ID of the profile this file belongs to.", + "example": 14556049 + }, + "fileId": { + "type": "string", + "format": "uuid", + "description": "Unique identifier of the uploaded file.", + "minLength": 36, + "maxLength": 36, + "example": "a1b2c3d4-e5f6-4789-abcd-ef1234567890" + }, + "fileName": { + "type": "string", + "description": "The name of the uploaded file.", + "maxLength": 128, + "example": "company-registration.pdf" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the file was uploaded.\nFormat: ISO 8601 datetime without timezone (server timezone is UTC).\n", + "example": "2026-09-30T10:00:00.123" + }, + "purpose": { + "type": "string", + "description": "The purpose of the file upload.", + "enum": [ + "GENERAL" + ], + "example": "GENERAL" + } + }, + "required": [ + "profileId", + "fileId", + "fileName", + "createdAt", + "purpose" + ] + }, + "file-list-response": { + "type": "object", + "description": "A page of files uploaded by your application and the total number of matching files.", + "properties": { + "files": { + "type": "array", + "description": "Collection of file metadata for the requested page. Ordered by `createdAt` descending and then `fileId` descending.\n", + "items": { + "$ref": "#/components/schemas/listed-file" + } + }, + "totalFiles": { + "type": "integer", + "format": "int64", + "minimum": 0, + "description": "Total number of files across all pages.", + "example": 3 + } + }, + "required": [ + "files", + "totalFiles" + ] + }, + "error-response-2": { + "type": "object", + "title": "Error Response", + "description": "Standard error response structure following RFC 7807 Problem Details.\n\nAll error responses include a `type` URI identifying the error category,\na human-readable `title`, and the HTTP `status` code.\n", + "properties": { + "type": { + "type": "string", + "description": "A URI reference that identifies the error type.\n\nCommon types:\n- `/errors/types/validation` - Request validation failed\n- `/errors/types/access` - Authentication or authorization error\n- `/errors/types/domain` - Domain-specific business rule violation\n", + "example": "/errors/types/validation" + }, + "title": { + "type": "string", + "description": "A short, human-readable summary of the error type.", + "example": "Validation Error" + }, + "status": { + "type": "integer", + "description": "The HTTP status code.", + "example": 400 + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the error.", + "example": "Unauthorized" + }, + "instance": { + "type": "string", + "description": "The request path that caused the error.", + "example": "/cases/files" + }, + "code": { + "type": "string", + "description": "A machine-readable error code for domain errors.", + "example": "forbidden" + } + }, + "required": [ + "type", + "title", + "status" + ] + }, + "file-list-validation-error": { + "allOf": [ + { + "$ref": "#/components/schemas/error-response-2" + }, + { + "type": "object", + "title": "File List Validation Error (400)", + "description": "Returned when the request fails validation.\n\n**Common causes:**\n- Page number is less than 1\n- Page size is less than 1 or greater than 100\n- A query parameter is not a valid integer\n- The specified profile is not associated with Partner\n", + "properties": { + "type": { + "example": "/errors/types/validation" + }, + "title": { + "example": "Validation Error" + }, + "status": { + "example": 400 + }, + "instance": { + "example": "/cases/files" + }, + "errors": { + "type": "array", + "description": "List of query parameter validation errors.", + "items": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "A machine-readable validation error code.", + "example": "parameter_invalid" + }, + "ref": { + "type": "string", + "description": "The query parameter that caused the validation error.", + "example": "pageNumber" + }, + "detail": { + "type": "string", + "description": "A human-readable description of the validation failure.", + "example": "Page number must be greater than or equal to 1" + } + }, + "required": [ + "code", + "ref", + "detail" + ] + } + } + }, + "required": [ + "errors" + ] + } + ] + }, + "error-401-unauthorized-2": { + "allOf": [ + { + "$ref": "#/components/schemas/error-response-2" + }, + { + "type": "object", + "title": "Unauthorized Error (401)", + "description": "Returned when authentication is missing or invalid.\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired or invalid bearer token\n", + "properties": { + "type": { + "example": "/errors/types/access" + }, + "title": { + "example": "Unauthorized" + }, + "status": { + "example": 401 + } + }, + "example": { + "type": "/errors/types/access", + "title": "Unauthorized", + "status": 401, + "detail": "Authentication required" + } + } + ] + }, + "error-403-forbidden-2": { + "allOf": [ + { + "$ref": "#/components/schemas/error-response-2" + }, + { + "type": "object", + "title": "Forbidden Error (403)", + "description": "Returned when the client does not have sufficient permissions.\n\n**Common causes:**\n- Client credentials do not have the required permission\n", + "properties": { + "type": { + "example": "/errors/types/access" + }, + "title": { + "example": "Forbidden" + }, + "status": { + "example": 403 + }, + "code": { + "example": "forbidden" + } + }, + "example": { + "type": "/errors/types/access", + "title": "Forbidden", + "status": 403, + "detail": "Unauthorized", + "code": "forbidden" + } + } + ] + }, + "file-purpose": { + "type": "string", + "description": "The purpose of the file upload.", + "enum": [ + "GENERAL" + ], + "example": "GENERAL" + }, + "file-upload-request": { + "type": "object", + "description": "Metadata for the file upload, sent as the `submissionData` part of the multipart request.\n", + "properties": { + "profileId": { + "type": "integer", + "format": "int64", + "description": "The ID of the profile you are providing the file for. If you are set up only with your own profile and do not have them for end customers you must use your own profileId.\n", + "example": 14556049 + }, + "purpose": { + "$ref": "#/components/schemas/file-purpose" + } + }, + "required": [ + "profileId", + "purpose" + ], + "example": { + "profileId": 14556049, + "purpose": "GENERAL" + } + }, + "file-upload-response": { + "type": "object", + "description": "Response returned after successfully uploading a file.", + "properties": { + "profileId": { + "type": "integer", + "format": "int64", + "description": "The ID of the profile this file belongs to.", + "example": 14556049 + }, + "fileId": { + "type": "string", + "format": "uuid", + "description": "Unique identifier of the uploaded file (UUID v4).", + "minLength": 36, + "maxLength": 36, + "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "fileName": { + "type": "string", + "description": "The original name of the uploaded file.", + "maxLength": 128, + "example": "company-registration.pdf" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the file was uploaded.\nFormat: ISO 8601 datetime without timezone (server timezone is UTC).\n", + "example": "2026-09-30T10:00:00.123" + }, + "purpose": { + "$ref": "#/components/schemas/file-purpose" + } + }, + "required": [ + "profileId", + "fileId", + "fileName", + "createdAt", + "purpose" + ] + }, + "validation-error-2": { + "type": "object", + "title": "Validation Error Detail", + "description": "Details about a specific field validation error.", + "properties": { + "code": { + "type": "string", + "description": "Machine-readable validation error code.\n\nPossible codes:\n- `parameter_missing` - A required parameter was not provided\n- `parameter_invalid` - A parameter value is invalid\n- `invalid_file_extension` - File type or extension is not allowed\n- `file_size_exceeds_max_limit` - File exceeds the maximum allowed size\n", + "example": "parameter_invalid" + }, + "ref": { + "type": "string", + "description": "The field that caused the validation error.", + "example": "purpose" + }, + "detail": { + "type": "string", + "description": "A human-readable description of the validation failure.", + "example": "Invalid purpose" + } + }, + "required": [ + "code", + "ref", + "detail" + ] + }, + "error-400-validation": { + "allOf": [ + { + "$ref": "#/components/schemas/error-response-2" + }, + { + "type": "object", + "title": "Validation Error (400)", + "description": "Returned when the request fails validation.\n\n**Common causes:**\n- Missing required fields (`profileId`, `purpose`)\n- Invalid `purpose` value\n- File is empty or missing\n- Unsupported file content type (only `application/pdf`, `image/jpeg`, `image/png` allowed)\n- File extension does not match the content type\n- File exceeds 15 MB size limit\n- File name exceeds 128 characters\n- You do not own the specified profile\n- File failed security scan (malware detected)\n", + "properties": { + "type": { + "example": "/errors/types/validation" + }, + "title": { + "example": "Validation Error" + }, + "status": { + "example": 400 + }, + "instance": { + "example": "/cases/files" + }, + "errors": { + "type": "array", + "description": "List of field-level validation errors.", + "items": { + "$ref": "#/components/schemas/validation-error-2" + } + } + }, + "example": { + "type": "/errors/types/validation", + "title": "Validation Error", + "status": 400, + "instance": "/cases/files", + "errors": [ + { + "code": "parameter_missing", + "ref": "purpose", + "detail": "purpose must be provided" + } + ] + } + } + ] + }, + "error-429-too-many-requests": { + "allOf": [ + { + "$ref": "#/components/schemas/error-response-2" + }, + { + "type": "object", + "title": "Too Many Requests Error (429)", + "description": "Returned when the rate limit for file uploads has been exceeded.\n\n**Resolution:**\n- Wait before retrying the upload\n", + "properties": { + "type": { + "example": "/errors/types/domain" + }, + "title": { + "example": "Too Many Requests" + }, + "status": { + "example": 429 + }, + "code": { + "example": "rate_limit_exceeded" + } + }, + "example": { + "type": "/errors/types/domain", + "title": "Too Many Requests", + "status": 429, + "detail": "Too many files uploaded recently. Please try again later.", + "instance": "/cases/files", + "code": "rate_limit_exceeded" + } + } + ] + }, + "Address-2": { + "type": "object", + "properties": { + "addressFirstLine": { + "type": "string" + }, + "city": { + "type": "string" + }, + "country": { + "type": "string" + }, + "postCode": { + "type": "string" + }, + "state": { + "type": "string" + } + } + }, + "AccountOwnerDetails": { + "type": "object", + "properties": { + "address": { + "$ref": "#/components/schemas/Address-2" + }, + "email": { + "type": "string", + "format": "email", + "maxLength": 254, + "minLength": 0 + } + } + }, + "InitialiseInstrumentRequest": { + "type": "object", + "properties": { + "accountHolderName": { + "type": "string" + }, + "accountNumber": { + "type": "string" + }, + "accountOwnerDetails": { + "$ref": "#/components/schemas/AccountOwnerDetails" + }, + "accountType": { + "type": "string" + }, + "bankCode": { + "type": "string" + }, + "branchCode": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "required": [ + "accountNumber", + "type" + ] + }, + "AccountOwnerDetailsDto": { + "type": "object", + "properties": { + "city": { + "type": "string" + }, + "companyName": { + "type": "string" + }, + "country": { + "type": "string" + }, + "firstLine": { + "type": "string" + }, + "postCode": { + "type": "string" + }, + "state": { + "type": "string" + } + } + }, + "PaymentInstrumentDetailsResource": { + "type": "object", + "properties": { + "accountNumber": { + "type": "string" + }, + "accountOwnerDetails": { + "$ref": "#/components/schemas/AccountOwnerDetailsDto" + }, + "bankCode": { + "type": "string" + }, + "bankName": { + "type": "string" + }, + "branchCode": { + "type": "string" + }, + "disconnectReason": { + "type": "string" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "reference": { + "type": "string" + }, + "status": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "PayinSessionPayinInitiationResource": { + "type": "object", + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "failureReason": { + "type": "string" + }, + "id": { + "type": "string" + }, + "payinSessionId": { + "type": "string" + }, + "paymentInstrumentId": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "PayinSessionPayinInitiationRequest": { + "type": "object", + "properties": { + "payinSessionId": { + "type": "string" + }, + "reference": { + "type": "string" + } + }, + "required": [ + "payinSessionId" + ] + }, "address": { "type": "object", "description": "Address associated with a profile.", @@ -35160,6 +41066,16 @@ "description": "Address post code.", "example": "FK 12345" }, + "city": { + "type": "string", + "description": "City of residential address.", + "example": "Phoenix" + }, + "state": { + "type": "string", + "description": "State or region of residential address.", + "example": "AZ" + }, "ownershipPercentage": { "type": [ "integer", @@ -35937,7 +41853,7 @@ }, "confirmations": { "type": "object", - "description": "Contains verification results for the recipient's details. Only populated for currencies with recipient verification enabled (CNY, KRW, INR, IDR, EUR). \n\nSee the [Recipient verification guides](/guides/product/send-money/recipient-verification) for details about how to handle this verification data by currency.\n", + "description": "Contains verification results for the recipient's details. Only populated for currencies with recipient verification enabled (CNY, KRW, INR, IDR, EUR). \n\nSee the [Recipient verification guides](/guides/product/send-money/recipients/recipient-verification) for details about how to handle this verification data by currency.\n", "properties": { "acceptedOutcomes": { "type": "boolean", @@ -36474,7 +42390,7 @@ }, "confirmations": { "type": "object", - "description": "Contains verification results for the recipient's details. Only populated for currencies with recipient verification enabled (CNY, KRW, INR, IDR, EUR). \n\nSee the [Recipient verification guides](/guides/product/send-money/recipient-verification) for details about how to handle this verification data by currency.\n", + "description": "Contains verification results for the recipient's details. Only populated for currencies with recipient verification enabled (CNY, KRW, INR, IDR, EUR). \n\nSee the [Recipient verification guides](/guides/product/send-money/recipients/recipient-verification) for details about how to handle this verification data by currency.\n", "properties": { "acceptedOutcomes": { "type": "boolean", @@ -36575,7 +42491,538 @@ } } }, - "Address-2": { + "CurrencyCode": { + "type": "string", + "description": "ISO 4217 currency code", + "pattern": "^[A-Z]{3}$", + "example": "USD" + }, + "settlement-allocation-request": { + "type": "object", + "required": [ + "paymentReference", + "expectedTotalAmount", + "currency" + ], + "properties": { + "paymentReference": { + "type": "string", + "description": "Unique payment reference for the allocation request", + "example": "PAY-2024-001234" + }, + "expectedTotalAmount": { + "type": "number", + "format": "decimal", + "description": "Expected total amount for the allocation", + "example": 10000 + }, + "currency": { + "$ref": "#/components/schemas/CurrencyCode", + "description": "Currency code" + } + } + }, + "SettlementAllocationState": { + "type": "string", + "description": "State of a funding allocation.", + "enum": [ + "NEW", + "MATCHING_FUNDS", + "MATCHED", + "MISMATCHED", + "PARTIALLY_COMPLETED", + "COMPLETED", + "CANCELLED" + ] + }, + "settlement-allocation-response": { + "type": "object", + "required": [ + "id", + "expectedTotalAmount", + "currency", + "state", + "paymentReference", + "createdAt", + "updatedAt" + ], + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier of the settlement allocation request" + }, + "expectedTotalAmount": { + "type": "number", + "format": "decimal", + "description": "Expected total amount", + "example": 10000 + }, + "currency": { + "$ref": "#/components/schemas/CurrencyCode", + "description": "Currency code" + }, + "state": { + "$ref": "#/components/schemas/SettlementAllocationState" + }, + "paymentReference": { + "type": "string", + "description": "Payment reference", + "example": "PAY-2024-001234" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + } + } + }, + "RecipientType": { + "type": "string", + "description": "Type of recipient for a payment intent.", + "enum": [ + "SELLER", + "PARTNER_FEE" + ] + }, + "AllocationType": { + "type": "string", + "description": "Type of allocation for a payment intent.", + "enum": [ + "CREDIT", + "DEBIT" + ] + }, + "PaymentIntentState": { + "type": "string", + "description": "State of a payment intent.", + "enum": [ + "NEW", + "PARTIALLY_LEDGERED", + "LEDGERED", + "PARTIALLY_SETTLED", + "SETTLED", + "CANCELLED" + ] + }, + "FundingSource": { + "type": "string", + "description": "Source of funding for a payment intent.", + "enum": [ + "WISE_COLLECTION_ACCOUNT", + "PARTNER_DEFICIT_ACCOUNT", + "SPLIT", + "UNDETERMINED" + ] + }, + "PaymentIntentResponse": { + "type": "object", + "description": "Details of a payment intent associated with a settlement allocation.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the payment intent in the UUID format.", + "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "allocationId": { + "type": "string", + "description": "Unique identifier of the associated settlement allocation in the UUID format.", + "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + }, + "partnerEntityId": { + "type": "string", + "description": "Partner entity identifier.", + "example": "PARTNER-001" + }, + "profileId": { + "type": "string", + "description": "Profile identifier.", + "example": "12345678" + }, + "recipientType": { + "$ref": "#/components/schemas/RecipientType", + "description": "Type of recipient." + }, + "sourceAmount": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": 0, + "description": "Source amount of the payment.", + "format": "decimal", + "example": 100 + }, + "sourceCurrency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Source currency code (ISO 4217).", + "example": "EUR" + }, + "targetAmount": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": 0, + "description": "Target amount of the payment.", + "format": "decimal", + "example": 85 + }, + "targetCurrency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Target currency code (ISO 4217).", + "example": "GBP" + }, + "allocationType": { + "$ref": "#/components/schemas/AllocationType", + "description": "Type of allocation." + }, + "paymentReference": { + "type": "string", + "description": "Payment reference.", + "example": "REF-001" + }, + "reason": { + "type": "string", + "description": "Reason for the payment.", + "example": "Invoice payment" + }, + "state": { + "$ref": "#/components/schemas/PaymentIntentState", + "description": "Current state of the payment intent." + }, + "fundingSource": { + "$ref": "#/components/schemas/FundingSource", + "description": "Source of funding for the payment." + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the payment intent was created.", + "format": "date-time", + "example": "2026-07-10T10:35:16.000Z" + }, + "updatedAt": { + "type": "string", + "description": "Timestamp when the payment intent was last updated.", + "format": "date-time", + "example": "2026-07-10T10:45:41.000Z" + } + } + }, + "GetSettlementAllocationResponseContent": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the settlement allocation.", + "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + }, + "expectedTotalAmount": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": 0, + "description": "Expected total amount for the allocation.", + "format": "decimal", + "example": 1000.5 + }, + "currency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Currency code for the allocation (ISO 4217).", + "example": "EUR" + }, + "state": { + "$ref": "#/components/schemas/SettlementAllocationState", + "description": "Current state of the settlement allocation." + }, + "paymentReference": { + "type": "string", + "description": "Unique payment reference for the settlement allocation.", + "example": "PAY-123456" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the settlement allocation was created.", + "format": "date-time", + "example": "2026-07-10T10:30:16.000Z" + }, + "updatedAt": { + "type": "string", + "description": "Timestamp when the settlement allocation was last updated.", + "format": "date-time", + "example": "2026-07-10T11:00:41.000Z" + }, + "paymentIntents": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentIntentResponse" + }, + "description": "List of payment intents associated with the allocation. Only included when includePaymentIntents is true." + }, + "nextPageToken": { + "type": "string", + "description": "Token for fetching the next page of payment intents. Null if no more pages.", + "example": "def456" + } + } + }, + "GetPaymentIntentResponseContent": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the payment intent.", + "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "allocationId": { + "type": "string", + "description": "Unique identifier of the associated settlement allocation.", + "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + }, + "partnerEntityId": { + "type": "string", + "description": "Partner entity identifier.", + "example": "PARTNER-001" + }, + "profileId": { + "type": "string", + "description": "Profile identifier.", + "example": "12345678" + }, + "recipientType": { + "$ref": "#/components/schemas/RecipientType", + "description": "Type of recipient." + }, + "sourceAmount": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": 0, + "description": "Source amount of the payment.", + "format": "decimal", + "example": 100 + }, + "sourceCurrency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Source currency code (ISO 4217).", + "example": "EUR" + }, + "targetAmount": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": 0, + "description": "Target amount of the payment.", + "format": "decimal", + "example": 85 + }, + "targetCurrency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Target currency code (ISO 4217).", + "example": "GBP" + }, + "allocationType": { + "$ref": "#/components/schemas/AllocationType", + "description": "Type of allocation." + }, + "paymentReference": { + "type": "string", + "description": "Payment reference.", + "example": "REF-001" + }, + "reason": { + "type": "string", + "description": "Reason for the payment.", + "example": "Invoice payment" + }, + "state": { + "$ref": "#/components/schemas/PaymentIntentState", + "description": "Current state of the payment intent." + }, + "fundingSource": { + "$ref": "#/components/schemas/FundingSource", + "description": "Source of funding for the payment." + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the payment intent was created.", + "format": "date-time", + "example": "2026-07-10T10:35:16.000Z" + }, + "updatedAt": { + "type": "string", + "description": "Timestamp when the payment intent was last updated.", + "format": "date-time", + "example": "2026-07-10T10:45:41.000Z" + } + } + }, + "delivery_update": { + "type": "string", + "enum": [ + "partner_accepted", + "recipient_provider_accepted", + "scheme_settled", + "account_credited", + "funds_available" + ], + "description": "The delivery signal to simulate. Must be a member of `delivery_update_path`, but need not be its last item." + }, + "delivery-update-request": { + "type": "object", + "required": [ + "delivery_update_path", + "delivery_update" + ], + "properties": { + "scheme": { + "type": [ + "string", + "null" + ], + "enum": [ + "sepa_instant_credit_transfer", + null + ], + "description": "Payment scheme to include in the observation. May be omitted or null." + }, + "delivery_update_path": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "$ref": "#/components/schemas/delivery_update" + }, + "description": "Delivery signals supported by the simulated route, not a history of events.\nSelect one or more distinct values in this progression order:\n`partner_accepted`, `recipient_provider_accepted`, `scheme_settled`,\n`account_credited`, `funds_available`. Values may be skipped.\nThe service validates the order and requires this array to contain `delivery_update`.\n" + }, + "delivery_update": { + "type": "string", + "enum": [ + "partner_accepted", + "recipient_provider_accepted", + "scheme_settled", + "account_credited", + "funds_available" + ], + "description": "The delivery signal to simulate. Must be a member of `delivery_update_path`, but need not be its last item." + }, + "estimated_delivery_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Optional estimated delivery time. May be omitted or null. Published timestamps are truncated to milliseconds." + } + } + }, + "delivery-update-response": { + "type": "object", + "required": [ + "observation_id", + "occurred_at" + ], + "properties": { + "observation_id": { + "type": "string", + "format": "uuid", + "description": "Server-generated observation identifier. Matches `data.observation_id` in the webhook." + }, + "occurred_at": { + "type": "string", + "format": "date-time", + "description": "Server-generated observation time in UTC with millisecond precision. Matches `data.occurred_at` in the webhook." + } + } + }, + "simulation-error": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Description of the error, when available." + }, + "path": { + "type": "string", + "description": "Field associated with a validation error, when available." + }, + "arguments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Arguments associated with the error." + } + } + }, + "simulation-errors": { + "type": "object", + "required": [ + "errors" + ], + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/simulation-error" + } + } + } + }, + "SimulateSettlementAllocationsFundsRequestContent": { + "type": "object", + "properties": { + "amount": { + "type": "number", + "minimum": 0.01, + "exclusiveMinimum": 0, + "description": "The amount to be simulated as received.", + "format": "decimal", + "example": 1000.5 + }, + "currency": { + "type": "string", + "maxLength": 3, + "minLength": 3, + "pattern": "^[A-Z]{3}$", + "description": "Currency code (ISO 4217).", + "example": "JPY" + }, + "paymentReference": { + "type": "string", + "minLength": 1, + "pattern": "\\S", + "description": "Payment reference for the settlement allocation. Must start with 'BYOPSP_'.", + "example": "BYOPSP_test-client_A1B2C3" + } + }, + "required": [ + "amount", + "currency", + "paymentReference" + ] + }, + "Address-3": { "type": "object", "properties": { "addressFirstLine": { @@ -36698,15 +43145,20 @@ "senderAddress": { "maxLength": 255, "description": "Sender address.", - "$ref": "#/components/schemas/Address-2" + "$ref": "#/components/schemas/Address-3" }, "beneficiaryAddress": { "description": "Beneficiary address.", - "$ref": "#/components/schemas/Address-2" + "$ref": "#/components/schemas/Address-3" } } }, - "Address-3": { + "Bic": { + "description": "Business Identifier Code, also known as Swift Code.", + "type": "string", + "pattern": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$" + }, + "Address-4": { "type": "object", "properties": { "addressLine": { @@ -36807,7 +43259,7 @@ "description": "Address of the sender's bank.", "allOf": [ { - "$ref": "#/components/schemas/Address-3" + "$ref": "#/components/schemas/Address-4" }, { "type": "object", @@ -36933,7 +43385,7 @@ "description": "Address of the sender's bank.", "allOf": [ { - "$ref": "#/components/schemas/Address-3" + "$ref": "#/components/schemas/Address-4" }, { "type": "object", @@ -37012,7 +43464,7 @@ "description": "Address of the ultimate beneficiary.", "allOf": [ { - "$ref": "#/components/schemas/Address-3" + "$ref": "#/components/schemas/Address-4" }, { "type": "object", @@ -37057,7 +43509,7 @@ "description": "Address of the sender.", "allOf": [ { - "$ref": "#/components/schemas/Address-3" + "$ref": "#/components/schemas/Address-4" }, { "type": "object", @@ -37650,7 +44102,7 @@ } } }, - "validation-error-2": { + "validation-error-3": { "title": "Validation Error", "type": "object", "required": [ @@ -37834,7 +44286,7 @@ }, "status": { "type": "string", - "description": "Transfer current status. See [Tracking Transfers](/guides/product/send-money/tracking-transfers) for all possible statuses.", + "description": "Transfer current status.\nSee [Transfer statuses](/guides/product/send-money/tracking/transfer-statuses) for all possible statuses.", "example": "incoming_payment_waiting" }, "reference": { @@ -38319,7 +44771,7 @@ } } }, - "Address-4": { + "Address-5": { "type": "object", "properties": { "firstLine": { @@ -38366,9 +44818,7 @@ "properties": { "reference": { "type": "string", - "minLength": 1, - "pattern": "\\S", - "description": "Unique customer ID in your system. This allows us to uniquely identify each originator", + "description": "Unique customer ID in your system. This allows Wise to identify each originator for compliance purposes. All transfers sent by the same originator must use the same `originator.reference` value.", "example": "CST-2991992" }, "name": { @@ -38379,8 +44829,7 @@ "type": "string", "description": "Payment originator date of birth", "format": "date", - "example": "1977-07-01", - "x-temporal-constraint": "past" + "example": "1977-07-01" }, "nationality": { "type": "string", @@ -38393,7 +44842,7 @@ "example": "23456789" }, "address": { - "$ref": "#/components/schemas/Address-4", + "$ref": "#/components/schemas/Address-5", "description": "Payment originator address" } }, @@ -38431,9 +44880,7 @@ "properties": { "reference": { "type": "string", - "minLength": 1, - "pattern": "\\S", - "description": "Unique customer ID in your system. This allows us to uniquely identify each originator", + "description": "Unique customer ID in your system. This allows Wise to identify each originator for compliance purposes. All transfers sent by the same originator must use the same `originator.reference` value.", "example": "CST-2991992" }, "name": { @@ -38459,7 +44906,7 @@ "example": "23456789" }, "address": { - "$ref": "#/components/schemas/Address-4", + "$ref": "#/components/schemas/Address-5", "description": "Payment originator address" } }, @@ -39214,62 +45661,6 @@ "EUR_T2" ] }, - "Iso20022Address": { - "type": "object", - "description": "An ISO 20022 structured address with optional free-form address lines.", - "properties": { - "streetName": { - "type": "string", - "description": "Street name", - "example": "Clifton Street, London" - }, - "buildingNumber": { - "type": "string", - "description": "Building number", - "example": "65" - }, - "townName": { - "type": "string", - "description": "City or town", - "example": "London" - }, - "postCode": { - "type": "string", - "description": "Postal or ZIP code", - "example": "EC2A 4JE" - }, - "countrySubDivision": { - "type": "string", - "description": "State, province, or region", - "example": "Greater London" - }, - "country": { - "type": "string", - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "description": "ISO 3166-1 alpha-2 country code", - "example": "GB" - }, - "addressLines": { - "type": "array", - "items": { - "type": "string" - }, - "maxItems": 2, - "description": "Address lines. May be empty; up to two lines can be populated alongside structured fields.", - "example": [ - "1st Floor, Worship Square", - "EV2A 4JE" - ] - } - }, - "required": [ - "addressLines", - "country", - "townName" - ] - }, "AccountInfo": { "type": "object", "properties": { @@ -40931,7 +47322,7 @@ }, "current_state": { "type": "string", - "description": "Current transfer status. See [Transfer Statuses](/guides/product/send-money/tracking-transfers) for possible values.\n", + "description": "Current transfer status. See [Transfer statuses](/guides/product/send-money/tracking/transfer-statuses) for possible values.\n", "example": "processing" }, "previous_state": { @@ -41014,7 +47405,7 @@ }, "current_state": { "type": "string", - "description": "Current transfer status. See [Transfer Statuses](/guides/product/send-money/tracking-transfers) for possible values.\n", + "description": "Current transfer status. See [Transfer statuses](/guides/product/send-money/tracking/transfer-statuses) for possible values.\n", "example": "processing" }, "previous_state": { @@ -41530,6 +47921,102 @@ } }, "v4.0.0-7": { + "title": "Schema version 4.0.0", + "type": "object", + "required": [ + "schema_version", + "event_type", + "subscription_id", + "data" + ], + "properties": { + "schema_version": { + "type": "string", + "description": "Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).", + "enum": [ + "4.0.0" + ], + "example": "4.0.0" + }, + "subscription_id": { + "type": "string", + "format": "uuid", + "description": "ID of the webhook subscription that triggered this event.", + "example": "01234567-89ab-cdef-0123-456789abcdef" + }, + "event_type": { + "type": "string", + "description": "Event type identifier", + "example": "allocations#state-changed" + }, + "sent_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was sent.", + "example": "2020-01-01T12:34:56.123Z" + }, + "data": { + "type": "object", + "properties": { + "resource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier of webhook notification" + }, + "event_type": { + "type": "string", + "description": "Event type identifier.", + "example": "funds-allocation-state-change" + }, + "occurred_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the state change occurred.", + "example": "2020-01-01T12:34:56.789Z" + }, + "data": { + "type": "object", + "description": "Details of the allocation state change.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier of the settlement allocation request" + }, + "paymentReference": { + "type": "string", + "description": "Reference identifier for the payment.", + "example": "payment-ref-12345" + }, + "previousState": { + "type": "string", + "description": "Previous state of the allocation request.", + "example": "NEW", + "$ref": "#/components/schemas/SettlementAllocationState" + }, + "newState": { + "type": "string", + "description": "New state of the allocation request.", + "$ref": "#/components/schemas/SettlementAllocationState", + "example": "MATCHING_FUNDS" + }, + "clientKey": { + "type": "string", + "description": "Client key identifying the partner application.", + "example": "test-client-key" + } + } + } + } + } + } + } + } + }, + "v4.0.0-8": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -41685,7 +48172,7 @@ } } }, - "v4.0.0-8": { + "v4.0.0-9": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -41879,7 +48366,7 @@ } } }, - "v4.0.0-9": { + "v4.0.0-10": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -42161,7 +48648,7 @@ } } }, - "v4.0.0-10": { + "v4.0.0-11": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -42367,7 +48854,7 @@ } } }, - "v4.0.0-11": { + "v4.0.0-12": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -43705,7 +50192,7 @@ } } }, - "v4.0.0-12": { + "v4.0.0-13": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -43814,7 +50301,7 @@ } } }, - "v4.0.0-13": { + "v4.0.0-14": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -43990,7 +50477,7 @@ } } }, - "v4.0.0-14": { + "v4.0.0-15": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -44150,7 +50637,7 @@ } } }, - "v4.0.0-15": { + "v4.0.0-16": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -44286,7 +50773,7 @@ } } }, - "v4.0.0-16": { + "v4.0.0-17": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -44463,12 +50950,12 @@ }, "state": { "type": "string", - "description": "Status of the KYC Review. See [KYC review status](/guides/product/kyc/wise-kyc/hosted-kyc/kyc-review-status.md) for possible values.\n", + "description": "Status of the KYC Review. See [KYC review statuses](/guides/product/account-setup/customer-onboarding/api-hybrid-kyc#kyc-review-statuses) for possible values.\n", "example": "WAITING_CUSTOMER_INPUT" }, "prevState": { "type": "string", - "description": "Previous status of the KYC review. See [KYC review status](/guides/product/kyc/wise-kyc/hosted-kyc/kyc-review-status.md) for possible values.\n", + "description": "Previous status of the KYC review. See [KYC review statuses](/guides/product/account-setup/customer-onboarding/api-hybrid-kyc#kyc-review-statuses) for possible values.\n", "example": "WAITING_CUSTOMER_INPUT" }, "profileId": { @@ -44591,7 +51078,7 @@ } } }, - "v4.0.0-17": { + "v4.0.0-18": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -44634,7 +51121,7 @@ }, "state": { "type": "string", - "description": "Status of the KYC Review. See [KYC Review Status](/guides/product/kyc/wise-kyc/hosted-kyc/kyc-review-status.md) for possible values.\n", + "description": "Status of the KYC Review. See [KYC review statuses](/guides/product/account-setup/customer-onboarding/api-hybrid-kyc#kyc-review-statuses) for possible values.\n", "example": "WAITING_CUSTOMER_INPUT" }, "profileId": { @@ -44785,7 +51272,7 @@ }, "state": { "type": "string", - "description": "Status of the KYC Review. See [KYC Review Status](/guides/product/kyc/wise-kyc/hosted-kyc/kyc-review-status.md) for possible values.\n", + "description": "Status of the KYC Review. See [KYC review statuses](/guides/product/account-setup/customer-onboarding/api-hybrid-kyc#kyc-review-statuses) for possible values.\n", "example": "WAITING_CUSTOMER_INPUT" }, "profileId": { @@ -44893,9 +51380,10 @@ } } }, - "v4.0.0-18": { + "v4.0.0-19": { "title": "Schema version 4.0.0", "type": "object", + "deprecated": true, "properties": { "schema_version": { "type": "string", @@ -44987,6 +51475,7 @@ "v2.0.0-18": { "title": "Schema version 2.0.0", "type": "object", + "deprecated": true, "properties": { "schema_version": { "type": "string", @@ -45075,7 +51564,7 @@ } } }, - "v4.0.0-19": { + "v4.0.0-20": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -45477,7 +51966,7 @@ } } }, - "v4.0.0-20": { + "v4.0.0-21": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -45623,7 +52112,7 @@ } } }, - "v4.0.0-21": { + "v4.0.0-22": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -45924,7 +52413,7 @@ } } }, - "v4.0.0-22": { + "v4.0.0-23": { "title": "Schema version 4.0.0", "type": "object", "deprecated": true, @@ -46146,7 +52635,92 @@ } } }, - "Address-5": { + "v4.0.0-24": { + "title": "Schema version 4.0.0", + "type": "object", + "required": [ + "schema_version", + "event_type", + "subscription_id", + "data" + ], + "properties": { + "schema_version": { + "type": "string", + "description": "Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).", + "enum": [ + "4.0.0" + ], + "example": "4.0.0" + }, + "subscription_id": { + "type": "string", + "format": "uuid", + "description": "ID of the webhook subscription that triggered this event.", + "example": "01234567-89ab-cdef-0123-456789abcdef" + }, + "event_type": { + "type": "string", + "description": "Event type identifier", + "example": "settlement#funds-received" + }, + "sent_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was sent.", + "example": "2020-01-01T12:34:56.123Z" + }, + "data": { + "type": "object", + "properties": { + "resource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for this funds received event.", + "example": "a0a727a4-3c77-46b2-91be-1089195d16c3" + }, + "occurred_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the funds were received.", + "example": "2020-01-01T12:34:56.789Z" + }, + "data": { + "type": "object", + "description": "Details of the received funds.", + "properties": { + "amount": { + "type": "number", + "description": "Amount of funds received.", + "example": 10000 + }, + "currency": { + "$ref": "#/components/schemas/CurrencyCode", + "description": "Currency code of the received funds (ISO 4217).", + "example": "USD" + }, + "clientKey": { + "type": "string", + "description": "Client key identifying the partner application.", + "example": "test-client-key" + }, + "paymentReference": { + "type": "string", + "description": "Reference identifier for the payment.", + "example": "payment-ref-12345" + } + } + } + } + } + } + } + } + }, + "Address-6": { "type": "object", "description": "Structured address details.", "properties": { @@ -46231,7 +52805,7 @@ "description": "Identifier within the clearing system specified by `clearing_system_code`." }, "address": { - "$ref": "#/components/schemas/Address-5", + "$ref": "#/components/schemas/Address-6", "description": "Bank or financial institution address." } } @@ -46246,7 +52820,7 @@ "maxLength": 140 }, "address": { - "$ref": "#/components/schemas/Address-5", + "$ref": "#/components/schemas/Address-6", "description": "Party address." }, "account": { @@ -46368,7 +52942,7 @@ "description": "Identifier within the clearing system specified by `clearing_system_code`." }, "address": { - "$ref": "#/components/schemas/Address-5", + "$ref": "#/components/schemas/Address-6", "description": "Bank or financial institution address." } } @@ -46383,7 +52957,7 @@ "maxLength": 140 }, "address": { - "$ref": "#/components/schemas/Address-5", + "$ref": "#/components/schemas/Address-6", "description": "Party address." }, "account": { @@ -47835,7 +54409,7 @@ } } }, - "v4.0.0-23": { + "v4.0.0-25": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -48677,7 +55251,7 @@ } } }, - "v4.0.0-24": { + "v4.0.0-26": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -48767,7 +55341,7 @@ } } }, - "v4.0.0-25": { + "v4.0.0-27": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -48985,7 +55559,7 @@ } } }, - "v4.0.0-26": { + "v4.0.0-28": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -49214,7 +55788,7 @@ } } }, - "v4.0.0-27": { + "v4.0.0-29": { "title": "Schema version 4.0.0", "type": "object", "properties": { @@ -49266,7 +55840,7 @@ } } }, - "v4.0.0-28": { + "v4.0.0-30": { "title": "Schema version 4.0.0", "type": "object", "required": [ @@ -49382,33 +55956,6 @@ } } } - }, - "securitySchemes": { - "UserToken": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "User Access Token for making API calls on behalf of a Wise user.\n\nCan be obtained via two OAuth 2.0 flows:\n- **registration_code grant**: For partners creating users via API\n- **authorization_code grant**: For partners using Wise's authorization page\n\nAccess tokens are valid for 12 hours and can be refreshed using a refresh token.\n" - }, - "PersonalToken": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "Personal API Token for individual personal or small business users.\nGenerated from Wise.com > Settings > Connect and manage apps > API tokens.\nHas limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).\n" - }, - "ClientCredentialsToken": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "Application-level token for partner operations that don't require a specific user context, such as bulk settlement and card spend controls.\n\nObtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.\n\nValid for 12 hours. No refresh token — fetch a new token when expired.\n\nSee [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.\n" - }, - "BasicAuth": { - "type": "http", - "scheme": "basic", - "x-defaultUsername": "", - "x-defaultPassword": "", - "description": "Basic Authentication using your Client ID and Client Secret as the username and password.\n\nClient credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.\n" - } } } } \ No newline at end of file