> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Issuance and Management

> The Cards API creates and manages cards for your customers over the entire life of a card — from issuance through activation, day-to-day management, reissuance, and termination.

This guide covers the Cards API itself. Before you issue your first card, work through [Design Your Card Program](/v2/docs/card-programs), [Card-Account Relationship and Funding Hierarchies](/v2/docs/card-accounts-funding), and [Card Products](/v2/docs/card-products) — those decisions are already baked into the card product by the time you call the API.

## Prerequisites

To issue a card you need three things:

<Steps>
  <Step title="A verified customer">
    A person who has passed KYC, or a business that has passed KYB. See [Create a Personal Customer](/v2/docs/create-a-personal-customer) and [KYC/KYB Verification](/v2/docs/kyc-kyb-verification).

    Gift card programs are the exception: card products with `issue_without_kyc` enabled can issue cards without verification.
  </Step>

  <Step title="An account that the customer owns">
    The account the card spends against, with cards enabled. See [Card-Account Relationship and Funding Hierarchies](/v2/docs/card-accounts-funding) for which account type to use.
  </Step>

  <Step title="An active card product">
    The `card_product_id` of the product you are issuing against. Retrieve it with [List Card Products](/v2/reference/listcardproducts).
  </Step>
</Steps>

## Card Lifecycle

```mermaid mermaid theme={"system"}
stateDiagram-v2
    request : Request card
    physical : Physical card
    virtual : Virtual card
    deliver : Deliver to customer
    present : Present digitally<br>to customer
    activate : Activate card
    monitor : Monitor card
    manage : Manage card
    reissue : Reissue card
    suspend : Suspend card
    terminate : Terminate card
    request --> physical
    request --> virtual
  virtual --> present
  physical --> deliver
  deliver --> activate
  present --> monitor
  activate --> monitor
  monitor --> manage
  manage --> reissue
  manage --> suspend
  manage --> terminate
```

* **Requesting card issuance** — you present an issuance request for a verified customer, an account belonging to them, and a card product. The request goes to Synctera's card vendor, who issues the card.
* **Presenting the card to the customer** — a physical card is delivered by mail; a virtual card's details are presented digitally through a secure channel.
* **Activating the card** — automatic for a virtual card. A physical card requires the customer to prove they received it.
* **Monitoring the card** — you are alerted to irregularities in card use.
* **Managing the card** — you respond to customer activity, requests, and security alerts, changing card data and status when appropriate.
* **Reissuing the card** — a new card replaces one that expired, was damaged, lost, or stolen, or that needs to change appearance or program.
* **Suspending the card** — temporarily blocking use, for suspected but unconfirmed fraud, or when a customer thinks they have misplaced their card.
* **Terminating the card** — permanently disabling the card, with no replacement.

### Card Status

The `status.card_status` field tracks where a card is in that life:

| Status        | Meaning                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `PENDING`     | The card has been requested but not yet issued. Check `status.pending_reasons` to see what it is waiting for. |
| `UNACTIVATED` | The card has been issued but not activated, and cannot be used.                                               |
| `ACTIVE`      | The card is available for full use.                                                                           |
| `SUSPENDED`   | The card is temporarily blocked and cannot be used until returned to active.                                  |
| `TERMINATED`  | The card may no longer be used. This is final.                                                                |
| `REJECTED`    | The issuance request was rejected.                                                                            |

A card sits in `PENDING` when something must happen before it can be manufactured. The `pending_reasons` object says which:

* `is_waiting_for_pin` — the card product's `pin_issuance_policy` is `REQUIRED` and no PIN has been set yet.
* `is_waiting_for_image` — the card uses a custom image that has not yet been uploaded and approved.
* `is_waiting_for_bulk_shipment` — the card ships as part of a bulk order that has not been released.

<Note>
  You can set only `ACTIVE`, `SUSPENDED`, and `TERMINATED` through [Update Card](/v2/reference/updatecard). The other statuses are set by the Synctera platform as the card moves through issuance.
</Note>

### Fulfillment Status

