# Overview

What External Authorization is and how it differs from standard integration.

## Before You Start

Read the following guides before proceeding:

| Guide                                  | Why                                        |
| -------------------------------------- | ------------------------------------------ |
| [Getting Started](https://docs.wirexapp.com/docs/getting-started) | Platform overview and setup                |
| [Api Basics](https://docs.wirexapp.com/docs/api-basics)           | Required headers and request configuration |

***

## 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

| Aspect                  | Standard Flow             | External Authorization    |
| ----------------------- | ------------------------- | ------------------------- |
| Smart Wallet deployment | Required per user         | Not required              |
| On-chain registration   | Required                  | Not required              |
| User identifier         | EOA address               | EOA address               |
| Balance management      | Wirex (on-chain per user) | Partner (external system) |
| Transaction settlement  | User's AA wallet          | Partner's Master Account  |
| Authorization           | Internal (Wirex)          | External (Partner API)    |

***

## 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](https://business.wirexapp.com)
   * **Sandbox:** [business.wirexapp.tech](https://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](#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](https://business.wirexapp.tech) / [production](https://business.wirexapp.com))
   * [ ] Complete KYB verification
   * [ ] Notify Wirex to link account as Master Account
   * [ ] Fund the Master Account

2. **API Integration**
   * [ ] Implement `/authorize` endpoint (see [Authorization API](https://docs.wirexapp.com/docs/extauth-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