CHcheckout
Cards

Update card details

Update the details of an issued card.

Only the fields for which you provide values will be updated. If you pass null, the existing value will be removed.

patch/issuing/cards/{cardId}

Request

Path parameters

cardIdstring required

The card's unique identifier.

Example:crd_fa6psq242dcd6fdn5gifcq1491

Request body

status'active'

Set the card's status to active to activate an inactive or suspended card.

If you submit this field, you cannot specify a scheduled_activation_date. If you do, you receive a scheduled_activation_date_conflicts_with_activation error.

referencestring

Your reference.

expiry_monthinteger

The card's expiration month.

expiry_yearinteger

The card's expiration year.

scheduled_revocation_datestring date

The card will be revoked at midnight UTC on the date specified.

  • Format: YYYY-MM-DD
revocation_datestring date

Deprecated. Use scheduled_revocation_date instead.

Date scheduling the card's automatic revocation.

  • Supported format: YYYY-MM-DD (time is midnight UTC)
scheduled_activation_datestring

Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:

  • Date only: YYYY-MM-DD (treated as midnight UTC)
  • Date with round hour: YYYY-MM-DDTHH:mmZ (UTC) or YYYY-MM-DDTHH:mm±HH:mm (offset)

Only round hours are allowed when a time is provided (HH:00). The value must be at least the next round hour after the request time.

Example request

{
  "status": "active",
  "reference": "X-123456-N11",
  "metadata": {
    "udf1": "metadata1",
    "udf2": "metadata2",
    "udf3": "metadata3",
    "udf4": "metadata4",
    "udf5": "metadata5"
  },
  "expiry_month": 5,
  "expiry_year": 2025,
  "scheduled_revocation_date": "2027-03-12T00:00:00.0000000",
  "revocation_date": "2027-03-12T00:00:00.0000000",
  "scheduled_activation_date": "2026-06-01T10:00Z"
}

Response

Card updated successfully

idstring required

The card's unique identifier.

client_idstring required

The client's unique identifier.

entity_idstring required

The entity's unique identifier.

cardholder_idstring required

The cardholder's unique identifier.

card_product_idstring required

The card product's unique identifier.

user_idstring

The Dashboard user's unique identifier.

last_fourstring required

The last four digits of the card number, also known as the PAN.

expiry_monthinteger required

The card's expiration month.

expiry_yearinteger required

The card's expiration year.

status'active' | 'inactive' | 'revoked' | 'suspended' required

The card's status, which determines whether it can approve incoming authorizations:

  • inactive: the default state - authorizations will be declined until the card is activated
  • active: authorization requests can be approved
  • suspended: incoming authorization requests will be declined - the card can be reactivated to accept new authorizations
  • revoked: incoming authorization requests will be permanently declined - the card cannot be reactivated from this state
display_namestring

The name to display on the card.

typestring required

The card type.

billing_currencystring ISO4217 required

The issuing currency, as a three-letter <a href="https://docs.checkout.com/docs/currency-codes" target="blank">ISO currency code</a>.

issuing_countrystring required

The issuing country, as a two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="blank" >ISO country code</a>.

referencestring

Your reference.

scheduled_revocation_datestring date

The card will be revoked at midnight UTC on the date specified.

  • Format: YYYY-MM-DD
revocation_datestring date

Deprecated. Use scheduled_revocation_date instead.

Date scheduling the card's automatic revocation.

  • Supported format: YYYY-MM-DD (time is midnight UTC)
scheduled_activation_datestring

Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:

  • Date only: YYYY-MM-DD (treated as midnight UTC)
  • Date with round hour: YYYY-MM-DDTHH:mmZ (UTC) or YYYY-MM-DDTHH:mm±HH:mm (offset)

Only round hours are allowed when a time is provided (HH:00). The value must be at least the next round hour after the request time.

last_activated_onstring date-time nullable

The date and time the card was last activated.

If the card has never been activated, this field returns null.

root_card_idstring

When a card is renewed, the unique identifier of the first card in the renewal history.

parent_card_idstring

When a card is renewed, the unique identifier of the previous card in the renewal history.

scheme'mastercard' | 'visa' required

the card scheme.

created_datestring UTC
last_modified_datestring UTC required

Example response

{
  "id": "crd_fa6psq242dcd6fdn5gifcq1491",
  "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
  "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
  "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
  "user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
  "last_four": "1234",
  "expiry_month": 5,
  "expiry_year": 2025,
  "status": "active",
  "display_name": "JOHN KENNEDY",
  "billing_currency": "USD",
  "issuing_country": "US",
  "reference": "X-123456-N11",
  "metadata": {
    "udf1": "metadata1",
    "udf2": "metadata2",
    "udf3": "metadata3",
    "udf4": "metadata4",
    "udf5": "metadata5"
  },
  "scheduled_revocation_date": "2027-03-12T00:00:00.0000000",
  "revocation_date": "2027-03-12T00:00:00.0000000",
  "scheduled_activation_date": "2026-06-01T10:00Z",
  "last_activated_on": "2019-09-10T10:11:12.0000000+00:00",
  "root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
  "parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
  "scheme": "mastercard",
  "created_date": "2021-09-09T19:41:39Z",
  "last_modified_date": "2021-09-09T19:41:39Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "credentials": {
      "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "revoke": {
      "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
      "actions": [
        "POST"
      ],
      "types": [
        "application/json"
      ]
    },
    "controls": {
      "href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.