Top-Up Card Registration

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain access tokens
Onboarding	User and wallet registration
KYC	KYC verification requirements
Environments	PCI environment base URLs

Overview

Before initiating a card top-up, the source card must be registered on Wirex's PCI-compliant secure environment. Registration returns a card_id that identifies the card in top-up estimate and execute requests.

Card management runs entirely against the PCI environment:

Register Card — Submit card details to receive a card_id
List Cards — Retrieve the user's registered top-up cards
Delete Card — Remove a registered card

The PCI environment ensures sensitive card data (PAN, CVV) is never stored or transmitted outside the secure environment.

Authentication

All card management endpoints require a user-scoped token obtained via User Token Issuance (Login as User). S2S tokens are not supported for these endpoints. The target user is identified by the user_id query parameter.

See Environments for PCI environment base URLs.

Register Card

Submit card details to the PCI secure environment to register a top-up source.

Endpoint

POST {pci_base_url}/b2b/cards/topup?user_id=USER_ID

Parameter	Description
`user_id`	User UUID from `GET /api/v2/user` response (`id` field)

Request

{
  "card": {
    "name": "ALEX GREY",
    "expiry_month": 12,
    "expiry_year": 2030,
    "number": "4000000000002701",
    "cvv": "123",
    "billing_details": {
      "address_line1": "1 Market Street",
      "address_line2": "Apt 4",
      "postal_code": "94105",
      "country": "FR",
      "city": "Paris",
      "state": "IDF"
    },
    "label": "My Visa Card"
  }
}

Field	Type	Required	Description
`card.name`	string	Yes	Cardholder name as printed on the card
`card.expiry_month`	integer	Yes	Card expiry month (1–12)
`card.expiry_year`	integer	Yes	Card expiry year (four digits)
`card.number`	string	Yes	Full card number (PAN)
`card.cvv`	string	Yes	Card verification value
`card.billing_details.address_line1`	string	Yes	Billing address line 1
`card.billing_details.address_line2`	string	No	Billing address line 2
`card.billing_details.postal_code`	string	Yes	Billing postal code
`card.billing_details.country`	string	Yes	Billing country (ISO 3166-1 alpha-2)
`card.billing_details.city`	string	Yes	Billing city
`card.billing_details.state`	string	No	Billing state or region
`card.label`	string	Yes	Display label for the card

Response

{
  "card_id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
  "card_label": "My Visa Card"
}

Field	Type	Description
`card_id`	string (UUID)	Card identifier used as `external_card_id` in top-up requests
`card_label`	string	Display label for the card

List Cards

Retrieve the top-up cards registered for a user.

Endpoint

GET {pci_base_url}/b2b/cards/topup?user_id=USER_ID

Response

{
  "cards": [
    {
      "card_id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
      "card_holder_name": "ALEX GREY",
      "pan_last4": "2701",
      "payment_system": "VISA",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z",
      "status": "Active",
      "is_confirmed": true,
      "card_label": "My Visa Card"
    }
  ]
}

Field	Type	Description
`cards[].card_id`	string (UUID)	Card identifier used as `external_card_id` in top-up requests
`cards[].card_holder_name`	string	Cardholder name
`cards[].pan_last4`	string	Last 4 digits of the card number
`cards[].payment_system`	string	`VISA` or `MASTERCARD`
`cards[].created_at`	string	ISO 8601 timestamp of registration
`cards[].updated_at`	string	ISO 8601 timestamp of last update (nullable)
`cards[].status`	string	Current card status
`cards[].is_confirmed`	boolean	Whether the card has been confirmed
`cards[].card_label`	string	Display label for the card (nullable)

Delete Card

Remove a registered top-up card. Returns an empty 200 body on success.

Endpoint

DELETE {pci_base_url}/b2b/cards/topup/{card_id}?user_id=USER_ID

Parameter	Description
`card_id`	Card identifier returned by registration
`user_id`	User UUID that owns the card

Error Handling

The PCI environment returns coded errors for card registration failures.

Code	Description
`0243`	The card has already been linked to another Wirex account

Registration also rejects invalid card numbers, unsupported card schemes (only Visa and Mastercard are supported), and expired cards.