Skip to content

Doc 1617/add call to action for card out transactions #587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
max-koro wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Doc 1617/add call to action for card out transactions #587

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
469f6b2
Update index.mdx
max-koro Mar 9, 2026
854864e
Proofreading
max-koro Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/topics/payments/cards/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,56 @@ Refer to explanations of types of account balances in the [accounts section](../
| `Released` | Card authorizations are released for specific reasons. Most of the time, the funds are captured when the merchant requests the actual debit. Authorizations might also be released by the merchant, and they can expire.<br /><br />When an authorization is released without a debit (clearing), the account's available balance increases by the amount of the authorization. |
| `Rejected` | Declined or refused card payments. For example, you, Swan, Mastercard rejected authorization for the payment, or the account's `Available` balance isn't sufficient to complete the card payment without resulting in a negative balance. |

## Rejected card transactions {#rejected}

When a card payment is rejected, the account isn't charged. The **`reasonCode`** on the rejected transaction explains why.

| Rejection reason code | Explanation | Resolution |
|---|---|---|
| `AccountClosed` | The account linked to this card is closed. | This is a permanent state. Open a new account to use cards again. |
| `CanceledByCardHolder` | The cardholder canceled the transaction. | No action needed unless the cancellation was accidental. |
| `CardExpired` | The card is expired. | Order a new card or use a different card. Physical cards renew automatically before expiration. |
| `CardNotActivated` | The card isn't activated. | [Activate the physical card](../../cards/physical/guide-activate.mdx) before making a payment. |
| `CardOutOfOrder` | The card is temporarily or permanently blocked, or it's expired. | Check the card status. If temporarily blocked, resume the card. If permanently blocked or expired, order a new card. |
| `CardPermanentlyBlocked` | The card is permanently blocked. | Order a new card. Permanently blocked cards can't be reactivated. |
| `CardSuspended` | The card is suspended. | Contact your account administrator or Swan Support to understand why and to request reactivation. |
| `CardUnknown` | The card is unknown. | Verify you're using the correct card details. Contact Swan Support if the issue persists. |
| `DigitalCardDeactivated` | The digital card is deactivated. | Reactivate the digital card (Apple Pay/Google Pay) or add it again to your digital wallet. |
| `DigitalCardEnrollmentInvalid` | There was a problem enrolling the digital card. | Remove the card from your digital wallet and add it again, completing the enrollment process fully. |
| `DigitalCardRefusal` | The digital card issuer rejected the transaction. | Try again with your physical or virtual card. Contact Swan Support if the issue persists. |
| `DigitalCardSuspended` | The digital card is suspended. | Check your digital wallet settings or reactivate the card in your Swan account. |
| `DigitalCardTokenInvalid` | The digital card is inactive, expired, or doesn't exist. | Remove the card from your digital wallet and add it again. |
| `DoNotHonor` | This request can't be honored. | Contact Swan Support for more information. |
| `InPersonTransactionsNotAuthorized` | This card can't be used for in-person transactions. | This card is configured for online use only. Check card settings or use a different card for in-person purchases. |
| `InsufficientFunds` | There are insufficient funds on the account. | Add funds to the account before retrying the transaction. |
| `InvalidExpirationDate` | The expiration date provided doesn't match the card's expiration date. | Verify you entered the correct expiration date (MM/YY format). Check your card details in your Swan account. |
| `InvalidPinAttemptsExceeded` | The cardholder entered the incorrect PIN too many times. | Reset your PIN through Swan Support or wait for the automatic reset period to expire. |
| `MagstripeNotSupported` | Paying with the card's magstripe isn't supported by this merchant. | Insert the card and use chip-and-PIN instead of swiping. |
| `MerchantNotFound` | The merchant couldn't be found or doesn't exist. | Contact the merchant to verify their payment system is working correctly. |
| `MerchantShouldResubmitAuthorization` | The merchant didn't use 3-D Secure (3DS). | Ask the merchant to retry the transaction with 3-D Secure authentication enabled. |
| `PeriodTransactionNumberLimitExceeded` | The maximum number of transactions allowed during the period is exceeded. | Wait until the spending period resets or contact your account administrator to increase the transaction limit. |
| `PinInvalid` | The PIN entered is incorrect. | Retry with the correct PIN. After several incorrect attempts, the card may be temporarily blocked. |
| `PinRequired` | The cardholder didn't enter their PIN. | Insert the card into the terminal and enter your PIN to complete the payment. |
| `PinRequiredForFurtherTransaction` | The cardholder must enter their PIN while completing a transaction to reactivate the card. | Complete a chip-and-PIN transaction to reactivate contactless functionality. |
| `SwanTechnicalErrorOccurred` | A technical error occurred. | Retry the transaction. If the problem persists, contact Swan Support with the transaction details. |
| `ThreeDsError` | There was an error with 3-D Secure (3DS). | Retry the transaction and complete the 3-D Secure authentication. |
| `TransactionAmountLimitExceeded` | The maximum spending limit for the period is exceeded. | Wait until your spending period resets, use a different card, or request a spending limit increase. |
| `TransactionCurrencyIncorrect` | The transaction isn't in a supported currency. | Enable international payments and non-main currency transactions in your card settings, or use a different payment method. |
| `TransactionTypeNotAllowed` | This transaction type isn't allowed on the account. | Verify account settings and card permissions. Contact your account administrator if you need access to this transaction type. |

:::note Generic rejection codes
Some codes, such as `DoNotHonor`, are intentionally generic for security reasons. For detailed information about a specific rejection, cardholders should contact Swan Support.

View the complete [RejectedReasonCode enum](https://api-reference.swan.io/enums/rejected-reason-code/) in the API Reference.
:::

:::tip Prevent common rejections
- Activate physical cards before first use.
- Enable international and non-main currency transactions before traveling.
- Monitor spending limits and available balance.
- Keep card details secure to prevent fraud-related blocks.
:::

## Contactless payments

Contactless payments let users pay by tapping their physical card on the payment terminal instead of inserting it and entering a PIN.
Expand Down