Post-Go-Live FAQ

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

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

​

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

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

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

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.
   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 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; the account asset and hold/debit model is in Basic concepts › Ledgering system.

​

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

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

POST /card/v2/block

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

​

A refund or reversal has not landed yet

• 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.
  POST /card/v1/transaction/id/resolve
  
  {
    "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, 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.

​

A cardholder disputes a transaction (dispute / fraud)

• 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 to take it forward.

​

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

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.
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, quoting the externalUserId and the KYC ticket identifier.

Rejection reasons are in KYC rejections and resubmission.

​

Changing the shipping address for a physical card

1. contact DCS through the escalation path 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.

​

Blocking a suspicious 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 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.
• For questions about getting ready to launch, see Customer success › Overview (Pre-Go-Live FAQ).