Skip to main content

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

​
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 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. For the authorization fields (approveFlag, direction, authType and others), see 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):
  • 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 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.

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

​
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 and contact DCS through the escalation path 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.
  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 with the customerId / kycTicketId.
For the state machine and how to query it, see Query KYC; for rejection reasons, see 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 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 (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 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. For questions about getting ready to launch, see the Pre-Go-Live FAQ.