Wise Platform API: Technical Reference for AI Implementation

Overview

International payment API built on production-tested infrastructure handling $8B+ monthly volume with 15.6M active customers. Provides real international transfer capabilities, not traditional banking delays.

Integration Models

Partner Account

• Use case: Direct control using own Wise business account
• Timeline: 2-3 weeks if experienced with payments
• Cost: Standard Wise Business rates (0.5-2% based on currency pair)

Customer Account with Partner KYC

• Use case: Banks/licensed institutions managing own compliance
• Timeline: Most complex option, 6-8 weeks minimum
• Requirements: Financial license, compliance infrastructure

Customer Account with Wise KYC

• Use case: Wise handles compliance, focus on product
• Timeline: 2-3 weeks integration + 1-3 days account creation
• User experience: Customers get Wise accounts through your app

International Receive

• Use case: Correspondent banking for incoming transfers
• Requirements: SWIFT connectivity needs

Technical Architecture

Infrastructure

• 1000+ microservices on Kubernetes
• 65% of transfers complete instantly (2025 data)
• Same-day/next-day completion for most transfers
• Rate limits exist but reasonable (exact limits vary by integration type)

API Workflow: Critical Failure Points

1. Quotes (30-minute expiration)

• CRITICAL: Quotes expire in exactly 30 minutes
• Failure mode: User delay causes quote expiration, requires restart
• Implementation requirement: Must implement countdown timer

2. Recipients (Validation failures)

• Common failure: Invalid routing number format
• Validation: Bank details validated on creation (immediate feedback)
• Error pattern: recipient_account_validation_failed = routing number issue

3. Transfer States

• States: waiting_recipient_input_data → processing → funds_converted → outgoing_payment_sent
• Complexity: Multiple state transitions require proper handling

4. Multi-Currency Accounts

• Account creation: 1-3 business days (not instant)
• Currency conversion: Mid-market rates, processing delays exist
• Local accounts: Real routing numbers/IBANs, not international routing

Authentication Complexity

Methods by Use Case

• Personal Access Tokens: Simple integrations
• Strong Customer Authentication (SCA): EU compliance required
• OAuth 2.0: Customer account management

SCA Critical Limitation

• Cannot fully automate: Requires user interaction for sensitive operations
• Workaround: SCA sessions (April 2025 update) reduce friction
• Design impact: Must plan for non-automated flows

Webhook Implementation: Common Failures

Signature Verification (Primary failure point)

• Algorithm: RS256 (NOT HMAC256 like most APIs)
• Critical requirement: Use raw request body, not parsed JSON
• Failure pattern: Parsing JSON before verification breaks signatures
• Retry behavior: 24-hour retry with exponential backoff

Known Issues

• Version 3.1.2: Broke webhook ordering in sandbox
• Sandbox limitation: Out-of-order delivery during testing
• Production behavior: Reliable delivery, different from sandbox

Regional Compliance Gotchas

Brazil

• PIX integration: Additional compliance steps required
• Documentation gap: Assumes knowledge of Brazilian banking regulations

EU

• GDPR requirements: Beyond typical API usage
• User consent: Bulletproof flows required
• Error codes: Different from US implementations

US

• ACH vs SEPA: Different failure modes
• Regional variance: Error codes vary by region

Performance Thresholds & Limitations

Settlement Speed Reality

• 65% instant: As of 2025
• Majority: Same-day/next-day
• Traditional banking comparison: 3-5 business days → hours/days

Rate Limits

• Design: Prevent abuse, not monetize API calls
• Documentation: Intentionally vague, varies by integration type
• Volume consideration: Plan for scaling

Cost Analysis (Real Numbers)

Transaction Costs

• $10K USD→EUR: $50-60 (0.5-0.6%)
• $5K USD→THB: $75-100 (1.5-2%)
• Volume pricing: 10K transfers/month = $500-1000 monthly API costs

Hidden Costs

• Developer time: Proper error handling implementation
• Compliance consulting: Multi-region requirements
• Integration partners: If internal expertise lacking

Competitive Positioning

Capability	Wise Platform	Stripe Connect	Adyen MarketPay	Traditional Banking
Settlement Speed	Same/next day	Instant-weekly	Regional variance	3-5 business days
FX Markup	Mid-market (no markup)	Reasonable US only	Negotiable enterprise	2-4% markup
Multi-Currency	Real local accounts	US-focused	Enterprise complexity	Single currency
Integration Time	2-3 weeks experienced	1 week	Months + contracts	Undefined
Documentation Quality	Good with gaps	Excellent	Comprehensive	Poor/nonexistent

Failure Scenarios & Workarounds

Most Common Integration Failures

1. Webhook signature verification: Raw body requirement missed
2. Quote expiration: No countdown timer implementation
3. Regional compliance: Different rules by geography
4. SCA authentication: Assuming full automation possible

Production Issues

• Support response: Business hours for technical issues
• Error message quality: Generally helpful HTTP status codes
• Escalation paths: Functional (unlike traditional banking)

Breaking Changes

• API versioning: v3.1.2 webhook ordering issue
• Feature updates: Card kiosk collection (March 2025), SCA sessions (April 2025)

Implementation Decision Criteria

Use Wise When

• International transfers required: Core strength
• Multi-currency accounts needed: Real local banking details
• Fair FX rates critical: Mid-market pricing
• 2-3 week integration acceptable: Standard timeline

Don't Use Wise For

• Cryptocurrency transactions: Explicitly prohibited
• Domestic US payments: Use Stripe/similar
• High-frequency trading: Rate limits incompatible
• Gambling/adult content: Compliance restrictions vary

Critical Implementation Requirements

Must Implement

• Quote expiration handling: 30-minute countdown
• Proper webhook verification: RS256 with raw body
• Regional error handling: Different codes by geography
• SCA user interaction: Cannot be fully automated
• Multi-state transfer tracking: Complex state machine

Production Readiness Checklist

• Webhook signature verification with raw body
• Quote expiration countdown timer
• Regional compliance handling
• SCA authentication flows
• Error handling for all transfer states
• Sandbox vs production behavior differences accounted for

This reference provides the operational intelligence needed for successful Wise Platform API implementation, including all critical failure modes and their solutions.