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

> This page lists the front-line issues that come up most often once you are live, organized by scenario: cards that will not add to a digital wallet, cards that will not save at a merchant, declined transactions, frozen cards, refunds and reversals that have not landed, disputes and fraud claims, KYC stuck in review, changing a shipping address, and blocking a merchant. For each one you get the steps your own support team can work through unaided, plus the threshold at which to escalate to DCS, so that most first-line cases can be resolved on your side.

Going live is only the start. Whether you are an exchange, a wallet or a platform, your end customers will run into real situations: the card will not add to Apple Pay, a refund is taking too long, a purchase gets declined. This page walks through those situations one by one.

As a licensed issuer with its own BINs, DCS provides **per-customer account custody, in-system authorization decisions, clearing and reconciliation** under DeCard-Managed. When a case genuinely needs DCS, raise it through [Escalations and support paths](./escalations-and-support-paths).

> Where responsibility sits under DeCard-Managed: **authorization decisions are made inside DCS**, and every end customer holds their own balance (available `free` / held `freeze`). So for questions like "why was this declined" or "did they have enough money", start with that customer's [per-customer balance](../how-to-use/managing-transactions/user-balance) and card status, then factor in risk and MCC rules. This differs from the Partner-Managed model, where the partner runs its own limits and authorization decisions.

***

## The card will not add to a digital wallet (Apple Pay / Google Pay)

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

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

> DeCard-Managed supports in-app provisioning (one-tap card binding inside your app) through `POST /card/v1/apple-bind-wallet` and `/card/v1/google-bind-wallet` (Google also has a V2 endpoint of the same name). For the integration and field details, see [Push provisioning (Apple / Google Pay)](../how-to-use/managing-cards/push-provisioning).

## The card will not save at a merchant (card-on-file)

When an end customer cannot store the card with a merchant or app:

* some merchants validate the billing address strictly, so suggest the customer enter address details matching the card's issuing market at checkout;
* if it still fails, note the **transaction identifier** and escalate to DCS for investigation through the [escalation path](./escalations-and-support-paths). You can use `POST /card/v1/transaction/id/resolve` to pull the transaction detail and pin down the record.

## How to troubleshoot a declined transaction

Under DeCard-Managed, the authorization decision is made **inside DCS**. Work through it in this order:

0. **Confirm from the webhook whether it was declined**: the callback URL you configured receives a `CARD_TRANSACTION` webhook in which `data.response` = `"A"` means approved and `"D"` means declined. That field is binary approve/decline only and carries no detailed decline reason code, so the reason has to be established manually through the steps below.

1. **Check the customer's own balance**: call `GET /user-asset/v1/balance` to see the customer's wallet balance, specifically whether `free` (available) covers the purchase and how much is tied up in `freeze` (held). Insufficient balance is by far the most common decline reason.

   ```http theme={null}
   GET /user-asset/v1/balance?externalUserId=<external-user-id>
   ```

   > `data` in the response is an array returning `{asset, free, freeze, total}` per currency. For the fields and how to use them, see [User balance](../how-to-use/managing-transactions/user-balance).

