Transaction Processing

Overview

Wirex Pay processes transactions differently depending on whether a user is onboarded through the Standard flow or the External Authorization flow.

• Standard — Wirex Pay validates and authorizes transactions internally, using the user’s on-chain Account Abstraction (AA) and balance projection.
• External Authorization — Wirex Pay calls the partner’s external authorization API before charging the partner’s prefunded Master Account.

Glossary

• Master Account: A prefunded account maintained by the partner within Wirex Pay. In External Authorization, all user transactions are settled against this account rather than individual user balances.

• 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 500ms.

• Mandatory Transaction (Advice Operation): A transaction required by card processors (e.g., refunds, chargebacks, corrections) that must always be executed and charged to the Master Account, regardless of partner authorization response. Identified by is_mandatory: true.

• Normal Transaction: A standard transaction (e.g., purchases, ATM withdrawals) that is executed only if the partner's external authorization endpoint responds with is_allowed: true. Declined if no response within 500ms.

• Round Trip SLA: The maximum time (500ms) allowed for the complete authorization request cycle from Wirex Pay to partner API and back. Timeouts are treated as declines for normal transactions.

• Settlement: The final debit of funds. In Standard flow, occurs on user's AA wallet. In External Authorization, occurs on the partner's Master Account.

Standard Transaction Processing

In the standard model, Wirex Pay is the system of record for user balances.

Steps:

1. User initiates a transaction.
2. Wirex Pay validates internally (limits, balance checks).
3. Authorization is handled entirely by Wirex Pay.
4. Settlement debits the user’s AA.
5. Completion — Transaction is confirmed and added to history.

Key characteristics:

• Authorization is fully internal.
• Balance checks use the user’s AA.
• Settlement always debits the user’s AA.

sequenceDiagram
    title Standard Transaction Processing
    participant U as User
    participant N as Card Network
    participant WP as Wirex Pay
    participant AA as User AA (Blockchain)

    U->>N: Initiates transaction
    N-->>WP: Transaction request
    WP->>WP: Validate transaction (limits, balance)
    WP->>AA: Debit AA
    AA-->>WP: Settlement confirmed
    WP-->>N: Transaction approved
    WP-->>U: Transaction completed

External Authorization Transaction Processing

Transaction Types

Normal Transactions

Transactions that require explicit partner authorization:

• Card purchases (POS, ePOS)
• ATM withdrawals
• Card-to-card transfers (sender side)

Mandatory Transactions (Advice Operations)

Transactions that must be processed regardless of authorization response:

• Refunds (full or partial)
• Chargebacks
• Network corrections
• Authorization reversals
• Settlement adjustments

Note: Mandatory transactions are identified by is_mandatory: true in the authorization request.

In the external authorization model, balances are managed externally by the partner, and Wirex Pay charges the partner’s prefunded Master Account.

Steps:

1. User initiates a transaction.
2. Wirex Pay requests authorization from the partner’s external API.
3. Partner responds:
   • Normal transactions: executed only on ALLOWED.
   • Mandatory (advice) transactions: always executed, regardless of response.
4. Settlement debits the partner’s Master Account.
5. Completion — Transaction finalized and reported to partner

Key characteristics:

• Authorization depends on the partner’s API.
• Normal transactions require explicit approval.
• Mandatory transactions always execute.
• Settlement always debits the Master Account.

sequenceDiagram
    title External Authorization Transaction Processing
    participant U as User
    participant N as Card Network
    participant WP as Wirex Pay
    participant P as Partner System
    participant MA as Master Account (Wirex Pay)

    U->>N: Initiates transaction
    N-->>WP: Transaction request
    WP->>P: Request authorization (user + txn)
    alt Normal Transaction
        P-->>WP: ALLOWED
        WP->>MA: Debit Master Account
        MA-->>WP: Settlement confirmed
        WP-->>N: Transaction approved
        WP-->>P: Transaction webhook notification
    else Decline
        P-->>WP: DECLINE
        WP-->>N: Transaction declined
        WP-->>P: Transaction webhook notification
    end
    alt Mandatory Transaction
        P-->>WP: ALLOWED/DECLINE (ignored)
        WP->>MA: Debit Master Account
        MA-->>WP: Settlement confirmed
        WP-->>N: Transaction approved
        WP-->>P: Transaction webhook notification
    end

