Create and Update Cards

Learn what a Marqeta card is as well as how to create and update it.

We'll cover the following

A card is a payment card that’s owned by a user. It can either be a physical or a virtual card. The behavior and the attributes of the card are defined by the card product object associated with it. We can also define the attributes of the card inside the card object. In that case, the definition inside the card object will take precedence over the definition inside the card product object.

In this lesson, we’ll learn how to create and update a Marqeta payment card.

Create a card

We can create a Marqeta payment card by making a POST request to the {BASE_URL}/cards endpoint. We can provide basic information about the card in the body of the request. This includes the shipping information. We also need to specify the user_token of the card owner as well as the card_product_token of the card product that controls the card. Therefore, we need to create a user and a card product before we create a new Marqeta card.

Request Parameters

Parameter

Type

Category

Description

show_cvv_number

boolean

optional

True to show the CVV2 number in the response, otherwise False

Note: This is a query parameter.

show_pan

boolean

optional

True to show the card’s PAN (primary account number) in the response, otherwise False

Note: This is a query parameter.

card_product_token

string

required

Token of the card product

expedite

boolean

optional

True when we want to request the fulfillment provider to expedite card processing, otherwise False

Default value: False

metadata

object

optional

Adds metadata provided by the customer to the card

Allowable values: Maximum 20 key-value pairs allowed

Format: "my_name_1": "my_value_1"

expiration_offset

object

optional

Defines the duration for card validity after issuance

token

string

optional

Unique token of the card

Length: 1–36 characters

Note: If not specified, the system generates one automatically. This value cannot be updated once set.

user_token

string

required

Unique token of the card user

fulfillment

object

optional

Contains shipping information and the physical characteristics of the card

reissue_pan_from_card_token

string

optional

Reissues the specified card and assigns the new card the same PAN and PIN (personal identification number) but a new expiration date and CVV2 number

Maximum length: 36 characters

translate_pin_from_card_token

string

optional

Assigns the newly created card the same PIN as the specified card

Maximum length: 36 characters

Note: Both cards must belong to the same user. Additionally, reissue_pan_from_card_token must not be set.

activation_actions

object

optional

Contains actions to perform at card activation

Note: The fields in this object are mutually exclusive.

bulk_issuance_token

string

optional

Token of the bulk card order to link the card to

Note: This field cannot be updated once set.

Maximum length: 36 characters

Note: Please refer to this course’s appendix for details of the expiration_offset, fulfillment, and activation_actions objects.

In the code below, we pass two query parameters, show_cvv_number and show_pan, along with some optional parameters in the body of the request, in addition to the required parameters.

Lines 1–2: We set the values for both optional query parameters, show_cvv_number and show_pan, to True.

Lines 8–9: We have already saved the values in the previous lessons for the required parameters, user_token and card_product_token, respectively.

Line 14: We enter the value for name_line_1.value.

Lines 20–24: We enter the values for address1, city, state, postal_code and country. Refer to the Marqeta’s official documentation for details.

Note: You can change and enter values for other optional parameters that are given in the table above.

After we’ve entered the values, click the “Run” button in the code widget below to see the output.

Press + to interact
show_cvv_number = True
show_pan = True
url =     "https://sandbox-api.marqeta.com/v3/cards?show_cvv_number=" \
          + str(show_cvv_number) + "&show_pan="+ str(show_pan)
data = json.dumps({
     "user_token": "{{USER_TOKEN}}", 
     "card_product_token": "{{CARD_PRODUCT_TOKEN}}",
     "fulfillment": {
          "card_personalization": {
               "text": {
                    "name_line_1": {
                         "value": ""
                    }
               }
          },
          "shipping": {
               "recipient_address": {
                    "address1": "",
                    "city": "",
                    "state": "",
                    "postal_code": "",
                    "country": "",
               }
          },   
     },
})
response = requests.post(url, headers=headers, data=data)
printResponse(response)

When the code is executed successfully, the output displays the complete card object with all the data fields. We extract the token field and save it as CARD_TOKEN. This value will be used for a number of operations throughout this course.

In case of failure, an appropriate error message is displayed.

Create card transition

Card transition refers to when we set the state of an existing card. All cards are inactive upon creation and require us to activate them. We can set the state of an existing card by making a POST request to the {BASE_URL}/cardtransitions endpoint.

Note: Once activated, we may not be able to transfer a card from one user to another.

Request Parameters

Parameter

Type

Category

Description

card_token

string

required

Token of the card that we want to set the status of

channel

string

required

Mechanism used for the transition

Allowable values: ADMIN, API, FRAUD, IVR, SYSTEM

state

string

required

New state that we want to set

Allowable values: ACTIVE, SUSPENDED, TERMINATED

token

string

optional

Unique token of the card transition

Length: 1–36 characters

Note: If not specified, the system generates one automatically. This value can't be updated once set.

reason

string

optional

Additional information about the change of state

Maximum length: 255 characters

reason_code

string

optional

Two-digit numeric code that describes the reason for the transition

Allowable values: 00–31

validations

object

optional

Contains user information

Note: Please refer to the course’s appendix for details of the validations object and the descriptions of the channel and the reason_code values.

Line 4: We use the CARD_TOKEN value that we extracted in the previous code, for the card_token attribute.

Line 5: We set the required parameter state to ACTIVE.

Line 6: We set the required parameter channel to API since we use the API to process this request.

Note: You can enter values for the other optional parameters that are given in the table above.

Click the “Run” button in the code widget below to see the output.

Press + to interact
url = '{{BASE_URL}}cardtransitions'
data = json.dumps({
    "card_token": "{{CARD_TOKEN}}",
    "state": "ACTIVE",
    "channel": "API",
})
response = requests.post(url, headers=headers, data=data)
printResponse(response)

When the code is executed successfully, the output of the above code displays the complete card transition object with all the data fields. This includes the updated state.

In case of failure, an appropriate error message is displayed.

Update a card

We can update a card by making a PUT request to the {BASE_URL}/cards/{token} endpoint. The path parameter ({token}) refers to the token of the card to be updated. We also need to specify the fields that we would like to update in the body of the request.

Request Parameters

Parameter

Type

Category

Description

token

string

required

Token of the card we want to update

Note: This is a path parameter.

user_token

string

optional

Token of the user we would like to associate with the card

expedite

boolean

optional

True when we request the fulfillment provider to expedite the processing of the card, otherwise False

Default value: False

fulfillment

object

optional

Contains the shipping information and the physical characteristics of the card

metadata

object

optional

Adds metadata provided by the customer to the card

Allowable values: Maximum 20 key-value pairs allowed

Format: "my_name_1": "my_value_1"

Note: We can only update the values of the user_token and the expedite parameters in addition to the fulfillment and the metadata objects. Please refer to the card creation request parameters table given above to find the details of these parameters.

In the code below, we update the metadata of the card.

Note: You may opt to change any of the attribute(s) given in the table above.

Line 1: For token, we’ve used the CARD_TOKEN value that we saved earlier.

Line 7: We enter "card_purpose": "payment_card" to add this information to the metadata of the card.

Click the “Run” button in the code widget below to see the output.

Press + to interact
token = '{{CARD_TOKEN}}'
url = '{{BASE_URL}}cards/' + token
data = json.dumps({
    "metadata": { 
        "card_purpose": "payment_card"
    }
})
response = requests.put(url, headers=headers, data=data)
printResponse(response)

When the code is executed successfully, the output of the above code displays the complete card object that corresponds to the given token with all the data fields. This includes the updated ones.

In case of failure, an appropriate error message is displayed.