Troubleshoot declined card payments
This guide helps partner support teams troubleshoot declined payments made with a Swan-issued card: what to check, who needs to act, what to tell your user, and when to contact the merchant or submit a Swan Support request.
For user-facing guidance, share the relevant articles in Share these articles with your users.
For the technical payment lifecycle and rejection reasons, see Card payments. To display transaction details and rejection reasons in your product, your development team can see Get transaction information.
This guide doesn't cover payments accepted into a Swan account through Swan's merchant features. For in-person merchant payments, see Troubleshooting: in-person card payments.
- Check whether the payment appears in the Dashboard and, if it does, review its status and rejection reason.
- A declined card payment isn't debited from the user's account.
- The user might be able to resolve some issues; others need the merchant, your development team, or Swan Support.
What a declined card payment means
A card payment can fail before Swan receives the authorization request or while Swan is processing it. If a transaction appears in the Dashboard, check its status and rejection reason there.
A declined payment isn't debited from the user's account. This differs from:
Pending, when an authorization has been granted but the payment hasn't been debited yet.Booked, when the payment has been completed and debited.Released, when an authorization has ended without a debit and the held amount becomes available again.
If a transaction stays Pending or seems stuck, see Card payments for lifecycle guidance. Submit a support request in your Dashboard when you need Swan to investigate.
In this guide, "declined" means the transaction status is Rejected.
Quick triage
| Situation | Next action |
|---|---|
| The payment isn't recorded | Direct the user to confirm the payment details and check with the merchant. If the merchant confirms that its side is working and the issue appears related to the Swan card, submit a Swan Support request in your Dashboard. |
| The payment is recorded | Go to Step 3: Check the rejection reason and follow the path for the recorded rejection reason. |
The rejection reason is PartnerRefused or PartnerTechnicalErrorOccurred | Route the issue to your development team for a technical investigation of your Payment Control integration. |
The rejection reason is SwanTechnicalErrorOccurred, SwanTimeout, or SwanOffline | Direct the user to retry the payment once. If it still fails, submit a Swan Support request in your Dashboard with the transaction details and note what you've already checked. |
Troubleshoot a declined payment
Step 1: Confirm the scope
Confirm that the payment was made using a Swan-issued card.
If you're troubleshooting payments accepted into a Swan account through Swan's merchant features, see Merchants. These payments use different payment objects, statuses, and rejection reasons.
Step 2: Find the transaction
- Go to Dashboard > Data > Accounts.
- Select the user's account.
- Open Transactions.
- Find the payment attempt and open its details.
- Check the transaction status and rejection reason.
If the payment isn't listed:
- Ask your user to confirm the date, amount, currency, merchant, and payment method.
- Ask the user to check whether the merchant received or rejected the authorization.
- If the merchant confirms that their side is working and the issue appears related to the Swan card, submit a support request in your Dashboard with the merchant's confirmation.
Step 3: Check the rejection reason
Use the reason shown in the transaction details to identify the relevant checks and the next steps. Don't guess based on what the user has described.
The account or membership isn't eligible
Rejection reasons: AccountClosed, AccountSuspended, AccountHolderDeceased, AccountMembershipRefused.
Check that the account and account membership are active. If the account or membership status prevents payments, follow the relevant account or membership procedure instead of changing the card settings.
The card isn't active, is suspended, or is permanently blocked
Rejection reasons: CardNotActivated, CardSuspended, CardPermanentlyBlocked, CardExpired, CardOutOfOrder.
Check the card's status in the Dashboard or your product:
- If the card isn't activated, ask the user to activate it. If your product shows the wrong status, ask your development team to check the integration and API implementation. See Activate your physical card.
- If it's suspended, the cardholder can unblock it in your product. If you use Swan Web Banking, they can do it there.
- If it's blocked after incorrect PIN attempts, ask the user to follow Unblock your card after three incorrect PIN attempts. They need to wait 24 hours after the last incorrect attempt before starting the unblocking process.
For the technical implementation, see Block and unblock physical cards. This covers both API actions and the user unblocking flow.
CardSuspended and CardPermanentlyBlocked are rejection reason codes, not card statuses. Check the card's actual status before advising the user to unsuspend or replace a card.
The user doesn't have enough funds or has reached a limit
Rejection reasons: InsufficientFunds, TransactionAmountLimitExceeded, PeriodAmountLimitExceeded, PeriodTransactionNumberLimitExceeded.
Check the user's available balance and card or transaction limit. Use the rejection reason in the transaction details to confirm why the payment failed.
If a limit was reached, the user may need to wait or split the payment. An account member with canManageCards permission can adjust the individual card setting within the allowed limit. Don't change global card product settings to fix one user's decline.
A card setting doesn't allow the payment
Rejection reasons: TransactionTypeNotAllowed, InPersonTransactionsNotAuthorized, TransactionCurrencyIncorrect.
Check the individual card's usage settings, including:
- International payments
- Payments in a non-main currency
- eCommerce payments
- Withdrawals
Direct the user to your product's card settings to change an individual card. Only account members with canManageCards permission can make the change. Users can also change card settings in Web Banking.
If your product's settings don't match the API, ask your development team to check the integration. Change card product settings only when the update should apply to all cards, not to fix one user's decline.
A country restriction can't be removed by changing an individual card setting. Don't ask the user to keep retrying the payment. See Allowed and blocked countries for card payments.
The PIN or contactless verification wasn't completed
Rejection reasons: PinInvalid, PinRequired, PinRequiredForFurtherTransaction, InvalidPinAttemptsExceeded.
Use the rejection reason to choose the right guidance.
- For
PinInvalid, ask the user to try once with the correct PIN. Repeated guesses can block the card. - For
PinRequired, ask the user to insert the card and enter their PIN. - For
PinRequiredForFurtherTransaction, ask the user to insert the card and enter their PIN to restore contactless payments. This doesn't mean the card is blocked. - For
InvalidPinAttemptsExceeded, share Unblock your card after three incorrect PIN attempts.
For contactless limits, share Spending limits.
The card details are incorrect
Rejection reasons: InvalidExpirationDate, InvalidSecurityNumber.
Ask the user to check the card number, expiry date, and CVC they gave the merchant, then try once more. If the details are correct and the payment still fails, have them contact the merchant.
If the payment still fails and the merchant confirms its systems are working, submit a support request in your Dashboard.
3D Secure wasn't completed
Rejection reasons: ThreeDsError, MerchantShouldResubmitAuthorization.
For an online payment, the merchant may need to start or complete 3D Secure (3DS) verification.
Ask your user to:
- Retry the payment.
- Complete the 3DS verification when prompted.
- Contact the merchant if the verification step doesn't appear or the payment is rejected again.
If the rejection reason is MerchantShouldResubmitAuthorization, the merchant didn't use 3DS. Ask the merchant to check their 3DS implementation. If the issue persists, submit a support request in the Dashboard.
The digital card or wallet isn't active
Rejection reasons: DigitalCardDeactivated, DigitalCardSuspended, DigitalCardTokenInvalid, DigitalCardEnrollmentInvalid, DigitalCardRefusal.
Use the payment type and rejection reason in the transaction details to identify which of the following applies.
If the payment used Apple Pay or Google Pay:
- Check that the card is still present and active in the user's wallet.
- If the user needs to add the card again, share Set up Apple Pay or Set up Google Pay.
- Ask the user to retry the payment.
If the rejection reason is DigitalCardRefusal, the digital card issuer rejected the transaction. Ask the user to check with the merchant or try another payment method. If the issue persists and the merchant confirms their systems are working, submit a support request in your Dashboard.
Swan returned a technical error
Rejection reasons: SwanTechnicalErrorOccurred, SwanTimeout, SwanOffline.
Ask the user to retry once, and check whether other users or cards are affected. If the issue continues, record the transaction details and error message in a support request.
Contact Swan Support
Raise a Swan Support request in your Dashboard when:
- The rejection reason indicates a Swan technical error and retrying once hasn't resolved the issue.
- The same issue affects multiple users or cards.
- The card, account, membership, and card settings are correct, but every payment attempt still fails.
- The transaction isn't recorded, the merchant confirms that its side is working, and the issue appears to be related to the Swan card.
- The rejection reason is unfamiliar and the next action remains unclear after checking the relevant documentation.
Make sure to include the following information:
- Account ID
- Account membership ID, when relevant
- Card contract ID, or the masked card details requested by the support form
- Transaction date and time
- Amount and currency
- Merchant name
- Transaction status and rejection reason, if recorded in Swan
- Whether the payment was in-store, online, made through 3D Secure, or made through a digital wallet
- The checks already completed
- Screenshots or error messages with sensitive card details masked
Don't include full card numbers, PINs, or other sensitive card credentials. Avoid opening duplicate requests for the same issue. See Filling out a support request.
Share these articles with your users
Share these Support Center articles when your user can complete the next step themselves:
- Allowed and blocked countries for card payments
- 3D Secure (3DS)
- Spending limits
- Activate your physical card
- Unblock your card after three incorrect PIN attempts
- Set up Apple Pay
- Set up Google Pay
You can also use these articles as a starting point to create your own FAQ or help center content, tailored to your product's terminology and your users' specific context.