--- title: "Update Card" method: PATCH path: "/cards/{card_id}" tags: ["Cards"] --- # Update Card `PATCH /cards/{card_id}` Integrators can update the card resource to change status, update shipping (if the card hasn't been shipped) or edit metadata. ## Path parameters - `card_id` string, uuid, required — The unique identifier of a card ## Headers - `Idempotency-Key` string ## Request body - CardEditRequest - `card_status` 'ACTIVE' | 'SUSPENDED' | 'TERMINATED' — The status indicating the card lifecycle state - `customer_id` string, uuid — The ID of the customer to whom the card will be issued - `emboss_name` EmbossName — The customer details to emboss on the card - Defaults to customer first and last name. Is limited to 21 characters. Valid characters are A-Z, a-z, 0-9, space ( ), period (.), comma (,), forward slash (/), hyphen (-), ampersand (&), single quote ('). - `line_1` string, required — line 1 - `line_2` string — line 2 - `memo` string — Additional details about the reason for the status change - `metadata` CardMetadata — Additional data to include in the request structured as key-value pairs - `reason` 'ACT' | 'ADD' | 'AUX' | 'CLO' | 'COM' | 'DOB' | 'EML' | 'EXP' | 'FRD' | 'FUL' | 'INA' | 'INF' | 'ISS' | 'KYC' | 'LOS' | 'MAT' | 'NAM' | 'NEG' | 'NEW' | 'OTH' | 'OUT' | 'PHO' | 'PIN' | 'PRC' | 'REQ' | 'REV' | 'SSN' | 'STO' | 'SUS' | 'TMP' | 'UNK' — The reason for the card status Code | Description --- | --- NEW | Card activated REQ | Requested by you INA | Dormant UNK | Invalid shipping address NEG | Negative account balance REV | Account under review SUS | Suspicious activity OUT | Activity outside program parameters FRD | Confirmed fraud MAT | Matched with an OFAC list LOS | Card reported lost CLO | Card was cloned COM | Account or card was compromised TMP | Awaiting customer confirmation PRC | Initiated by Processor ISS | Initiated by Issuer EXP | Card expired KYC | Failed KYC INF | Information was validated ACT | Account activity was validated AUX | Initiated by a third party PIN | PIN try limit reached STO | Card reported stolen ADD | Address issue NAM | Name issue SSN | SSN issue DOB | DOB issue EML | Email issue PHO | Phone issue FUL | Account/fulfillment mismatch OTH | Other ## Response `200` Card issued - union - VirtualCardResponse — A virtual card - `card_status` 'ACTIVE' | 'IMAGE_PENDING' | 'IMAGE_REJECTED' | 'PENDING' | 'REJECTED' | 'SUSPENDED' | 'TERMINATED' | 'UNACTIVATED', required — The status indicating the card lifecycle state - `memo` string — Additional details about the reason for the status change - `pending_reasons` CardStatusPendingReasons — reasons why the card status is PENDING - `is_waiting_for_bulk_shipment` boolean — The card is to be shipping as part of a bulk shipment but that bulk shipment has not yet been released. - `is_waiting_for_image` boolean — The card has a custom image and either that image hasn't yet been uploaded and approved or the card has not yet been processed by the periodic daily custom card image processing task. - `is_waiting_for_pin` boolean — The card requires a PIN to be set before it can be issued (refer to the pin_issuance_policy of the related card product). The PIN has not yet been set and not enough time has passed to use a random PIN (if applicable). - `status_reason` 'ACT' | 'ADD' | 'AUX' | 'CLO' | 'COM' | 'DOB' | 'EML' | 'EXP' | 'FRD' | 'FUL' | 'INA' | 'INF' | 'ISS' | 'KYC' | 'LOS' | 'MAT' | 'NAM' | 'NEG' | 'NEW' | 'OTH' | 'OUT' | 'PHO' | 'PIN' | 'PRC' | 'REQ' | 'REV' | 'SSN' | 'STO' | 'SUS' | 'TMP' | 'UNK', required — The reason for the card status Code | Description --- | --- NEW | Card activated REQ | Requested by you INA | Dormant UNK | Invalid shipping address NEG | Negative account balance REV | Account under review SUS | Suspicious activity OUT | Activity outside program parameters FRD | Confirmed fraud MAT | Matched with an OFAC list LOS | Card reported lost CLO | Card was cloned COM | Account or card was compromised TMP | Awaiting customer confirmation PRC | Initiated by Processor ISS | Initiated by Issuer EXP | Card expired KYC | Failed KYC INF | Information was validated ACT | Account activity was validated AUX | Initiated by a third party PIN | PIN try limit reached STO | Card reported stolen ADD | Address issue NAM | Name issue SSN | SSN issue DOB | DOB issue EML | Email issue PHO | Phone issue FUL | Account/fulfillment mismatch OTH | Other - `account_id` string, uuid, required — The ID of the account to which the card will be linked - `business_id` string, uuid — The business ID associated with this card. If no customer_id is supplied, a card can still be issued to a business, but cannot be activated or used until a customer is assigned via the PATCH /cards/{card_id} endpoint. - `card_product_id` string, uuid, required — The card product to which the card is attached - `creation_time` string, date-time, required — The timestamp representing when the card issuance request was made - `customer_id` string, uuid — The ID of the customer to whom the card will be issued. If a business_id is passed, but a customer_id not passed at the time of card creation the card cannot be activated or used for spend until it's assigned to a human customer via the PATCH /cards/{card_id} endpoint. If no business_id is passed, a customer_id is required. - `emboss_name` EmbossName, required — The customer details to emboss on the card - Defaults to customer first and last name. Is limited to 21 characters. Valid characters are A-Z, a-z, 0-9, space ( ), period (.), comma (,), forward slash (/), hyphen (-), ampersand (&), single quote ('). - `line_1` string, required — line 1 - `line_2` string — line 2 - `expiration_month` string, required - `expiration_time` string, date-time — The timestamp representing when the card would expire at - `expiration_year` string, required - `id` string, uuid, required — Card ID - `is_pin_set` boolean — indicates whether a pin has been set on the card - `last_four` string, required — The last 4 digits of the card PAN - `last_modified_time` string, date-time — The timestamp representing when the card was last modified at - `metadata` CardMetadata — Additional data to include in the request structured as key-value pairs - `reissue_reason` 'APPEARANCE' | 'DAMAGED' | 'EXPIRATION' | 'LOST' | 'NAME_CHANGE' | 'PRODUCT_CHANGE' | 'STOLEN' | 'VIRTUAL_TO_PHYSICAL' — This is the reason the card needs to be reissued, if any. The reason determines several behaviours: - whether or not the new card will use the same PAN as the original card - the old card will be terminated and if so, when it will be terminated Reason | Same PAN | Terminate Old Card ---------------------- | -------- | ------------------ EXPIRATION | yes | on activation LOST | no | immediately STOLEN | no | immediately DAMAGED | yes | on activation VIRTUAL_TO_PHYSICAL(*) | yes | on activation PRODUCT_CHANGE | yes | on activation NAME_CHANGE(**) | yes | on activation APPEARANCE | yes | on activation (*) VIRTUAL_TO_PHYSICAL is deprecated. Please use PRODUCT_CHANGE whenever reissuing from one card product to another, including from a virtual product to a physical product. (**) NAME_CHANGE is deprecated. Please use APPEARANCE whenever reissuing in order to change the appearance of a card, such as the printed name or custom image. For all reasons, the new card will use the same PIN as the original card and digital wallet tokens will reassigned to the new card - `reissued_from_id` string, uuid — When reissuing a card, specify the card to be replaced here. When getting a card's details, if this card was issued as a reissuance of another card, this ID refers to the card was replaced. If this field is set, then reissue_reason must also be set. - `reissued_to_id` string, uuid — If this card was reissued, this ID refers to the card that replaced it. - `timestamp_pin_set` string, date-time — Time when the PIN was last set or changed. - `type` 'DEBIT' | 'PREPAID', required — The type of the card program and BIN - `form` 'PHYSICAL' | 'VIRTUAL', required — PHYSICAL or VIRTUAL. - `bin` string — The bin number - `card_brand` 'MASTERCARD' | 'VISA', required — The brand of a card product - `tenant` string, required — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. - PhysicalCardResponse — The status of the card - `account_id` string, uuid, required — The ID of the account to which the card will be linked - `business_id` string, uuid — The business ID associated with this card. If no customer_id is supplied, a card can still be issued to a business, but cannot be activated or used until a customer is assigned via the PATCH /cards/{card_id} endpoint. - `card_product_id` string, uuid, required — The card product to which the card is attached - `creation_time` string, date-time, required — The timestamp representing when the card issuance request was made - `customer_id` string, uuid — The ID of the customer to whom the card will be issued. If a business_id is passed, but a customer_id not passed at the time of card creation the card cannot be activated or used for spend until it's assigned to a human customer via the PATCH /cards/{card_id} endpoint. If no business_id is passed, a customer_id is required. - `emboss_name` EmbossName, required — The customer details to emboss on the card - Defaults to customer first and last name. Is limited to 21 characters. Valid characters are A-Z, a-z, 0-9, space ( ), period (.), comma (,), forward slash (/), hyphen (-), ampersand (&), single quote ('). - `line_1` string, required — line 1 - `line_2` string — line 2 - `expiration_month` string - `expiration_time` string, date-time — The timestamp representing when the card would expire at - `expiration_year` string - `id` string, uuid, required — Card ID - `is_pin_set` boolean — indicates whether a pin has been set on the card - `last_four` string — The last 4 digits of the card PAN - `last_modified_time` string, date-time — The timestamp representing when the card was last modified at - `metadata` CardMetadata — Additional data to include in the request structured as key-value pairs - `reissue_reason` 'APPEARANCE' | 'DAMAGED' | 'EXPIRATION' | 'LOST' | 'NAME_CHANGE' | 'PRODUCT_CHANGE' | 'STOLEN' | 'VIRTUAL_TO_PHYSICAL' — This is the reason the card needs to be reissued, if any. The reason determines several behaviours: - whether or not the new card will use the same PAN as the original card - the old card will be terminated and if so, when it will be terminated Reason | Same PAN | Terminate Old Card ---------------------- | -------- | ------------------ EXPIRATION | yes | on activation LOST | no | immediately STOLEN | no | immediately DAMAGED | yes | on activation VIRTUAL_TO_PHYSICAL(*) | yes | on activation PRODUCT_CHANGE | yes | on activation NAME_CHANGE(**) | yes | on activation APPEARANCE | yes | on activation (*) VIRTUAL_TO_PHYSICAL is deprecated. Please use PRODUCT_CHANGE whenever reissuing from one card product to another, including from a virtual product to a physical product. (**) NAME_CHANGE is deprecated. Please use APPEARANCE whenever reissuing in order to change the appearance of a card, such as the printed name or custom image. For all reasons, the new card will use the same PIN as the original card and digital wallet tokens will reassigned to the new card - `reissued_from_id` string, uuid — When reissuing a card, specify the card to be replaced here. When getting a card's details, if this card was issued as a reissuance of another card, this ID refers to the card was replaced. If this field is set, then reissue_reason must also be set. - `reissued_to_id` string, uuid — If this card was reissued, this ID refers to the card that replaced it. - `timestamp_pin_set` string, date-time — Time when the PIN was last set or changed. - `type` 'DEBIT' | 'PREPAID', required — The type of the card program and BIN - `form` 'PHYSICAL' | 'VIRTUAL', required — PHYSICAL or VIRTUAL. - `card_image_id` string, uuid — The ID of the custom card image used for this card - `shipping` Shipping, required — Details about the shipping method. If supplied this will override the default shipping address of the customer or account. - `address` Address1 - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `city` string, required — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `postal_code` string, required — Postal code - `state` string, required — State, region, province, or prefecture - `care_of_line` string — The name of the person to send in care of - `is_expedited_fulfillment` boolean — Is the shipment expedited - `method` 'INTERNATIONAL' | 'INTERNATIONAL_GROUND' | 'INTERNATIONAL_PRIORITY' | 'LOCAL_MAIL' | 'LOCAL_PRIORITY' | 'OVERNIGHT' | 'TWO_DAY' — The shipping method. * `INTERNATIONAL_GROUND` is only available for addresses in Canada and Mexico. - `phone_number` string — The phone number of the recipient - `recipient_name` RecipientName — The name of the recipient to whom the card will be shipped - `first_name` string, required - `last_name` string, required - `middle_name` string - `card_status` 'ACTIVE' | 'IMAGE_PENDING' | 'IMAGE_REJECTED' | 'PENDING' | 'REJECTED' | 'SUSPENDED' | 'TERMINATED' | 'UNACTIVATED', required — The status indicating the card lifecycle state - `memo` string — Additional details about the reason for the status change - `pending_reasons` CardStatusPendingReasons — reasons why the card status is PENDING - `is_waiting_for_bulk_shipment` boolean — The card is to be shipping as part of a bulk shipment but that bulk shipment has not yet been released. - `is_waiting_for_image` boolean — The card has a custom image and either that image hasn't yet been uploaded and approved or the card has not yet been processed by the periodic daily custom card image processing task. - `is_waiting_for_pin` boolean — The card requires a PIN to be set before it can be issued (refer to the pin_issuance_policy of the related card product). The PIN has not yet been set and not enough time has passed to use a random PIN (if applicable). - `status_reason` 'ACT' | 'ADD' | 'AUX' | 'CLO' | 'COM' | 'DOB' | 'EML' | 'EXP' | 'FRD' | 'FUL' | 'INA' | 'INF' | 'ISS' | 'KYC' | 'LOS' | 'MAT' | 'NAM' | 'NEG' | 'NEW' | 'OTH' | 'OUT' | 'PHO' | 'PIN' | 'PRC' | 'REQ' | 'REV' | 'SSN' | 'STO' | 'SUS' | 'TMP' | 'UNK', required — The reason for the card status Code | Description --- | --- NEW | Card activated REQ | Requested by you INA | Dormant UNK | Invalid shipping address NEG | Negative account balance REV | Account under review SUS | Suspicious activity OUT | Activity outside program parameters FRD | Confirmed fraud MAT | Matched with an OFAC list LOS | Card reported lost CLO | Card was cloned COM | Account or card was compromised TMP | Awaiting customer confirmation PRC | Initiated by Processor ISS | Initiated by Issuer EXP | Card expired KYC | Failed KYC INF | Information was validated ACT | Account activity was validated AUX | Initiated by a third party PIN | PIN try limit reached STO | Card reported stolen ADD | Address issue NAM | Name issue SSN | SSN issue DOB | DOB issue EML | Email issue PHO | Phone issue FUL | Account/fulfillment mismatch OTH | Other - `card_fulfillment_status` 'DIGITALLY_PRESENTED' | 'ISSUED' | 'ORDERED' | 'REISSUED' | 'REJECTED' | 'REORDERED' | 'SHIPPED', required — The status indicating the state of the card issuance - `fulfillment_details` FulfillmentDetails - `ship_date` string, date — The date that the card was shipped as reported by the card fulfillment provider - `shipping_method` string — The specific shipping method as reported by the card fulfillment provider - `tracking_number` string — The shipment tracking number - `tracking_number` string — This contains all shipping details as provided by the card fulfillment provider, including the tracking number. This field is deprecated. Instead, please use the fulfillment_details object, which includes a field for just the tracking number. - `bin` string — The bin number - `card_brand` 'MASTERCARD' | 'VISA', required — The brand of a card product - `physical_card_format` 'CHIP' | 'CONTACT' | 'CONTACTLESS' | 'MAGNETIC_STRIPE' | 'PHYSICAL_COMBO', required — The format of a physical card product - `tenant` string, required — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. ## Other responses - `400` — BadRequest - `401` — Unauthorized - `403` — Forbidden error - `422` — Unprocessable entity request response - `500` — Internal server error --- [API](https://skmtc.net/synctera/apis/synctera-api.md) · [All operations](https://skmtc.net/synctera/apis/synctera-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/synctera/synctera-api/versions/b0d812e6cdd0/schema)