2. **Check the card status**: call `GET /card/v2/detail` and read `cardStatus` (virtual card: `NORMAL`/`FROZEN`/`CANCELLED`) and `physicalCardStatus` (physical card: `UN_APPLY`/`INACTIVE`/`ACTIVE`/`REPLACE`/`FROZEN`/`CANCELLED`). A card in `FROZEN` or `CANCELLED` will never authorize.

   ```http theme={null}
   GET /card/v2/detail?externalUserId=<external-user-id>&cardId=<card-id>
   ```

   > `cardId` is returned in the successful card issuing response, and can also be looked up per customer with `GET /card/v2/detail` (leave `cardId` empty to list all of the user's cards). For frozen or canceled physical cards, read `physicalCardStatus`. See the next section, "The card is frozen".

3. **Check risk rules and MCC**: was a restricted merchant category (MCC) or a risk rule hit? If the balance is sufficient and the card status is fine but the transaction is still declined, contact DCS through the [escalation path](./escalations-and-support-paths) to confirm whether it hit a risk or MCC rule.

4. **Tell the customer**: explain the decline reason based on what you found.

> Authorization fields such as `direction` and `authType` are described in [Real-time authorization](../how-to-use/managing-transactions/authorizing-transactions); the account asset and hold/debit model is in [Basic concepts › Ledgering system](../basic-concepts/ledgering-system).

## The card is frozen: telling the states apart and what to do

Read `cardStatus` from `GET /card/v2/detail` (virtual card):

| Status      | Meaning                                         | Who can lift it                        |
| :---------- | :---------------------------------------------- | :------------------------------------- |
| `NORMAL`    | The card is active and usable                   | —                                      |
| `FROZEN`    | The card is frozen and temporarily unusable     | The partner can unfreeze it themselves |
| `CANCELLED` | The card is canceled and permanently out of use | Not reversible                         |

* **Unfreezing**: call `POST /card/v2/block` with `externalUserId`, `cardId` and `block` (boolean, `false` = unfreeze / `true` = freeze) in the body, plus **either** `smsCode` (SMS OTP) **or** `emailCode` (email OTP), since unfreezing requires a one-time code. Freeze and unfreeze are the **same endpoint distinguished by the boolean `block`**, not two separate endpoints.

```http theme={null}
POST /card/v2/block
```

```json theme={null}
{
  "externalUserId": "user_xxxxxxxx",
  "block": false,
  "cardId": "card_xxxxxxxx",
  "smsCode": "",
  "emailCode": ""
}
```

> Obtain `smsCode` from `POST /captcha/v1/send-mobile-code` (with `behavioral=CARD_UNFROZEN`) and `emailCode` from `POST /captcha/v1/send-email-code`. Either one is enough.

> This endpoint identifies a card precisely by `cardId`. The card state machine and the operations allowed in each state are covered in [Card management › Overview](../how-to-use/managing-cards/overview).

## A refund or reversal has not landed yet

Refunds and reversals appear in the system as credit-direction records (`direction` = `CREDIT`), releasing held funds back into the customer's `free` balance:

* once the merchant has initiated the refund or reversal there is an unavoidable delay before it lands, so ask the customer to be patient first.

* Use `GET /card/v2/statements` (statements) and `POST /card/v1/transaction/id/resolve` (single transaction detail) to check the status and direction of the record.

  ```http theme={null}
  POST /card/v1/transaction/id/resolve
  ```

  ```json theme={null}
  {
    "ids": ["<outstanding-id-or-posted-transaction-id>"]
  }
  ```

  > Pass one or more transaction IDs in `ids` (`outstandingTransactionId` or `postedTransactionId`). The response distinguishes `posted` (whether it has been booked), `outstandingTransactionId` (null once booked) and `postedTransactionId` (populated once booked).

* If it still has not landed well beyond any reasonable window, escalate to DCS for investigation through the [escalation path](./escalations-and-support-paths), quoting the **original transaction identifier**.

> Actual refund and reversal timings depend on how the channel processes them. The fields and scenarios for refunds and reversals (`authType=REFUND` / `REVERSAL`, `direction=CREDIT`) are in [Real-time authorization](../how-to-use/managing-transactions/authorizing-transactions).

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

When an end customer claims a transaction was unauthorized, or is in dispute with the merchant:

* first check the transaction detail with `GET /card/v2/statements` / `POST /card/v1/transaction/id/resolve` (merchant name, amount, timestamp) to rule out a forgotten purchase or a family member's spending;
* if it really is a dispute or fraud claim, contact DCS through the [escalation path](./escalations-and-support-paths) to take it forward.

<Warning>
  **How disputes are handled**: DeCard-Managed currently has **no self-service dispute or chargeback API**. Disputes and chargebacks are handled **through coordination with DCS Operations**, so escalate the case through the support path and DCS will follow its established process. This FAQ section also has a dedicated page, [Transaction issues and disputes](./transaction-issues-disputes).
</Warning>

## KYC has been in review for a long time on an issued card

If a customer's KYC status has not moved on well after they applied:

1. **Start with document quality and labeling**: confirm the documents submitted are legible, are not screenshots, and are labeled with the correct type and side (for example the front of a national ID, and a correctly labeled selfie). The list of acceptable documents is in [KYC documents](./kyc-documents).
2. **Check the current state**: establish which stage the application is at, and if a resubmission is needed, guide the customer through it.
3. **Escalate after a reasonable wait**: if the documents are sound and the application is still sitting in review, escalate to DCS through the [escalation path](./escalations-and-support-paths), quoting the `externalUserId` and the KYC ticket identifier.

> Rejection reasons are in [KYC rejections and resubmission](./kyc-rejections).

## Changing the shipping address for a physical card

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

1. contact DCS through the [escalation path](./escalations-and-support-paths) to cancel that customer's current card;
2. have the customer apply for a new card with the correct address.

> Canceling the current card and reapplying with the correct address is the standard way to correct a shipping address today. Shipping details and the physical card flow are covered in [Card management › Overview](../how-to-use/managing-cards/overview).

## Blocking a suspicious merchant

To block a specific merchant:

* under DeCard-Managed the authorization decision is made inside DCS, so merchant-level and MCC-level blocking has to be configured on the DCS risk side;
* escalate through the [escalation path](./escalations-and-support-paths) with the **merchant identifier and the reason for blocking**, and DCS will apply it at the risk or scheme layer.

***

## Next steps

* To escalate a case to DCS, or to understand the response path for each type of issue, go to [Escalations and support paths](./escalations-and-support-paths).
* For questions about getting ready to launch, see [Customer success › Overview (Pre-Go-Live FAQ)](./pre-go-live).