> ## 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.
# Issue a Card
> Everything from the prerequisites through to a card the cardholder can spend on: issuance, activation, handling sensitive card data, and setting a PIN.
## Prerequisites
To issue a card you need three things:
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.
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.
The `card_product_id` of the product you are issuing against. Retrieve it with [List Card Products](/v2/reference/listcardproducts).
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 |
`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.
## 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`.
```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}"
}
}'
```
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).
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.
## 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).
```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"
}
}
}'
```
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). |
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.
## 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.
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).
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.
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.
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.
## Set a PIN
A card needs a PIN before it can be used at an ATM, or anywhere a merchant terminal asks for one. This applies to virtual cards too — a point of sale can request a PIN when the card is used through a digital wallet, and a card with no PIN set cannot complete that purchase.
Prompt the cardholder to set one as part of activation, using the [Set PIN widget](/v2/docs/card-widgets-set-pin), or [Set Card PIN](/v2/reference/setcardpin) if you are PCI certified.
`is_pin_set` shows whether a card has a PIN, and `timestamp_pin_set` records when it was last changed.
Where the card product's `pin_issuance_policy` is `REQUIRED`, the card stays `PENDING` and is not manufactured until a PIN has been set. See [Card Products](/v2/docs/card-products).
To change a PIN later, see [Reset a PIN](/v2/docs/manage-a-card#reset-a-pin).
## Next Steps
Lock, reissue, terminate, and reset a PIN.
The states a card moves through, and what drives them.
One card followed end to end, with the calls at each step.