Wirex Baas Cards

Wirex BaaS Card Management

Overview

The Wirex BaaS card system provides Visa virtual, plastic, and metal card issuance, lifecycle management, secure details retrieval, configurable limits, an on-chain transaction flow (including withdrawal and transfer), and 3DS authentication handling (OTP via SMS and in-app confirmation via webhook).

Required Headers

All card API endpoints require the following headers:

Card Types

Virtual Card Issuance

Note: Fee checking and invoice creation are applicable only if your account manager has advised you to incorporate card fee handling.

Physical Card Issuance

Card Lifecycle

Status Flow

Physical cards: Requested → NotActivated → Active ↔ Blocked → Closed

Virtual cards: Active (auto-activated) ↔ Blocked → Closed

WARNING: Closing a card is irreversible. The card cannot be reactivated.

Management Endpoints

Card Details Retrieval (PAN, CVV, PIN)

WARNING: action_token expires in 5 minutes and is single-use per detail type.

Card details require a two-step verification process producing an action_token.

Verification Methods

1. Signature Verification (recommended): POST /api/v1/confirmation/signature/verify -- uses action_type (enum: GetCardDetails, 3dsChallenge, VerifyPhone), message_signature, and nonce (Unix timestamp).
2. SMS OTP: POST /api/v1/confirmation/sms (uses action_type) then POST /api/v1/confirmation/sms/verify (uses session_id).

Detail Endpoints (all require action_token)

Card Limits

View Limits

GET /api/v1/cards/{cardId}

Returns limit object with transaction_limit, daily_limit, daily_usage, monthly_limit, monthly_usage, lifetime_limit, lifetime_usage, and currency. A value of -1 means no limit.

Update Limits

PUT /api/v1/cards/{cardId}/limit

Supports transaction, daily, monthly, and lifetime limit types. Set to -1 to disable a limit.

Card Transaction Flow

Card transactions follow an on-chain debit/credit flow through the FundsManagement executor.

Debit (Card Purchase)

1. Initiated → Authorization request received from card network
2. CryptoOut → Funds debited from user wallet to FundsBuffer (on-chain)
3. CardOut → Funds settled to card network
4. Completed → Transaction finalized

Card Withdrawal

Card Transfer

Credit (Refund/Top-up)

1. Initiated → Credit request received
2. CardIn → Funds received from card network
3. CryptoIn → Funds credited to user wallet (on-chain)
4. Completed → Transaction finalized

3DS Authentication

Wirex supports two 3DS authentication methods:

Method 1: OTP via SMS

The card network sends a one-time password directly to the cardholder's registered phone number. This method requires no backend involvement from the partner -- the OTP is delivered and verified entirely by the card network and the cardholder.

Method 2: In-App Confirmation via Webhook

When a 3DS challenge is triggered, Wirex sends a webhook and waits for approval.

1. Wirex sends POST /v2/webhooks/3ds with transaction details
2. Partner displays approval UI to user
3. Partner calls approve or decline endpoint
4. If no response before timeout, request is automatically declined

In-App Confirmation Endpoints

Webhooks

Quick Reference

References

• Card API Reference -- Complete request/response schemas, error codes, field validation patterns, and JavaScript examples
• See webhook payloads for complete webhook payload examples