Overview

Before You Start

Read the following guides before proceeding:

What is External Authorization

External Authorization is an integration model where:

• Partners manage user balances in their own systems
• Wirex calls the partner's authorization API before processing card transactions
• All transactions settle against a partner-prefunded Master Account
• No per-user Smart Wallet deployment or on-chain registration required

Comparison with Standard Flow

Master Account

The Master Account is a Wirex Business account that you create and prefund. Wirex debits this account for all user transactions in External Authorization mode.

Creating a Master Account

1. Register a Wirex Business account in your organization's name:

   • Production: business.wirexapp.com
   • Sandbox: business.wirexapp.tech

2. Complete account verification (KYB)

3. Notify your Wirex account manager that this account should be used as the Master Account for your integration

4. Fund the account with sufficient balance

Requirements

• Maintain sufficient balance for expected transaction volume
• Recommended: 3-5 days of typical transaction volume
• Monitor balance and top up proactively
• Mandatory transactions process even if balance is insufficient

When to Use External Authorization

Use External Authorization when:

• You maintain your own balance ledger for users
• You need real-time control over transaction authorization
• You want to avoid per-user on-chain wallet deployment overhead
• Your business model requires custom authorization logic

Use Standard Flow when:

• Users should hold their own on-chain balances
• You prefer Wirex to handle balance management
• You don't need custom authorization logic per transaction

Enabling External Authorization

1. Create a Wirex Business account (see Master Account above)
2. Contact your Wirex account manager to:
   • Enable External Authorization for your partner account
   • Link your Wirex Business account as the Master Account
   • Configure your authorization API endpoint URL
   • Set up webhook endpoints
3. Fund your Master Account
4. Implement the authorization API endpoints

Implementation Checklist

1. Master Account Setup

   • Create Wirex Business account (sandbox / production)
   • Complete KYB verification
   • Notify Wirex to link account as Master Account
   • Fund the Master Account

2. API Integration

   • Implement /authorize endpoint (see Authorization API)
   • Implement /settle endpoint
   • Ensure response time < 300ms
   • Handle mandatory transactions

3. Webhooks

   • Configure webhook endpoints with Wirex
   • Implement transaction webhook handler
   • Update internal balance records on webhooks

4. Testing

   • Test authorization flow in sandbox
   • Test timeout handling (>500ms = decline)
   • Test mandatory transaction handling
   • Verify balance reconciliation