The `card_fulfillment_status` tracks digital presentation for virtual cards, and manufacturing and delivery for physical cards, separately from card status:

| Fulfillment status    | Meaning                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `DIGITALLY_PRESENTED` | A virtual card has been issued. This issuance is instant and the card is automatically activated and ready for use.       |
| `ISSUED`              | A physical card has been issued, but the order has not yet been sent to the fulfillment provider.                         |
| `ORDERED`             | The physical card order request has been sent to the fulfillment provider, who has successfully processed the order.      |
| `SHIPPED`             | The physical card has been shipped to the cardholder. Tracking is available for all shipping methods except `LOCAL_MAIL`. |
| `REJECTED`            | The physical card order failed.                                                                                           |
| `REISSUED`            | A physical card has been reissued. The card will go through the same fulfillment flow as new card issuance.               |

Fulfillment status is distinct from [card status](#card-status). A card can be `SHIPPED` while its card status is still `UNACTIVATED` — delivery and usability are tracked separately.

## Issue a Card

Use [Issue a Card](/v2/reference/issuecard) to request a card. Two things shape the request: the **card type** — `DEBIT` and `PREPAID` cards spend against a deposit account, `CREDIT` cards against a credit account — and the **form**, which determines whether the card is manufactured and shipped or generated instantly.

The response is the card object, including its `id`.

### Common Attributes

Physical and virtual cards share these attributes:

| Attribute                                                     | Description                                                                                     |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `id`                                                          | The card ID                                                                                     |
| `account_id`, `customer_id`, `business_id`, `card_product_id` | The account, customer, business, and product the card belongs to                                |
| `form`                                                        | `PHYSICAL` or `VIRTUAL`                                                                         |
| `type`                                                        | `DEBIT`, `CREDIT`, or `PREPAID`                                                                 |
| `emboss_name`                                                 | The name on the card. Defaults to the customer's first and last name. Limited to 21 characters. |
| `last_four`                                                   | The last four digits of the PAN                                                                 |
| `expiration_month`, `expiration_year`, `expiration_time`      | When the card expires                                                                           |
| `status`                                                      | Card status, status reason, memo, and pending reasons                                           |
| `is_pin_set`, `timestamp_pin_set`                             | Whether a PIN has been set, and when it was last changed                                        |
| `reissued_from_id`, `reissued_to_id`, `reissue_reason`        | Reissuance links and reason, if applicable                                                      |
| `metadata`                                                    | Optional key-value pairs of your own                                                            |
| `creation_time`, `last_updated_time`                          | When the card was requested and last modified                                                   |

<Note>
  `emboss_name` applies to both forms. On a physical card it is printed on the card; on a virtual card it is associated with the card and shown wherever you display the card's details.
</Note>

### Issue a Virtual Card

A virtual card is generated immediately. There is no manufacturing and no shipping, so there is nothing to wait for and no address to supply — and no separate activation step, because virtual cards activate automatically. Its fulfillment status is `DIGITALLY_PRESENTED`.

<CodeGroup>
  ```bash cURL theme={"system"}
  curl --request POST \
    --url "$baseurl/v2/cards" \
    --header "Authorization: Bearer $apikey" \
    --header "Content-Type: application/json" \
    --data '{
      "type": "DEBIT",
      "card_details": {
        "form": "VIRTUAL",
        "account_id": "{ACCOUNT_ID}",
        "customer_id": "{CUSTOMER_ID}",
        "card_product_id": "{CARD_PRODUCT_ID}"
      }
    }'
  ```
</CodeGroup>

Once the card exists, prompt the cardholder to set a PIN with the [Set PIN widget](/v2/docs/card-widgets-set-pin), and encourage them to add it to a digital wallet. See [Digital Wallets](/v2/docs/digital-wallets).

<Warning>
  Set a PIN even on a virtual card. A merchant point of sale can request one when the card is used through a digital wallet, and if no PIN is set that purchase cannot complete.
</Warning>

### Issue a Physical Card

A physical card is manufactured by a card fulfillment provider and shipped to the cardholder, so the request carries the name to emboss and where to send it. The card arrives `UNACTIVATED` and requires proof of possession before it can be used — see [Activate a Card](#activate-a-card).

<CodeGroup>
  ```bash cURL theme={"system"}
  curl --request POST \
    --url "$baseurl/v2/cards" \
    --header "Authorization: Bearer $apikey" \
    --header "Content-Type: application/json" \
    --data '{
      "type": "DEBIT",
      "card_details": {
        "form": "PHYSICAL",
        "account_id": "{ACCOUNT_ID}",
        "customer_id": "{CUSTOMER_ID}",
        "card_product_id": "{CARD_PRODUCT_ID}",
        "emboss_name": {
          "line_1": "Jane Smith"
        },
        "shipping": {
          "method": "LOCAL_MAIL",
          "recipient_name": "Jane Smith"
        }
      }
    }'
  ```
</CodeGroup>

Omit `emboss_name` and the card is embossed with the customer's first and last name. Omit `shipping.address` and it goes to the customer's shipping address on file.

#### Physical Card Attributes

Physical cards add fulfillment and shipping on top of the common attributes:

| Attribute                           | Description                                                                                                                                                                                                                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card_fulfillment_status`           | Where the card is in manufacturing and delivery                                                                                                                                                                                                                             |
| `shipping.address`                  | Where the card is mailed. Defaults to the customer's shipping address.                                                                                                                                                                                                      |
| `shipping.method`                   | `LOCAL_MAIL` (default), `LOCAL_PRIORITY`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_GROUND`, or `INTERNATIONAL_PRIORITY`. Additional fees apply to everything but `LOCAL_MAIL`. For more details, see [Card Shipping Overview](/docs/card-shipping-overview). |
| `shipping.recipient_name`           | Who should receive the card, often used for signature. Defaults to the customer's name.                                                                                                                                                                                     |
| `shipping.care_of_line`             | The person receiving the package on the recipient's behalf, when mailing somewhere other than the customer's address                                                                                                                                                        |
| `shipping.is_expedited_fulfillment` | Requests expedited printing (not expedited shipping). Can be supported upon request. Additional fees apply.                                                                                                                                                                 |
| `shipping.phone_number`             | Contact number for the carrier                                                                                                                                                                                                                                              |
| `card_image_id`                     | The custom image used for this card. See [Custom Cards](/v2/docs/custom-card-images).                                                                                                                                                                                       |
| `bulk_order_config_id`              | The bulk order this card ships under. See [Bulk Card Orders](/v2/docs/bulk-card-orders).                                                                                                                                                                                    |

<Tip>
  If a physical card comes back `PENDING` rather than progressing to `ORDERED`, read `status.pending_reasons`. The card is waiting on a PIN, a custom image approval, or a bulk shipment release before it can be manufactured.
</Tip>

### Track Issuance with Webhooks

Rather than polling, subscribe to card events. The platform emits `CARD.CREATED` when a card is created and `CARD.UPDATED` on every subsequent change — including card status and fulfillment status transitions, so you know when a card is ordered, shipped, or rejected in time to act on it.

Subscribe to `CARD.*` to receive all of them. See the [Webhooks guide](/v2/docs/webhooks-guide).

Other card events you can subscribe to:

| Event          | Fires when                                                 |
| -------------- | ---------------------------------------------------------- |
| `CARD.CREATED` | A card is created                                          |
| `CARD.UPDATED` | A card changes — status, fulfillment status, or attributes |

To read a card's current state at any point, use [Get Card](/v2/reference/getcard).

## Handling Sensitive Card Data

The PAN, CVV, expiration date, and PIN are sensitive and must be protected from everyone except the authorized cardholder. This data is exposed at activation and again whenever a cardholder wants to see their card details.

The Payment Card Industry (PCI) Data Security Standard defines what you must do when handling this data. Your sponsor bank and the card network require PCI compliance in your application, and getting certified is an involved and expensive process.

Synctera offers two paths.

### Widgets — No PCI Certification Required

Pre-built, PCI-compliant widgets run inside your application and send sensitive data directly between your customer and Synctera, so your systems never touch it. Each widget renders in an iframe and connects using a single-use token.

| Widget                                          | Purpose                                         |
| ----------------------------------------------- | ----------------------------------------------- |
| [Activate Card](/v2/docs/card-widgets-activate) | Collects the PAN and CVV to activate a card     |
| [Set PIN](/v2/docs/card-widgets-set-pin)        | Sets or resets a card's PIN                     |
| [Reveal Card](/v2/docs/card-widgets-reveal)     | Displays the full PAN, CVV, and expiration date |
| [Reveal PIN](/v2/docs/card-widgets-reveal-pin)  | Displays the current PIN                        |

See [Card Widgets](/v2/docs/card-widgets) to get started, and [Widget Theming](/v2/docs/card-widgets-theming) to match them to your app.

### Direct API — PCI Certification Required

If you are PCI certified, you can manage sensitive data directly:

| Endpoint                                               | Purpose                                                  |
| ------------------------------------------------------ | -------------------------------------------------------- |
| [Set Card PIN](/v2/reference/setcardpin)               | Sets a card's PIN                                        |
| [Reveal Card Details](/v2/reference/revealcarddetails) | Returns the card's sensitive details, encrypted as a JWE |

Both endpoints are disabled by default. Access is granted on confirmation of your PCI certification — work with your Synctera representative to enable them.

## Activate a Card

Virtual cards activate automatically. Physical cards require proof that the customer received the card. There are three methods.

<AccordionGroup>
  <Accordion title="Activation widget">
    For cards with the full PAN and CVV printed on them. The customer logs into your app, chooses to activate a card, and enters those values. The widget sends them to Synctera's card vendor.

    See [Activate Card Widget](/v2/docs/card-widgets-activate).
  </Accordion>

  <Accordion title="Barcode">
    For cards with no PAN and CVV printed on them, or only a partial PAN. The card issuer generates a unique barcode value, and the fulfillment vendor prints it as a Code 128 barcode on the card or carrier.

    The customer scans the barcode in your app. You convert it back to a string and send it to [Activate Card](/v2/reference/activatecard) as `activation_code`, along with the `customer_id`.

    ```bash cURL theme={"system"}
    curl --request POST \
      --url "$baseurl/v2/cards/activate" \
      --header "Authorization: Bearer $apikey" \
      --header "Content-Type: application/json" \
      --data '{
        "activation_code": "{BARCODE_VALUE}",
        "customer_id": "{CUSTOMER_ID}"
      }'
    ```

    In sandbox, retrieve a test card's barcode with [Get Card Barcode](/v2/reference/getcardbarcode). This endpoint is available in test environments only.
  </Accordion>

  <Accordion title="Update Card">
    Depending on your risk appetite and your other means of verifying that the cardholder has the card in hand, you can activate a card by setting its status to `ACTIVE` with [Update Card](/v2/reference/updatecard).

    This requires no proof of possession, so it is on you to perform whatever due diligence you need to authenticate the customer.
  </Accordion>
</AccordionGroup>

<Warning>
  Prompt the customer to set a PIN when they activate. Even virtual cards used through a digital wallet can be asked for a PIN at a merchant point of sale — and if no PIN is set, that purchase cannot complete.
</Warning>

## Manage a Card

### View Cards

[List Cards](/v2/reference/listcards) returns the cards you have issued. Filter by customer, account, embossed name, last four digits, expiration date, card type, brand, form, card product, and cardholder postal code, and sort by expiration date.

[Get Card](/v2/reference/getcard) returns a single card by ID.

#### View Card History

Subscribe to `CARD.UPDATED` webhooks to receive every change as it happens, and use [Get Card](/v2/reference/getcard) to read the current state.

### Set or Reset a PIN

Use the [Set PIN widget](/v2/docs/card-widgets-set-pin), or [Set Card PIN](/v2/reference/setcardpin) if you are PCI certified. Check `is_pin_set` to see whether a card has a PIN, and `timestamp_pin_set` for when it last changed.

### Reset PIN Tries

If someone enters a card's PIN incorrectly too many times in a short period — typically at an ATM or point-of-sale device — the card vendor suspends the card. Its status becomes `SUSPENDED` and the cardholder will most likely contact you.

There are three courses of action:

* **If fraud occurred**, reissue the card. This resets the PIN tries on the new card.
* **If the customer has forgotten their PIN**, have them reset it with the Set PIN widget, then set the card back to `ACTIVE`.
* **If the customer remembers their PIN correctly**, set the card back to `ACTIVE`.

You can also handle status changes and reissuance through the Synctera dashboard when a support agent is working with the customer.

### Lock and Unlock a Card

Customers often want to temporarily disable a card — a misplaced wallet, a suspicious charge they want to investigate. Suspend the card with [Update Card](/v2/reference/updatecard) and reactivate it the same way:

<CodeGroup>
  ```bash Lock theme={"system"}
  curl --request PATCH \
    --url "$baseurl/v2/cards/{CARD_ID}" \
    --header "Authorization: Bearer $apikey" \
    --header "Content-Type: application/json" \
    --data '{
      "card_status": "SUSPENDED",
      "reason": "REQ",
      "memo": "Customer misplaced card"
    }'
  ```

  ```bash Unlock theme={"system"}
  curl --request PATCH \
    --url "$baseurl/v2/cards/{CARD_ID}" \
    --header "Authorization: Bearer $apikey" \
    --header "Content-Type: application/json" \
    --data '{
      "card_status": "ACTIVE",
      "reason": "REQ"
    }'
  ```
</CodeGroup>

Unlike termination, suspension is reversible. Use `reason` to record why the status changed and `memo` for free-text detail.

### Reissue a Card

A card may be reissued because it is expiring, was lost or stolen or damaged, or needs to change appearance or program. You reissue by calling [Issue a Card](/v2/reference/issuecard) with `reissued_from_id` set to the card being replaced and `reissue_reason` set to why.

The reason determines whether the replacement keeps the same PAN, and when the old card is terminated:

| Reason           | Same PAN | Old card terminated | Use when                                                 |
| ---------------- | -------- | ------------------- | -------------------------------------------------------- |
| `EXPIRATION`     | Yes      | On activation       | The card is approaching its expiration date              |
| `DAMAGED`        | Yes      | On activation       | The customer requests a replacement for a damaged card   |
| `APPEARANCE`     | Yes      | On activation       | The name printed on the card or its custom image changes |
| `PRODUCT_CHANGE` | Yes      | On activation       | The card moves to a different product                    |
| `PROGRAM_CHANGE` | Yes      | On activation       | The card moves to a different program                    |
| `BANK_MIGRATION` | Yes      | On activation       | Cards are migrated to a different sponsor bank           |
| `LOST`           | No       | Immediately         | The customer reports the card lost                       |
| `STOLEN`         | No       | Immediately         | The customer reports the card stolen                     |

In every case the replacement card gets a new CVV and expiration date, **keeps the same PIN** as the original, and inherits its digital wallet tokens — cardholders do not need to re-add the card to Apple Pay or Google Pay. Cards already on file with merchants are updated automatically too.

Synctera terminates the old card at the right moment for you. For reasons that terminate on activation, the old card stays usable until the replacement is activated or its expiration date arrives, so the customer is never without a working card.

<Tip>
  **Automating expiration reissuance.** Use [List Cards](/v2/reference/listcards) with the `expires_before` filter, or sort by `expiration_date`, to find cards that are about to expire. From there you can run a background job that reissues them without customer interaction, or prompt the customer through a reissuance flow where they confirm the shipping address. An expiration reissuance must be requested **before** the actual expiration date.
</Tip>

### Terminate a Card

Set the card's status to `TERMINATED` with [Update Card](/v2/reference/updatecard):

```bash cURL theme={"system"}
curl --request PATCH \
  --url "$baseurl/v2/cards/{CARD_ID}" \
  --header "Authorization: Bearer $apikey" \
  --header "Content-Type: application/json" \
  --data '{
    "card_status": "TERMINATED",
    "reason": "REQ",
    "memo": "Customer requested closure"
  }'
```

Synctera notifies the card vendor, which terminates the card. **Termination is permanent** — a terminated card cannot be reactivated. If the customer needs a working card afterward, issue a new one.

## A Typical Card Workflow

An example covering a physical debit card from creation to cancellation, activated by barcode.

### Requesting Card Issuance

1. You offer a card product to a customer. Call [List Card Products](/v2/reference/listcardproducts) and note the `id` of the product you want to offer.
2. The customer signs up and accepts the card disclosure. Disclosure is generally handled as part of account onboarding, but can be a separate process. See [Record Disclosure Acceptance](/v2/docs/record-disclosure-acceptance).
3. You call [Issue a Card](/v2/reference/issuecard) with the customer, account, card product, embossed name, and optional shipping information. The response contains the card object and its ID.
4. You receive `CARD.UPDATED` webhooks as the card is ordered, manufactured, and shipped, so you can keep the customer informed and react if the card is rejected.

```mermaid mermaid theme={"system"}
%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
FinTech->>Customer: Offer card product
Customer->>FinTech: Sign me up
FinTech->>Synctera Platform: "Issue a Card"
Synctera Platform->>FinTech: CARD.CREATED webhook
Synctera Platform->>FinTech: CARD.UPDATED webhooks<br>(ordered, shipped)
```

### Activating a Card

1. Your customer receives the card, logs into your app, and scans the barcode with their phone camera.
2. Your app translates the barcode into its value.
3. You call [Activate Card](/v2/reference/activatecard) with that value and the customer ID.
4. The Cards API requests activation through the card vendor.
5. You prompt the customer to set a PIN using the Set PIN widget.
6. The widget sends the PIN directly to the card vendor.
7. The card vendor activates the card and notifies the Synctera platform.
8. The card's status becomes `ACTIVE`, and you receive a `CARD.UPDATED` webhook.

```mermaid mermaid theme={"system"}
%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: Scan barcode on card
FinTech->>FinTech: Translate barcode to value
FinTech->>Synctera Platform: Send barcode value:<br>"Activate Card"
Synctera Platform->>Card Vendor: Activate card
Customer->>FinTech: Set PIN through widget
FinTech->>Card Vendor: Widget sends PIN
Card Vendor->>Card Vendor: Activate card
Card Vendor->>Synctera Platform: Card is active
Synctera Platform->>FinTech: CARD.UPDATED: ACTIVE
```

### Reissuing a Card

1. Your customer reports that they lost the card.
2. You call [Issue a Card](/v2/reference/issuecard) with the same details as the original, plus `reissue_reason` of `LOST` and `reissued_from_id` of the lost card. You can also do this from the Synctera dashboard.
3. Synctera immediately terminates the lost card with the card vendor and sets its status to `TERMINATED`.
4. The new card is issued and activated just as the lost card was — with a new PAN, but the same PIN.

```mermaid mermaid theme={"system"}
%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: I lost my card
FinTech->>Synctera Platform: "Issue a Card"<br>reissue_reason: LOST
Synctera Platform->>Card Vendor: Terminate card
Synctera Platform->>Synctera Platform: Old card: TERMINATED
Synctera Platform->>Card Vendor: Issue new card
Card Vendor->>Customer: New card, new PAN, same PIN
```

### Cancelling a Card

1. The customer cancels the card.
2. You call [Update Card](/v2/reference/updatecard) to set the status to `TERMINATED`. You can also do this from the Synctera dashboard.
3. Synctera notifies the card vendor.
4. The card vendor terminates the card.

```mermaid mermaid theme={"system"}
%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: Cancel my card
FinTech->>Synctera Platform: "Update Card" to<br>TERMINATED status
Synctera Platform->>Card Vendor: Terminate card
Card Vendor->>Card Vendor: Terminate card
```