docs: add Wise provider integration guide #98
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| --- | ||
| title: Wise | ||
| description: Connect your Wise multi-currency account using a personal API token | ||
| --- | ||
|
|
||
| Wise integration connects your Wise multi-currency account to Sure using a personal API token. Sure syncs your currency balances, Jars (savings pots), transfers, and Wise Assets activity directly from the Wise API — no OAuth flow required. | ||
|
|
||
| ## How it works | ||
|
|
||
| 1. You create a personal API token in Wise and paste it into Sure | ||
| 2. Sure fetches the profiles (personal and/or business) available to that token | ||
| 3. You choose which profile(s) to connect — each becomes its own connection in Sure | ||
| 4. Sure discovers every currency balance and Jar under the connected profile(s) | ||
| 5. You link each discovered balance to a new or existing Sure account | ||
| 6. Syncs then run automatically, pulling balances, transfers, and Jar activity | ||
|
|
||
| ## Setting up Wise | ||
|
|
||
| 1. Sign in to [wise.com](https://wise.com) | ||
| 2. Go to **Settings → API tokens** | ||
| 3. Create a new personal API token with read-only access | ||
| 4. In Sure, go to **Settings > Providers**, find the **Wise** panel, and paste the token | ||
| 5. If the token has access to more than one profile (for example, a personal and a business profile), select which ones to connect — Sure creates a separate connection for each | ||
| 6. Open **Set Up Accounts** on the new connection and link each currency balance to a Sure account | ||
|
|
||
| <Note> | ||
| For testing, Wise provides a sandbox environment at `https://api.sandbox.transferwise.tech`. Set `WISE_BASE_URL` in your Sure environment to point at it instead of the default live API (`https://api.wise.com`). | ||
| </Note> | ||
|
Comment on lines
+26
to
+28
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== providers/wise.mdx =="
if [ -f providers/wise.mdx ]; then
nl -ba providers/wise.mdx | sed -n '1,80p'
else
echo "providers/wise.mdx not found"
fi
echo
echo "== WISE_BASE_URL references =="
rg -n --hidden --glob '!node_modules' --glob '!dist' --glob '!build' 'WISE_BASE_URL|api\.sandbox\.transferwise\.tech|wise-sandbox|sandbox\.transferwise|TRANSFERWISE' .
echo
echo "== Wise-related provider docs files =="
fd -i 'wise|transferwise|providers' . -t f | sed -n '1,100p'Repository: we-promise/docs Length of output: 218 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== providers/wise.mdx =="
if [ -f providers/wise.mdx ]; then
cat -n providers/wise.mdx | sed -n '1,120p'
else
echo "providers/wise.mdx not found"
fi
echo
echo "== WISE_BASE_URL and Wise sandbox references =="
grep -RIn --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build \
-E 'WISE_BASE_URL|api\.sandbox\.transferwise\.tech|api\.wise-sandbox\.com|wise-sandbox|transferwise' . | sed -n '1,200p'
echo
echo "== Candidate provider files =="
find . -path './node_modules' -prune -o -path './dist' -prune -o -path './build' -prune -o -type f \( -ilname '*wise*' -o -iname '*wise*' -o -iname '*transferwise*' \) -print | sed -n '1,120p'
echo
echo "== Package/config files =="
for f in package.json pnpm-lock.yaml package-lock.json yarn.lock bun.lockb; do
if [ -f "$f" ]; then echo "-- $f"; sed -n '1,160p' "$f"; fi
doneRepository: we-promise/docs Length of output: 4885 🌐 Web query:
💡 Result: Wise has required developers to migrate from the legacy Sandbox environment (V1) to the new Sandbox environment (V2) by June 30, 2026 [1]. The V1 environment, previously accessed via api.sandbox.transferwise.tech or api.sandbox.wise.tech, was officially deprecated on June 30, 2026 [1]. As of this date, V1 is no longer supported, and any testing workflows relying on it will cease to function [1]. Key migration requirements include: - Base URL Update: Developers must switch their base URLs to the V2 endpoints: - TLS Only: https://api.wise-sandbox.com [1][2] - mTLS Enabled: https://api-mtls.wise-sandbox.com [2] - Portal Address: Update the Wise Portal URL to https://wise-sandbox.com [1][2]. - Credentials: V1 tokens and credentials created prior to the migration transition period may require replacement. Partners onboarded after April 1, 2025, must request new V2 sandbox credentials via their delivery team or by contacting api@wise.com [1]. While all existing endpoints and webhooks are supported in V2, developers are advised to ensure their environments are updated to avoid disruption [1]. No changes to code logic are typically required for the environment migration itself [1]. Citations:
Update the Wise sandbox host and WISE_BASE_URL guidance. The documented sandbox host is the deprecated Wise V1 URL. Use the latest Wise V2 sandbox host, 🤖 Prompt for AI Agents |
||
|
|
||
| ## Features | ||
|
|
||
| ### Multi-currency balances | ||
|
|
||
| - **Standard balances**: one balance per currency held in your Wise account, refreshed (including reserved amount) on every sync | ||
| - **Jars (savings pots)**: synced alongside standard balances and mapped to a savings-type account in Sure | ||
| - New balances discovered on a sync are shown as "needs setup" until linked to a Sure account | ||
|
|
||
| ### Transaction syncing | ||
|
|
||
| - The first sync imports 90 days of transfer history (or history from a sync start date you configure); later syncs use a 7-day lookback from the last successful sync | ||
|
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Locate providers/wise.mdx =="
fd -a 'wise\.mdx$' . || true
echo "== Context around line 40 =="
if [ -f providers/wise.mdx ]; then
nl -ba providers/wise.mdx | sed -n '1,90p'
fi
echo "== Search for Wise integration code/docs references =="
rg -n "Wise|wise|statement|balance|history|personal-api-token|90 days|supported|countries|account" -S . --glob '!node_modules' --glob '!.git' | head -200Repository: we-promise/docs Length of output: 292 🌐 Web query:
💡 Result: Personal API tokens are designed for individual Wise business accounts to automate payouts and manage balances [1][2]. While these tokens provide access to many API endpoints, they have specific limitations regarding balance statements and funding, which are restricted based on the account's country of registration [1]. Access to balance statements via the API is supported only for accounts based in the following countries: United States, Canada, Australia, New Zealand, Singapore, and Malaysia [1]. Key points regarding balance and statement API usage: - Personal API Token Scope: Personal API tokens are primarily intended for small-to-medium businesses (SMBs) to automate payout workflows, such as creating quotes, managing recipients, and preparing transfers [1][2]. - Balance Endpoints: The Wise API provides endpoints to retrieve specific balance details (GET /v4/profiles/{profileId}/balances/{balanceId}) [3] and total fund valuations (GET /v1/profiles/{profileId}/total-funds/{currency}) [4]. - Statement Retrieval: For eligible accounts, developers can use the balance account endpoints to obtain statements for a specified time range [5]. - Restrictions: Accounts outside of the six supported countries (US, CA, AU, NZ, SG, MY) cannot retrieve balance statements via the API [1]. Additionally, all Personal API tokens are limited compared to full OAuth 2.0 tokens, which are used by enterprise partners for more comprehensive financial management [6][2]. Developers should consult the official Wise Developer documentation for the most current information, as feature availability and regional support can be subject to change [7]. Top results: [1], [3], [4], [2], [5] Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Wise docs context =="
python3 - <<'PY'
from urllib.request import urlopen
from urllib.error import HTTPError, URLError
url = "https://docs.wise.com/guides/developer/auth-and-security/personal-api-token?utm_source=openai"
try:
text = urlopen(url, timeout=20).read().decode("utf-8", errors="replace")
except (HTTPError, URLError) as e:
print(f"ERROR: {type(e).__name__}: {e}")
raise SystemExit(2)
for needle in ["balance statements", "statement retrieval", "accounts based in", "United States", "Canada", "90 days", "statement history"]:
idx = text.rfind(needle)
if idx != -1:
start=max(0, idx-800); end=min(len(text), idx+1600)
print(f"\n--- around {needle} ---\n{text[start:end][:2000]}")
PY
echo "== providers/wise.mdx context (sed fallback) =="
sed -n '1,90p' providers/wise.mdx | awk '{printf "%3d: %s\n", NR, $0}'
echo "== Search Wise docs references in repo =="
rg -n "Wise|wise|balance statements|90 days|statement history|accounts based in" -S . --glob '!node_modules' || trueRepository: we-promise/docs Length of output: 329 Add the Wise statement-history country limitation. Wise personal API tokens only support balance-account statement retrieval for accounts registered in the supported countries. Since this sync imports history from statements, only users with supported Wise accounts will receive the 90-day transfer-history sync; add that limitation here or state a different authenticated source for transfers. 🤖 Prompt for AI Agents |
||
| - Transfers are matched to each linked balance by source or target currency | ||
| - Cross-currency incoming transfers use the amount actually received, not the amount sent | ||
|
Comment on lines
+41
to
+42
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Tracked files matching wise:"
git ls-files | rg -i '(^|/)wise|wise\.mdx|providers|jars|balance' || true
echo
echo "Inspect providers/wise.mdx around cited lines:"
if [ -f providers/wise.mdx ]; then
nl -ba providers/wise.mdx | sed -n '1,120p'
fi
echo
echo "Search for Wise balance matching implementation/usages:"
rg -n "source|target currency|SAVINGS|balance|Jar|sync|Wise|wise" . \
-g '!node_modules' \
-g '!dist' \
-g '!build' | head -200Repository: we-promise/docs Length of output: 574 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Inspect providers/wise.mdx around cited lines:"
if [ -f providers/wise.mdx ]; then
awk '{printf "%6d\t%s\n", NR, $0}' providers/wise.mdx | sed -n '1,140p'
fi
echo
echo "Related Wise provider references in documentation:"
rg -n -i "Wise|wise|balance|source currency|target currency|Jar|JAR|savings|linked balance|sync" providers README.md -g '!node_modules' -g '!dist' -g '!build' || trueRepository: we-promise/docs Length of output: 25834 🌐 Web query:
💡 Result: In the Wise API, balance accounts are managed within a multi-currency account structure [1][2]. Each balance account is categorized by a type, which dictates whether you can hold multiple accounts in the same currency [1][3]. 1. Balance Types: - STANDARD: These are standard balance accounts. You are limited to one STANDARD balance account per currency per profile [1][3]. - SAVINGS: These are "Jar" accounts. You can create multiple SAVINGS balance accounts in the same currency for a single profile [1][3]. 2. Key API Concepts: - Balance ID: Every individual balance account, whether STANDARD or SAVINGS, is assigned a unique integer ID [4][5]. You use this ID to retrieve details for a specific balance [4] or to facilitate movements between balances [6]. - Identification: When you list all balances for a profile, the response returns an array of balance objects, each containing its Citations:
Do not describe Wise balance matching by currency alone. Wise can have multiple 🤖 Prompt for AI Agents |
||
| - When a same-currency transfer includes a fee, the fee is imported as a separate "Wise fee" transaction | ||
|
|
||
| ### Jar activity | ||
|
|
||
| - Deposits and withdrawals to a Jar are imported as "Transfer to Jar" / "Transfer from Jar" transactions | ||
| - Interest and Wise Assets fees are imported automatically | ||
| - Transfers between a standard balance and a Jar are automatically linked as Sure Transfers, so the same movement is never double-counted as separate income and expense | ||
|
|
||
| ### Multiple profiles | ||
|
|
||
| If your Wise account has both personal and business profiles, you can connect several profiles from the same token at once. Each profile is a separate connection that can be synced, updated, or disconnected independently. | ||
|
|
||
| ## Limitations | ||
|
|
||
| - Uses a Wise personal API token rather than OAuth; the token carries whatever account access you grant it in Wise | ||
| - Wise Assets (investment) balances are not tracked as accounts — only fees charged against them are imported | ||
| - Each discovered currency balance must be linked to a Sure account manually after the first sync; balances aren't created automatically | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| **Invalid token / connection requires update**: your API token was revoked, expired, or lacks permissions. Create a new personal token in Wise and update it in the Wise provider panel. | ||
|
|
||
|
Comment on lines
+63
to
+64
There was a problem hiding this comment. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== locate wise.mdx =="
fd -a 'wise\.mdx$' . || true
echo "== relevant docs excerpt =="
if [ -f providers/wise.mdx ]; then
nl -ba providers/wise.mdx | sed -n '50,75p'
fi
echo "== search for Wise token expiry mentions in repo =="
rg -n "expired|personal API token|personal token|Wise" -S . \
-g '!node_modules' -g '!dist' -g '!build' | head -200Repository: we-promise/docs Length of output: 281 🌐 Web query:
💡 Result: Yes, Wise personal API tokens remain active until they are explicitly revoked [1][2]. These tokens do not have an inherent expiration date and will continue to function unless you choose to revoke them through your Wise business account settings [1][2]. If a token is compromised or no longer needed, you can revoke it by logging into your Wise business account, navigating to Your Account > Connect and manage apps > API tokens, and selecting the Revoke option for the specific token [1][2]. The token will stop working immediately upon revocation [1][2]. Please note that while these tokens do not expire on their own, the account itself must remain active for the tokens to work [3]. If a user account is deactivated, any associated tokens are also revoked [3]. Additionally, some documentation indicates that personal token logic may be subject to deprecation or migration requirements for certain users, so it is recommended to follow official guidance if you receive notifications regarding authentication updates [4]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== providers/wise.mdx around target lines =="
python3 - <<'PY'
from pathlib import Path
p = Path("providers/wise.mdx")
lines = p.read_text(encoding="utf-8").splitlines()
for i in range(max(0,62), min(len(lines),66)):
print(f"{i+1}: {lines[i]}")
PY
echo "== token expiry/expiration mentions in providers/wise.mdx and nearby docs =="
python3 - <<'PY'
from pathlib import Path
for p in Path("").glob("**/*.md*"):
if "node_modules" in p.parts or "dist" in p.parts or "build" in p.parts:
continue
text = p.read_text(errors="ignore").lower()
if {"wise", "expired", "expires", "expiration", "personal token", "personal-api-token", "invalid token", "requires update"} & {word.strip().rstrip(":").strip() for word in text.split()}:
if any(term in text for term in ["wise","personal token","personal-api-token"]):
try:
rel = str(p)
if "providers/wise.mdx" in rel or "docs.wise.com" in text:
continue
print(rel)
except UnicodeDecodeError:
pass
PY
echo "== exact Wise error/help snippets if present =="
rg -n "Invalid token|requires update|expired|personal API token|personal token" providers/wise.mdx || trueRepository: we-promise/docs Length of output: 1436 Remove the unsupported “expired” diagnosis. Wise personal API tokens remain active until revoked. Keep “expired” only if Sure imposes its own expiration rule; otherwise describe this failure as invalid or revoked. 🤖 Prompt for AI Agents |
||
| **No profiles found**: the token doesn't have access to any Wise profile. Check the token's permissions in Wise and try again. | ||
|
|
||
| **A currency balance is missing**: run a sync, then check **Set Up Accounts** on the connection — new balances only become Sure accounts once you link them. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: we-promise/docs
Length of output: 296
🏁 Script executed:
Repository: we-promise/docs
Length of output: 9031
🌐 Web query:
Wise personal API token read-only documentation transfer permissions💡 Result:
Wise personal API tokens support both full and read-only access levels [1][2]. When creating a personal API token through your Wise business account, you can explicitly configure the token's permission scope as either "full" or "read only" [1][2]. Key points regarding personal API token permissions: 1. Token Creation: You can generate and manage these tokens by navigating to Your Account > Connect and manage apps > API tokens in your Wise business account settings [3][1]. Two-factor authentication is required for this process [3][4]. 2. Permission Levels: - Read-only: Typically allows for data retrieval and tracking without the ability to execute state-changing actions like creating transfers [1]. - Full: Allows the token to perform authorized actions, such as creating quotes, creating recipients, and creating transfers (if supported in your region) [3][1]. 3. Capability Limitations: Regardless of the token's permission level, personal API tokens are generally limited to specific actions: creating quotes, managing recipients, drafting transfers, and tracking transfer statuses [3][1]. 4. Regional Restrictions: Funding transfers and retrieving balance statements via API are restricted features [3][1]. These capabilities are currently only available to business accounts based in the US, Canada, Australia, New Zealand, Singapore, and Malaysia [3][1]. For other regions, these actions cannot be performed via the API, even with a token configured for "full" access [5][1]. You can edit the name and access level of an existing personal API token or revoke it at any time through the same section in your Wise business account [3][1][2].
Citations:
🌐 Web query:
Wise personal API token account holder API personal token settings API tokens personal access level💡 Result:
Wise personal API tokens are designed for use with Wise business accounts, primarily to enable small-to-medium businesses to automate payouts and related workflows [1][2]. They are not intended for standard individual/personal Wise accounts [3][4]. Key details regarding personal API tokens: Access and Settings You can generate a personal API token by logging into your Wise business account and navigating to Your Account > Connect and manage apps > API tokens [1][3]. Two-step verification (2FA) must be enabled on the account to generate a token [1][5]. Usage and Limitations Personal API tokens are used to authenticate requests to the Wise API by including the token in the Authorization header: Authorization: Bearer <PERSONAL_API_TOKEN> [1][3]. They provide limited access compared to full OAuth 2.0 credentials [3][4]. Supported actions generally include: - Generating quotes [1][6] - Retrieving and creating recipient account details [1][6] - Creating transfers and batch groups [1][6] - Tracking transfer statuses [1][6] Important Restrictions - Funding transfers and retrieving balance statements via API are restricted in certain regions (e.g., EU/UK) due to PSD2 regulations, except for accounts based in the US, Canada, Australia, New Zealand, Singapore, and Malaysia [1][3]. - These tokens remain active indefinitely until they are manually revoked via the same API tokens settings page [1][6]. For enterprise partners or applications built for end customers, Wise requires the use of OAuth 2.0 rather than personal API tokens [3][2].
Citations:
Align the Wise token instructions with Wise’s documented setup and permissions.
Wise personal API tokens are created from Wise business account settings and support read-only and full access levels. Update these steps to point to the correct token creation path and describe read-only versus full token access consistently, including the limitation that full tokens can authorize recipient/transfer operations.
🤖 Prompt for AI Agents