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

# Post-Go-Live FAQ

> Lists the most common front-line issues you will meet in day-to-day operations after go-live, organized by scenario (digital wallet provisioning failures, card-on-file failures, declines, frozen or blocked cards, refunds that have not arrived, disputes and fraud, KYC stuck in review, changing a shipping address, blocking a merchant). Each scenario gives the steps you can work through yourself and the threshold at which the case should be raised with DCS.

## 📄 Guide

Go-live is only the beginning. Whether you are an exchange, a wallet or a platform, your cardholders will run into real situations: a card that will not go into a mobile wallet, a refund that never seems to land, a transaction that gets declined. This page lists the most common post-go-live issues by scenario and gives you both **the steps you can work through yourself** and **the threshold at which to raise the case with DCS**, so that your support team can resolve most front-line issues without help.

As a licensed issuer with its own BINs, DCS keeps providing card issuing, authorization forwarding, clearing and reconciliation in production. When a case genuinely needs DCS, raise it through the [Escalation and Support Path](./support-escalation).

> A note on ownership: under the Partner-Managed model, **you control spending limits and you make the authorization decision**. Questions like "why was this declined" and "was the balance sufficient" should therefore be investigated first in your own authorization logic and enterprise deposit; DCS is responsible for issuing, forwarding and settlement.

***

## Adding the card to a digital wallet (Apple Pay / Google Pay) fails

When a cardholder cannot add a card to their mobile wallet, walk them through the following in order:

1. **Try a different card**: this tells you whether the problem is with *this card* or with *this wallet / this handset*.
2. **Common causes**:
   * the country or region of the handset does not match the region the card was issued in;
   * the handset has been flagged as a high-risk device by Apple or Google;
   * several cards were added in quick succession, tripping the wallet's own rate limit.
3. **What to advise**: a single device can normally add only **one card successfully per 24 hours**, so ask the cardholder to wait 24 hours and try again.

> For one-tap provisioning from inside your app, see [Push Provisioning / Digital Wallets](../how-to-use/cards/push-provisioning).

## Adding the card at a merchant (card on file) fails

When a cardholder cannot save the card with a merchant or app:

* some merchants verify the billing address strictly, so suggest the cardholder enter address details matching the card's issuing region at checkout;
* if it still fails, note the **transaction identifier** (`transactionId` / `authId`) and raise it with DCS through the [escalation path](./support-escalation) for investigation.

## How to troubleshoot a decline

Every authorization request is forwarded by DCS to your `authUrl` in real time for a decision, and the decline is visible in the authorization data as well. Troubleshoot in this order:

1. **Establish who made the decision**: under the Partner-Managed model the vast majority of declines come from your own decision (`approveFlag=D`), so check your authorization logic first: has the user exhausted their limit, is the available balance of the enterprise deposit sufficient, did the request hit one of your own risk or MCC rules.
2. **Then check the DCS-side pre-checks**: DCS validates card status (activated, frozen or blocked) before forwarding. If the card is `FROZEN`, `BLOCKED` or `INVALID` the authorization cannot succeed; query the card detail for `status` and `statusReason` (see "Frozen or blocked cards" below).
3. **Common decline reasons**: insufficient balance or limit, an abnormal card status, a CVV or PIN mismatch, or a restricted MCC or merchant.
4. **Tell the cardholder**: explain the reason to the cardholder based on what you found above.

> For the standardised decline values and their meanings, see [Decline Codes](../how-to-use/transactions/decline-codes). For the authorization fields (`approveFlag`, `direction`, `authType` and others), see [Authorization](../how-to-use/transactions/authorization).

## Frozen or blocked cards: telling them apart and resolving them

Use the `status` and `statusReason` returned by the card detail endpoint (`GET /open-api/card/v1/detail`):

| Status    | Meaning                                                                                                                                               | Who can lift it                                   |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
| `FROZEN`  | Freeze initiated by the cardholder or by you, or triggered automatically by failed verification (for example three consecutive wrong CVV/PIN entries) | You can unfreeze it yourself                      |
| `BLOCKED` | Freeze initiated by the issuer or by risk control (for example a compliance review or a security restriction)                                         | You cannot lift this directly; DCS must handle it |
| `INVALID` | The card's life cycle has ended; permanently void                                                                                                     | Not recoverable                                   |

