Cardholder and Card Management in Europe

Cardholder management

A user is a person who uses a Marqeta card (physical or virtual) to access Marqeta-administered funds. The following endpoints enable you to create and manage users on the Marqeta platform:

To create a new user, use the /users endpoint.
To transition a user between statuses, use the /usertransitions endpoint.

You can set the number of active or suspended cards each user can own. The following card ownership scenarios are possible:

Each user can own a single active or suspended card (default).
Each user can own multiple active or suspended cards with one or more Primary Account Numbers (PANs).

For 3D Secure (3DS) and Tokenization use cases where Marqeta is responsible for sending the one-time passcode (OTP), you should include:

phone – E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of 15 digits.

For more information, see Users and User Transitions.

{
  "token": "user_token",
  "active": true,
  "phone": "012345123456",
  "first_name": "first_name",
  "last_name": "last_name",
  "email": "email_address",
  "address1": "Test Address",
  "address2": "Test Address 2",
  "city": "My Home City",
  "country": "My Country",
  "birth_date": "My Birthday",
  "parent_token": "parent_token",
  "uses_parent_account": true,
  "postal_code": "post_code"
}

{
  "usertransitions": [
    {
      "token": "transition_token",
      "status": "ACTIVE",
      "reason_code": "14",
      "reason": "Cardholder creation",
      "channel": "SYSTEM",
      "created_time": "2021-02-08T16:23:06Z",
      "user_token": "user_token"
    }
  ]
}

Card management

A card is a payment device that enables a user to conduct transactions at merchants’ shops. Cards can be physical or virtual. You can also tokenize cards for use in digital wallets. The following endpoints enable you to manipulate a card’s state:

To issue a new card or reissue an existing card, use the /cards endpoint.
To transition a card between states, use the /cardtransitions endpoint.

You can configure a card to be used once or multiple times.

A single-use card only functions for one transaction, after which it can no longer transact.
A multi-use card functions for multiple transactions, usually until the expiration date is reached.

Cards must be activated before use:

A card product can be configured so that new cards are active upon issuance.
New physical cards are shipped in an inactive state.
Virtual cards are digitally presented and activated immediately.

For more information, see Cards and Card Transitions.

{
  "token": "card_token",
  "user_token": "user_token",
  "card_product_token": "cardproduct_token",
  "fulfillment": {
    "shipping": {
      "recipient_address": {
          "first_name": "first_name",
          "last_name": "last_name",
          "address1": "address1",
          "address2": "address2",
          "city": "city",
          "country": "United Kingdom",
          "postal_code": "postal_code"
        }
    }
  }
}

Cardholder and card metadata

The cardholder and card objects allow you to configure metadata associated with the cardholder object. This metadata is displayed within each transaction and can therefore be used to pass data to your systems to inform them of specific attributes or actions for that cardholder.

Customer-injected metadata can define the names and values of up to 20 fields.
Values are provided within each transaction and passed to both the gateway and webhook endpoints.
Cardholder metadata includes specific configurations to tailor the experience to the cardholder, including notification email and notification language.

{
  "metadata": {
    "my_name_1": "my_value_1",
    "notification_email": "my_notification_email",
    "notification_language": "eng",
    "authentication_question1": "What was your first job?",
    "authentication_answer1": "Cashier",
    "authentication_question2": "What make was your first car?",
    "authentication_answer2": "Trabant",
    "authentication_question3": "What is your favorite color?",
    "authentication_answer3": "Blue"
  }
}

{
  "user": {
    "metadata": {
      "my_name_1": "my_value_1"
    }
  },
  "card": {
    "metadata": {
      "my_name_1": "my_value_1"
    }
  }
}

Card lifecycle

You might need to suspend, terminate and reissue or replace a card if it is lost, damaged, or stolen. You are responsible for maintaining the card state in the Marqeta platform. Marqeta informs you of state changes:

The card is suspended after you reach the online PIN limit.
The card is terminated because it is past its expiration date.

In general, you should respond to card problems in the following ways:

If a card is lost, you should suspend or terminate the card and reissue it with a new PAN.
If a card is stolen, you should terminate the card and reissue it with a new PAN.
If a card is damaged, you should terminate the card and reissue it with the same PAN.

{
  "cards": [
    {
      "token": "transition_token",
      "card_token": "card_token",
      "user_token": "user_token",
      "state": "ACTIVE",
      "reason": "New card activated",
      "reason_code": "01",
      "channel": "API",
      "fulfillment_status": "DIGITALLY_PRESENTED",
      "type": "state.activated",
      "created_time": "2021-01-08T16:59:22Z",
      "card_product_token": "cardproduct_token",
      "last_four": "8053",
      "pan": "1234**MASKED**5678",
      "expiration": "0625",
      "expiration_time": "2025-06-30T23:59:59.000Z",
      "barcode": "00112233445566778899",
      "pin_is_set": "false"
    }
  ]
}

Virtual to physical card replacement

Issuing a virtual card and a physical card with the same PAN is common with tokenization. This occurs when a customer wants to issue a card that can be used right away while a physical card is being shipped.

{
  "token": "virtual_card_1",
  "user_token": "test_user",
  "card_product_token": "virtual_card"
}

{
  "activation_actions": {
    "terminate_reissued_source_card": true
  },
  "card_product_token": "physical_card",
  "reissue_pan_from_card_token": "virtual_card_1",
  "token": "physical_card_1",
  "user_token": "test_user"
}

PIN management

Marqeta card objects act the same whether they are virtual or physical. A PIN is used with a physical card at a point of sale. PINs work differently based on region.

Online PIN management

The details of online PIN management are outlined below:

{
  "transactions": [
    {
      "response": {
        "code": "1809",
        "memo": "Invalid Pin"
      }
    }
  ]
}

{
  "cards": [
    {
      "fulfillment_status": "ORDERED",
      "last_four": "7890",
      "pan": "123456_____7890",
      "pin_is_set": true,
      "reason": "Pin Retry Limit Reached",
      "reason_code": "22",
      "state": "SUSPENDED",
      "token": "**REMOVED**",
      "type": "state.suspended"
    }
  ]
}

Offline PIN management

The details of offline PIN management are outlined below:

{
  "response": {
    "code": "1872",
    "memo": "Pin try limit exceeded",
    "additional_information": "Offline pin try limit exceeded"
  }
}

Cardholder and card management responsibilities

If you offer a Marqeta card program in Europe, there are several responsibilities that you and Marqeta maintain.

Responsibility	Powered By	Managed By
Reissue and reorder cards, including lost, stolen, and expired cards	You	You
Suspend cardholders when security thresholds are breached	Marqeta	Marqeta
Create and verify cardholder accounts, including Know Your Customer (KYC) identity verification	You	Marqeta
Batch and send card orders to your chosen fulfillment provider	Marqeta	Marqeta
Send transition webhook notifications for card and cardholder status changes	Marqeta	Marqeta