> ## 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.

# Debit Card

> A walkthrough of a consumer debit card program end to end: verified customer, checking account, virtual card for immediate spend, and a physical card in the mail.

This guide follows the virtual-first pattern Synctera recommends. Your customer gets a virtual card they can use the moment onboarding completes, and a physical card arrives a few days later.

The `curl` examples assume you have set up `baseurl` and `apikey` environment variables. See [Base URL](/v2/reference/environments) and [Authentication](/v2/reference/authentication). Identifiers produced by earlier steps are written like `{ACCOUNT_ID}`.

## What you are building

```mermaid mermaid theme={"system"}
%%{init: {"fontFamily": "sans-serif"}}%%
flowchart LR
  P["Person<br/>KYC ACCEPTED"] --> A["CHECKING account<br/>is_card_enabled: true"]
  A --> V["Virtual debit card<br/>active immediately"]
  A --> F["Physical debit card<br/>activated on arrival"]
```

## Step 1 — Create and verify the customer

Create a personal customer and run KYC. The customer must reach a `verification_status` of `ACCEPTED` before they can hold an account or use a card.

See [Create a Personal Customer](/v2/docs/create-a-personal-customer) and [KYC/KYB Verification](/v2/docs/kyc-kyb-verification).

Record the disclosures your program requires as part of onboarding — typically the USA Patriot Act notice, E-Sign consent, the privacy notice, and your deposit account agreement. See [Record Disclosure Acceptance](/v2/docs/record-disclosure-acceptance).

We refer to the resulting person's UUID as `{CUSTOMER_ID}`.

## Step 2 — Create an account template

The template defines the shape of every checking account you open for this program. Cards must be enabled on it.

<CodeGroup>
  ```shell Shell theme={"system"}
  curl -X POST "$baseurl/v0/accounts/templates" \
    -H "Authorization: Bearer $apikey" \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "name": "consumer debit checking",
      "description": "Checking accounts backing consumer debit cards",
      "is_enabled": true,
      "template": {
        "account_type": "CHECKING",
        "bank_country": "US",
        "currency": "USD",
        "is_ach_enabled": true,
        "is_card_enabled": true,
        "is_p2p_enabled": true,
        "overdraft_limit": 0
      }
    }'
  ```
</CodeGroup>

Note the returned `id` — we refer to it as `{ACCOUNT_TEMPLATE_ID}`.

<Tip>
  You only build the template once, not once per customer. If you want every account in this program to carry the same spending limits or fee structure, attach a `spend_control_id` and a fee product to the template now — accounts inherit them at creation. See [Spend Controls](/v2/docs/spend-controls-guide) and [Fees and Rewards](/v2/docs/fees-and-rewards).
</Tip>

## Step 3 — Create the account

Create the checking account from the template, with the customer as its holder. See [Create Accounts](/v2/docs/create-accounts-guide) for the full request and for account relationships.

We refer to the resulting account's UUID as `{ACCOUNT_ID}`.

## Step 4 — Find your card product

List your card products and pick the debit product you intend to issue against. You need one product per form — a virtual product and a physical product.

<CodeGroup>
  ```shell Shell theme={"system"}
  curl -X GET "$baseurl/v2/cards/products" \
    -H "Authorization: Bearer $apikey"
  ```
</CodeGroup>

Check that `active` is `true`, and note the `id` of each. We refer to them as `{VIRTUAL_CARD_PRODUCT_ID}` and `{PHYSICAL_CARD_PRODUCT_ID}`. See [Card Products](/v2/docs/card-products) for what each field on the product controls.

## Step 5 — Issue a virtual card

Issue the virtual card as the last step of onboarding, so the customer can spend immediately.

<CodeGroup>
  ```shell Shell theme={"system"}
  curl -X POST "$baseurl/v2/cards" \
    -H "Authorization: Bearer $apikey" \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "type": "DEBIT",
      "card_details": {
        "form": "VIRTUAL",
        "account_id": "{ACCOUNT_ID}",
        "customer_id": "{CUSTOMER_ID}",
        "card_product_id": "{VIRTUAL_CARD_PRODUCT_ID}"
      }
    }'
  ```
</CodeGroup>

Virtual cards activate automatically — the card comes back `ACTIVE`, with no activation step.

Show the card details to the customer with the [Reveal Card widget](/v2/docs/card-widgets-reveal), and prompt them to set a PIN with the [Set PIN widget](/v2/docs/card-widgets-set-pin). A PIN matters even for a virtual card: a merchant point of sale can request one when the card is used through a digital wallet, and without a PIN set that purchase cannot complete.

Then prompt the customer to add the card to Apple Pay or Google Wallet. See [Digital Wallets](/v2/docs/digital-wallets).

## Step 6 — Issue a physical card

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

If you omit `emboss_name`, the card is embossed with the customer's first and last name. If you omit `shipping.address`, the card goes to the customer's shipping address on file.

<Tip>
  For customers who have specified a chosen name, set `emboss_name` explicitly with their chosen and last name rather than relying on the default.
</Tip>

## Step 7 — Track fulfillment

Subscribe to `CARD.*` webhooks. You receive `CARD.CREATED` on issuance and `CARD.UPDATED` as the card moves through `ORDERED`, `SHIPPED`, and any rejection, which is what you need to keep the customer informed. See the [Webhooks guide](/v2/docs/webhooks-guide).

If the card comes back `PENDING` rather than progressing, read `status.pending_reasons` — a card product with a `REQUIRED` PIN issuance policy holds the card until a PIN is set.

## Step 8 — Activate the physical card

When the card arrives, the customer proves possession. Which method you use depends on what is printed on the card:

* **Full PAN and CVV printed** — use the [Activate Card widget](/v2/docs/card-widgets-activate).
* **No PAN or partial PAN** — have the customer scan the barcode and send its value to [Activate Card](/v2/reference/activatecard).
* **Neither** — set the card to `ACTIVE` with [Update Card](/v2/reference/updatecard), having done your own due diligence to authenticate the customer.

See [Activate a card](/v2/docs/card-issuance-management#activate-a-card) for the details and trade-offs.

The physical card keeps the PIN the customer already set on the virtual card only if the physical card was issued as a reissuance of it. Issued independently, as here, it needs its own PIN — prompt for one at activation.

## Step 9 — Run the program

From here the card is live. The rest of the lifecycle is covered in [Issue and Manage Cards](/v2/docs/card-issuance-management):

* **Lock and unlock** a card when a customer misplaces it
* **Reissue** on expiration, loss, theft, or damage
* **Terminate** when the customer closes the card

Set up expiration reissuance early. Use [List Cards](/v2/reference/listcards) with the `expires_before` filter to find cards approaching expiry, and reissue them with `EXPIRATION` before the date arrives — the replacement keeps the same PAN and PIN, and inherits the customer's digital wallet tokens, so the customer notices nothing.