* **Unfreezing a card you froze**: call `POST /open-api/card/v1/freeze` with `freeze=false` to unfreeze (`freeze=true` freezes). Freeze and unfreeze are **the same endpoint distinguished by the boolean `freeze` field**, not two separate endpoints.
* **`BLOCKED` cards**: read `statusReason` first (values such as `COMPLIANCE_REVIEW` or `SECURITY_RESTRICTION`) to understand why, then contact DCS through the [escalation path](./support-escalation) to have it lifted.

> For the card state machine, the full set of `statusReason` values and which operations are permitted in each state, see [Card Management](../how-to-use/cards/card-management).

## A refund or reversal has not arrived

Refunds and reversals appear in the system as authorizations with direction `INCOMING`, releasing funds that were held:

* once the merchant has initiated the refund or reversal there is an unavoidable delay before the money lands, so ask the cardholder to be patient first.
* if it still has not arrived well beyond a reasonable window, raise it with DCS through the [escalation path](./support-escalation) with the **original transaction identifier** (`transactionId`, plus the related `authId` / `originalAuthId`).

> The actual timing of a refund or reversal depends on how the channel processes it; if it clearly exceeds a reasonable window and still has not arrived, raise it with DCS through the escalation path. For the fields and scenarios of `INCOMING` authorizations, see [Authorization](../how-to-use/transactions/authorization).

## A cardholder disputes a transaction (dispute / fraud)

When a cardholder claims a transaction was unauthorised, or is in dispute with the merchant:

* check the transaction details first (merchant name `cardAcceptorNameLocation`, amount, timestamp) to rule out a purchase the cardholder forgot or a family member made;
* if it really is a dispute or a fraudulent transaction, file it following [Disputes](../how-to-use/disputes) and contact DCS through the [escalation path](./support-escalation) to follow up.

> Dispute and chargeback handling is currently coordinated with DCS operations, so contact DCS through the escalation path to follow up.

## KYC for an existing cardholder stays under review for a long time

When a cardholder's KYC status has not moved for a long time after they applied:

1. **Check document quality and labeling first**: make sure the documents submitted are legible, are not screenshots, and are labeled with the correct type and side (front of an ID card, selfie labeled correctly, and so on). For the list of acceptable documents, see [About KYC Documents](./faq-kyc-documents).
2. **Check the current status**: call the KYC query endpoint to see which stage the case is at; if more material is needed, ask the cardholder to supply it.
3. **Escalate after a reasonable wait**: if the documents are fine and the case is still sitting under review, raise it with DCS through the [escalation path](./support-escalation) with the `customerId` / `kycTicketId`.

> For the state machine and how to query it, see [Query KYC](../how-to-use/kyc/query-kyc); for rejection reasons, see [KYC Reject Codes](../how-to-use/kyc/kyc-reject-codes).

## Changing the shipping address of a physical card

Once physical card shipping details have been submitted they **normally cannot be changed in flight**. To correct them:

1. contact DCS through the [escalation path](./support-escalation) to cancel the user's current card;
2. ask the cardholder to reapply with the correct address.

> The standard way to correct a shipping address today is to cancel the current card and reapply with the correct one. To look up shipping details, see [Card Management](../how-to-use/cards/card-management) (`GET /open-api/card/v1/shipping-info`).

## Blocking a suspicious merchant

To block a merchant:

* under the Partner-Managed model you can decline a specific merchant or MCC directly in your own authorization decision (`approveFlag=D`), which is the fastest self-service route;
* if you need a harder block at the DCS or scheme level, raise it through the [escalation path](./support-escalation) with the **merchant identifier and the reason for blocking**.

***

## Next steps

To raise an issue with DCS, or to understand who owns which class of issue and how quickly it is handled, go to [Escalation and Support Path](./support-escalation). For questions about getting ready to launch, see the [Pre-Go-Live FAQ](./pre-go-live).