Card Issuance and Management

This guide covers the Cards API itself. Before you issue your first card, work through Design Your Card Program, Card-Account Relationship and Funding Hierarchies, and 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:

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.

Card Lifecycle

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.

You can set only ACTIVE, SUSPENDED, and TERMINATED through Update Card. The other statuses are set by the Synctera platform as the card moves through issuance.

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

Manage a Card

View Cards

List Cards 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 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 to read the current state.

Set or Reset a PIN

Use the Set PIN widget, or Set Card PIN 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 and reactivate it the same way:

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"
  }'

curl --request PATCH \
  --url "$baseurl/v2/cards/{CARD_ID}" \
  --header "Authorization: Bearer $apikey" \
  --header "Content-Type: application/json" \
  --data '{
    "card_status": "ACTIVE",
    "reason": "REQ"
  }'

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

Automating expiration reissuance. Use List Cards 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.

Terminate a Card

Set the card’s status to TERMINATED with Update Card:

cURL

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

You offer a card product to a customer. Call List Card Products and note the id of the product you want to offer.
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.
You call Issue a Card with the customer, account, card product, embossed name, and optional shipping information. The response contains the card object and its ID.
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.

Activating a Card

Your customer receives the card, logs into your app, and scans the barcode with their phone camera.
Your app translates the barcode into its value.
You call Activate Card with that value and the customer ID.
The Cards API requests activation through the card vendor.
You prompt the customer to set a PIN using the Set PIN widget.
The widget sends the PIN directly to the card vendor.
The card vendor activates the card and notifies the Synctera platform.
The card’s status becomes ACTIVE, and you receive a CARD.UPDATED webhook.

Reissuing a Card

Your customer reports that they lost the card.
You call Issue a Card 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.
Synctera immediately terminates the lost card with the card vendor and sets its status to TERMINATED.
The new card is issued and activated just as the lost card was — with a new PAN, but the same PIN.

Cancelling a Card

The customer cancels the card.
You call Update Card to set the status to TERMINATED. You can also do this from the Synctera dashboard.
Synctera notifies the card vendor.
The card vendor terminates the card.

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

Card Issuance and Management

Prerequisites

Card Lifecycle

Card Status

Fulfillment Status

Issue a Card

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

Manage a Card

View Cards

View Card History

Set or Reset a PIN

Reset PIN Tries

Lock and Unlock a Card

Reissue a Card

Terminate a Card

A Typical Card Workflow

Requesting Card Issuance

Activating a Card

Reissuing a Card

Cancelling a Card

​Prerequisites

​Card Lifecycle

​Card Status

​Fulfillment Status

​Issue a Card

​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

​Manage a Card

​View Cards

​View Card History

​Set or Reset a PIN

​Reset PIN Tries

​Lock and Unlock a Card

​Reissue a Card

​Terminate a Card

​A Typical Card Workflow

​Requesting Card Issuance

​Activating a Card

​Reissuing a Card

​Cancelling a Card

Prerequisites

Card Lifecycle

Card Status

Fulfillment Status

Issue a Card

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

Manage a Card

View Cards

View Card History

Set or Reset a PIN

Reset PIN Tries

Lock and Unlock a Card

Reissue a Card

Terminate a Card

A Typical Card Workflow

Requesting Card Issuance

Activating a Card

Reissuing a Card

Cancelling a Card