Comparison Table

Notes & Constraints

• Wirex Pay guarantees that its internal ledgers remain balanced even if a partner declines a mandatory transaction.
• Partners must ensure their external authorization API is reliable and performant (≤ 500 ms round trip).
• The Master Account must remain funded to cover all mandatory transactions.
• For normal flow user transaction would be rejected regardless of partner response in case Master account prefunding is insufficient.
• For normal flow user transaction would be rejected if partner's external authorization API does not respond within the SLA and subsequent response would not be honored even if received.

External Authorization API Contract

Endpoint

• Method: POST
• Path: /external-authorization/on-chain/card-transaction
• SLA: The full round‑trip (Wirex Pay → Partner → Wirex Pay) must be ≤ 500 ms.

Headers

• Content-Type: application/json
• Authorization: Bearer <partner-api-token>
• CorrelationId: <uuid> — Idempotency and tracing.

Request Body (JSON)

{
  "transaction_type": "POS",
  "user_id": "5f7e3f7b-8e0c-48b8-9f2c-3e0c9d7a2a11",
  "transaction_id": "a7b2a4b3-2f61-41a7-9f5a-3f3f0b1a3d22",
  "operation_type": "Debit",
  "card_id": "c0b2c7b1-1d2e-4d7a-9a5d-2b7e3c4d5f66",
  "currency": "USD",
  "amount": 123.45,
  "is_mandatory": false,
  "unique_operation_id": "3e1f6a98-6b0a-4c8c-93e5-0b9c6d2a7f31"
}

Field Reference

• transaction_type (required, enum) — Channel of the card event. Allowed values:
  • POS - Point of Sale transaction (in-store)
  • ATM - ATM withdrawal
  • ePOS - E-commerce transaction (online)
  • MoneyTransfer - Money transfer (e.g., card-to-card)
• user_id (required, string guid) — End‑user identifier (as registered in Wirex Pay Offchain API).
• transaction_id (required, string guid) — Original card transaction identifier.
• operation_type (required, enum) — Direction relative to the card balance. Allowed values:
  • Debit - charge (purchase, withdrawal)
  • Credit - refund (return, reversal), money send
• card_id (required, string guid) — Card that triggered this transaction.
• currency (required, string) — ISO‑4217 code (e.g., USD).
• amount (required, number) — Decimal amount in currency.
• is_mandatory (required, boolean) — If true, Wirex Pay executes regardless of the partner’s decision (advice operation).
• unique_operation_id (required, string guid) — Unique id tying this authorization to the original operation; use for idempotency.

Response (JSON)

Return your decision synchronously.

{
  "transaction_id": "b5b6f2b4-7c9a-4d79-8a6d-1e2f3a4b5c6d",
  "is_allowed": true,
  "decline_reason": "InsufficientFunds",
}

• is_allowed (required, bool) — Whether the transaction is allowed.
  • true = ALLOWED
  • false = DECLINE
• decline_reason (optional, string) — Reason for the transaction to be declined. Allowed values:
  • InsufficientFunds - User has insufficient funds for the transaction,
  • GeneralError - Transaction is declined due to processing error on partner side.
• transaction_id (optional, string) — Partner’s id for reconciliation.

Behavioral Rules

• Normal transactions: Wirex Pay proceeds only if decision = ALLOWED.
• Mandatory (advice) transactions: Wirex Pay always proceeds, ignoring decision.
• Timeouts / 5xx: Treated as no decision (same effect as DECLINE for normal; ignored for mandatory).