Issue a Card

Prerequisites

To issue a card you need three things:

A verified customer

A person who has passed KYC, or a business that has passed KYB. See Create a Personal Customer and KYC/KYB Verification.Gift card programs are the exception: card products with issue_without_kyc enabled can issue cards without verification.

An account that the customer owns

The account the card spends against, with cards enabled. See Card-Account Relationship and Funding Hierarchies for which account type to use.

An active card product

The card_product_id of the product you are issuing against. Retrieve it with List Card Products.

Use Issue a Card 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.

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, and encourage them to add it to a digital wallet. See 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.

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.
`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.
`bulk_order_config_id`	The bulk order this card ships under. See 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. 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.

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	Collects the PAN and CVV to activate a card
Set PIN	Sets or resets a card’s PIN
Reveal Card	Displays the full PAN, CVV, and expiration date
Reveal PIN	Displays the current PIN

See Card Widgets to get started, and Widget 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	Sets a card’s PIN
Reveal Card Details	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.

Activation widget

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 as activation_code, along with the customer_id.

cURL

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. This endpoint is available in test environments only.

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.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, or Set Card PIN 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.

To change a PIN later, see Reset a PIN.

Next Steps

Manage a Card

Lock, reissue, terminate, and reset a PIN.

Card Lifecycle

The states a card moves through, and what drives them.

A Typical Card Workflow

One card followed end to end, with the calls at each step.

Overview

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Use Cases

Prerequisites

Common Attributes

Issue a Virtual Card

Issue a Physical Card

Physical Card Attributes

Track Issuance with Webhooks

Handling Sensitive Card Data

Widgets — No PCI Certification Required

Direct API — PCI Certification Required

Activate a Card

Set a PIN

Next Steps

Manage a Card

Card Lifecycle

A Typical Card Workflow

​Prerequisites

​Common Attributes

​Issue a Virtual Card

​Issue a Physical Card

​Physical Card Attributes

​Track Issuance with Webhooks

​Handling Sensitive Card Data

​Widgets — No PCI Certification Required

​Direct API — PCI Certification Required

​Activate a Card

​Set a PIN

​Next Steps

Manage a Card

Card Lifecycle

A Typical Card Workflow

Prerequisites

Common Attributes

Issue a Virtual Card

Issue a Physical Card

Physical Card Attributes

Track Issuance with Webhooks

Handling Sensitive Card Data

Widgets — No PCI Certification Required

Direct API — PCI Certification Required

Activate a Card

Set a PIN

Next Steps