Guides
Start typing to search…

External authorization

The Master Account External Authorization feature allows partners to manage end-user balances within their own systems while maintaining a prefunded Master Account inside Wirex Pay. Wirex Pay debits the Master Account for transactions only after receiving authorization from the partner’s external API.

Executive Summary

What: The External Authorization feature allows partners to manage end-user balances within their own systems while maintaining a prefunded Master Account inside Wirex Pay. Wirex Pay debits the Master Account for transactions only after receiving authorization from the partner’s external API.

Why: This enables partners to retain control of their balance logic, reduce on-chain setup overhead, and guarantee settlement for mandatory operations from card processors. At the same time, Wirex Pay ensures internal ledgers remain balanced.

How:

  • Partners implement a standard API contract to handle authorization requests.
  • Wirex Pay calls this endpoint before executing transactions.
  • Normal transactions require explicit approval from the partner.
  • Mandatory transactions, also known as “advice operations” required by card processors, are always executed, regardless of partner response.
  • Users are registered via the Offchain API, with no need for per-user on-chain accounts.

Key Benefits:

  • Simplified onboarding — no per-user account abstraction
  • Full partner control of balance and business logic
  • Guaranteed settlement of mandatory advice operations
  • Lightweight, API-based integration

Glossary

  • Master Account A prefunded account maintained by the partner within Wirex Pay. All user transactions are ultimately settled against this account rather than individual balances inside Wirex Pay.

  • Mandatory Transaction (Advice Operation) A type of transaction instructed by card processors (e.g., to reconcile transaction status, ensure settlement, or handle reversals). These transactions must always be executed and charged to the Master Account, regardless of whether partner approval is received—to ensure system integrity and alignment with payment network requirements.

  • Normal Transaction A transaction type that is executed only if the partner’s external authorization endpoint responds with approval. If the response is a decline or there is no response, the transaction is rejected.

  • External Authorization The process where Wirex Pay sends transaction details to a partner-hosted API endpoint to confirm whether a user has sufficient balance in the partner’s system. The partner must respond within a strict latency SLA.

High-Level Architecture

Principles

  1. External Authorization First: All normal transactions require partner API approval.
  2. Mandatory Advice Fulfilled: Mandatory (advice) operations are always settled, regardless of partner response.
  3. Simplified Onboarding: Users registered via Offchain API only.
  4. Prefunded Assurance: Master Account must remain sufficiently funded at all times.

Workflow

  1. User Registration: Partner registers users through the Wirex Pay API.
  2. Transaction Request: User initiates a transaction in Wirex Pay.
  3. Authorization Call: Wirex Pay sends a request to the partner’s authorization API with transaction details.
  4. Partner Decision:
    • Approve → Wirex Pay debits the Master Account.
    • Decline → Wirex Pay rejects the transaction (normal transactions only).
    • Mandatory Transaction → Wirex Pay proceeds with debit regardless of partner response.
  5. Settlement: Transaction finalized and charged to the Master Account.

Performance Requirements

Your authorization API should respond quickly to ensure smooth transaction processing:

  • Target response time: < 300ms
  • Maximum total round trip: 500ms
  • Recommendation: Deploy in the same region as Wirex Pay (AWS eu-central-1/Azure west-europe)

Integration Requirements

Partner Responsibilities

  • Maintain a prefunded Master Account in Wirex Pay.
  • Implement and expose the external authorization API according to the contract.
  • Guarantee high availability and low latency of the API endpoint.
  • ‼️ Round-trip to the external authorization endpoint must complete in ≤ 500 ms.
  • Keep the Master Account funded to cover all mandatory operations.

Implementation Phases

  1. Setup
  • Request a feature from Account Manager
  • Fund the Master Account in Wirex Pay.
  • Register integration details (API URL, authentication).

  1. Integration

    • Implement the external authorization API endpoint.
    • Test against the Wirex Pay sandbox environment.

  2. Validation

    • Verify handling of both normal and mandatory (advice) transactions.

  3. Production Launch

    • Go live with the authorization API.

Frequently Asked Questions

What happens if my API is temporarily unavailable?

Normal transactions will be declined. Mandatory transactions will still process. We recommend implementing high availability.

How often should I top up the Master Account?

We recommend maintaining a balance equal to 3-5 days of typical transaction volume. Automated top-ups are available.

Can I migrate existing users from standard to external authorization?

This is evaluated case-by-case. Contact your account manager.

How do I handle chargebacks?

Chargebacks are processed as mandatory credit transactions. Your webhook will be notified.

Updated 2 days ago