Skip to main content

​
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.
JSON
{
  "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"
}
JSON
{
  "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. Payment cards are represented on the Marqeta platform by the card object, which stores data about a card. Your application calls the Marqeta Core API to issue and manage cards. 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.
Cards can be made temporarily non-functional by transitioning them to a suspended state.
  • Suspended cards can be transitioned back to an active state.
  • To make cards permanently non-functional, you can transition them to a terminated state. Terminated cards cannot be reactivated.
For more information, see Cards and Card Transitions.
JSON
{
  "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 that can be 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. The details of that process are outlined below.
  • Customer-injected metadata, with the user and card objects, 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.
    • If both the metadata.notification_email field and the user.email field are populated, notifications are sent to the metadata.notification_email address.
    • Email addresses in user.email can only exist on the Marqeta platform once, whereas notification_email can exist multiple times.
    • Customizable questions and answers for 3DS knowledge-based authentication (KBA) can be used as part of PSD2 compliance in some regions that use OTP and KBA questions.
JSON
{
  "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"
  }
}
JSON
{
  "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 can perform these actions on physical and virtual cards, as well as on any digital wallet tokens sourced from the affected card. You are responsible for maintaining the card state in the Marqeta platform. Marqeta informs you of state changes, such as:
  • The card is suspended after you reach the online PIN limit.
  • The card is terminated because it is past its expiration date. You are responsible for reordering an expired card.
When issuing a card, you can choose to create an original card or reissue an existing PAN.
  • A reissued card behaves the same and has the same card number as the source card.
  • You can only reissue a source card once. The source card can be an original card or a reissued card.
  • You can choose to automatically terminate a source card when the new reissued card is activated. The maximum active card limit is specific to your card program.
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.
JSON
{
  "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. It can also be used to control the ordering of a physical card, and it allows you to defer card shipment to a later date. When physical cards are issued, they are sent to the card provider immediately. Virtual cards can be issued and used immediately, either by displaying them digitally or adding them to a mobile wallet. Two core use cases for this flow are:
1
Virtual card is created. Physical card, with the same PAN, is ordered at the same time.
2
Virtual card is created. Physical card, with the same PAN, is ordered at a later time.
The details of virtual to physical card replacement are outlined below.
  • The reissue_pan_from_card_token field is used when issuing a physical card so that cards share the same PAN. For security reasons, CVV and expiration date are different between the two cards.
  • You can use terminate_reissued_source_card to terminate a virtual card automatically.
  • When two cards share the same PAN and the latest PAN is activated, Marqeta automatically switches non-terminated digital wallet tokens to the latest card.
A PUT request to the /cards endpoint creates a virtual card under a virtual card-specific card product.
JSON
{
  "token": "virtual_card_1",
  "user_token": "test_user",
  "card_product_token": "virtual_card"
}
A PUT request to the /cards endpoint creates a physical card under a physical card-specific card product. Additional fields can be used to create a physical card with the same PAN as a virtual card, which terminates the linked virtual card.
JSON
{
  "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. An online PIN is used at ATMs and in any region that is online. An offline PIN is used on airplanes and in regions such as the UK and France.

​
Online PIN management

The details of online PIN management are outlined below.
  • Online PIN validation occurs when Marqeta receives the PIN value to the host and validates it against Marqeta’s internal data to approve or decline the transaction. ATMs always utilize online PINs and reflect the latest PIN value that Marqeta holds.
  • Marqeta deploys a standard three attempt PIN limit for online PINs. As Marqeta is validating the PIN in this situation, Marqeta has better control over the rejection and related events.
    • The Marqeta system displays an “Invalid PIN” transaction decline for each failure.
    • Cardholders have a PIN attempt limit of three, after which the card is suspended on the Marqeta platform.
    • Customers should check to see if this is a legitimate failure before reactivating and resetting the PIN (if required).
  • Marqeta rejects weak PINs from being set and performs the following validations:
    • PIN does not contain consecutive ascending or descending values, such as 1-2-3-4 or 9-8-7-6.
    • PIN is not a single digit repeated four times, such as 2-2-2-2.
    • PIN is not one of the most common PINs chosen by cardholders.
    • PIN confirmation value matches the PIN value.
JSON
{
  "transactions": [
    {
      "response": {
        "code": "1809",
        "memo": "Invalid Pin"
      }
    }
  ]
}
JSON
{
  "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. In an offline PIN situation, the PIN is stored securely on the chip, and the point of sale sends the PIN to the card chip for validation. Cardholder verification therefore takes place within the chip card. Offline transactions also utilize offline PINs. Countries such as the UK and France are entirely offline PIN countries. New cards created on the Marqeta platform do not have PINs set by default, so PINs must be set in one of two ways:
  • PIN set at card creation (recommended for offline PINs).
    • PIN must be set before physical card is sent to card provider. It is recommended to set the PIN immediately after card creation.
    • When the offline/online PINs start in sync, the card can be used as soon as it is activated.
  • PIN set at card activation.
    • After setting the PIN, the card must first be used at an ATM (via an approved balance inquiry or a cash withdrawal) or at a point of sale that supports handling online PINs.
    • When the online/offline PINs are out of sync, there is no PIN stored with Marqeta and the default PIN is on the chip.
Note
To allow your card to work in offline PIN terminals, the enable_offline_pin field must be set to true in your card product to ensure your cards are created with a PIN block during manufacturing.
JSON
{
  "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. These responsibilities include:
ResponsibilityPowered ByManaged By
Reissue and reorder cards, including lost, stolen, and expired cardsYouYou
Suspend cardholders when security thresholds are breachedMarqetaMarqeta
Create and verify cardholder accounts, including Know Your Customer (KYC) identity verificationYouMarqeta
Batch and send card orders to your chosen fulfillment providerMarqetaMarqeta
Send transition webhook notifications for card and cardholder status changesMarqetaMarqeta

Related topics

Powered by Marqeta Europe and the Card-Issuing EcosystemManaging SCA in EuropeAbout SCA in EuropeCard Products in EuropeSettlement and Reconciliation in Europe