Topping Up From a Card

Before You Start

Read the following guides before proceeding:

---

Card Top-Up lets users fund their wallet by pulling funds from an external Visa or Mastercard payment card. The debit uses AFT (Account Funding Transaction) rails and credits the user's wallet with an on-chain token. This provides a fast on-ramp for users who want to move funds from their existing bank cards into the platform.

Before initiating a top-up, the source card must be registered on Wirex's PCI-compliant secure environment. Registration returns a card_id used to reference the card in top-up requests. Card data (PAN, CVV) is never stored or transmitted outside the secure environment.

Top-ups follow the standard estimate-then-execute flow. The estimate sizes the card debit for the token amount the user wants to receive, and execution starts the pull from the card. Because card debits are subject to Strong Customer Authentication, execution may return a 3DS state that the client must complete before the top-up settles. Transaction status is reported via activity webhooks.

Integration Flow (Simplified)

Detailed documentation available in Top-Up Card Registration and Card Top-Up.

sequenceDiagram
    participant User
    participant App as Your App
    participant PCI as Wirex PCI
    participant BaaS as Wirex BaaS

    Note over User,BaaS: Card Registration (one-time)
    User->>App: Enter card details
    App->>PCI: POST /b2b/cards/topup
    PCI-->>App: card_id

    Note over User,BaaS: Top-Up Execution
    User->>App: Request top-up
    App->>BaaS: POST /api/v1/cards/topup/estimate
    BaaS-->>App: estimation_id, source/destination amounts
    App-->>User: Top-up quote
    User->>App: Confirm top-up
    App->>BaaS: POST /api/v1/cards/topup/execute
    BaaS-->>App: id, status, three_ds_state

    Note over User,BaaS: 3DS (when required)
    App->>User: Open three_ds_state.url
    User->>PCI: Complete 3DS challenge

    Note over App,BaaS: Completion
    BaaS->>App: POST /v2/webhooks/activities
    App-->>User: Top-up complete