> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Provisioning Decisions
> Every attempt to add a card to a wallet is scored and routed down a green, yellow, or red path. This page explains what drives that decision, and what to do when a cardholder cannot add their card.
Understanding why a card was challenged or refused is the difference between resolving a support ticket in minutes and escalating it for a week.
Four layers feed the outcome:
| Layer | What it contributes |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Wallet provider** | Device and account risk scores, and a colour recommendation |
| **Card network** | Rules configured for your BIN range — allow-listing, blocking specific token requestors, and similar |
| **Issuer processor** | Issuer checks on the card and cardholder, and the final decision |
| **Your card product** | Optional address verification, and whether a method is enabled at all |
## What Triggers Each Path
**Red — declined outright**
* The PAN, expiration, and CVV do not match a card
* The card is not active, or is reported expired, lost, or stolen
* The cardholder is not in an active state
* More than five provisioning attempts with an incorrect CVV in the last 24 hours
* The wallet provider returns its lowest device trust score
* The card product is not configured for this provisioning method
* Network provisioning rules decline the attempt
**Yellow — step-up required**
* The wallet provider recommends additional verification
* The network recommends additional verification under a rule configured for your BIN
* Address verification is enabled for the method and the supplied address does not match the one on file
**Green — approved**
Neither red nor yellow was triggered.
The wallet providers' risk models are proprietary and not configurable. They weigh device history, how long the wallet account has existed and how much it has transacted, the device's location against the cardholder's address on file, whether the device was recently reset or reported lost, and bursts of provisioning activity across cards or devices.
## Step-Up Verification
On the yellow path the cardholder must prove they are who they claim before the token activates. The cardholder does this through SMS or Email OTP (one-time passcode).
Because OTP delivery depends on contact details, **every cardholder needs both a mobile number and an email address on file**. Collect them during onboarding — a cardholder without them cannot complete a yellow-path challenge, and the token will eventually be refused.
## Address Verification
Address verification can be enabled per provisioning method on the card product, checking the address supplied during provisioning against the one on file. A mismatch sends the attempt to the yellow path rather than declining it.
It is optional, and it trades friction for fraud protection. Programs whose cardholders move often, or whose address data is incomplete, see more step-up challenges with it on.
## Why Provisioning Fails
When a cardholder cannot add their card, the decline reason is visible on the token in the Synctera console. The common ones:
| Reason | What it means | What helps |
| -------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `HIGH_RISK` | The wallet provider's model scored the attempt as risky overall | Usually resolves as the account ages; repeated attempts make it worse |
| `LOW_DEVICE_SCORE` | The device itself is distrusted — recently reset, newly set up, or associated with past fraud | Try a different device; a new card will not help |
| `LOW_ACCOUNT_SCORE` | The wallet account is distrusted rather than the device | As above — time and normal activity help |
| `ACCOUNT_CARD_TOO_NEW` | The card or the wallet account was created very recently | Wait and retry |
| `ACCOUNT_RECENTLY_CHANGED` | The wallet account was recently modified, for example a password or device change | Wait and retry |
| `OUTSIDE_HOME_TERRITORY` | The device is located away from the cardholder's address on file | Retry from the usual location |
| `TOO_MANY_RECENT_ATTEMPTS` | Provisioning was attempted too many times in a short window | Wait 24 hours before retrying |
| `SUSPICIOUS_ACTIVITY` | Activity patterns associated with fraud | Escalate if the cardholder is known-good |
**Issuing a new card rarely fixes a provisioning decline.** Most reasons describe the device or the wallet account, not the card — so a replacement card presented from the same device scores the same way. Check the reason first.
Where a decline is wrong — a known-good cardholder on a distrusted device — the device can be allow-listed with the wallet provider. Raise it with Synctera support with the token ID and the decline reason. Allow-listing goes through the wallet provider and can take **up to 24 hours to take effect** after it is applied.
## Troubleshooting
| Symptom | Likely cause | What to do |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------- |
| Card refused immediately, no verification prompt | Red path. Check the decline reason on the token. | See [Why Provisioning Fails](#why-provisioning-fails) |
| Cardholder never receives the OTP | No mobile number or email on file, or the wrong one | Check the customer record; correct it and retry |
| Token shows `ACTIVE` but the console fulfillment status looks unfinished | A step-up was required. The two can diverge. | Trust `state`. If it is `ACTIVE`, the token can transact. |
| Cardholder removed the card but you still see an active token | Removal from a wallet does not terminate a token | Terminate it explicitly if intended |
| Repeated attempts now failing that previously only challenged | Attempt-count threshold reached | Wait 24 hours |
| Merchant card-on-file token, no step-up ever presented | Expected — there is no wallet UI to challenge in | Rely on [3DS](/v2/docs/card-3ds) at transaction time |
| A new card for the same cardholder fails the same way | The reason describes the device or wallet account, not the card | Try a different device, or request allow-listing |
When escalating to Synctera support, include the **token ID**, the **decline reason**, and the **device** from the token. Without those the request cannot be taken to the wallet provider.
## Next Steps
Managing tokens that were provisioned successfully.
How tokenization works and what your program needs.