Skip to content

DOC-821 Rejection and Return reasons for Merchant payment methods #341

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
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

DOC-821 Rejection and Return reasons for Merchant payment methods #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 28 additions & 4 deletions docs/topics/merchants/online/cards/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,11 +135,35 @@ import DayTimeStandard from '../../../partials/_day-time.mdx';

### Rejected {#rejected}

Card payments can be rejected (declined) for a long list of reasons, including:
When a card payment is rejected, the cardholder's account is not charged.

- Failed [3-D Secure (3DS) authentication](../../../payments/cards/index.mdx#3ds)
- Insufficient funds
- Bank refusal (often without further information)
Card payments can be rejected (declined) for the following reasons:

| Rejection reason | Explanation |
|---|---|
| `AmountInvalid` | The amount entered is invalid for this payment. |
| `CardDetailsInvalid` | The card details provided are incorrect or incomplete. The card holder should reach out to their card issuer for more information. |
| `CardExpired` | The card used is no longer valid because it has expired. The card holder should reach out to their card issuer for more information. |
| `InvalidPinAttemptsExceeded` | Too many incorrect PIN attempts were made. |
| `RejectedByCardIssuer` | The card issuer declined the transaction. The card holder should reach out to their card issuer for more information. |
| `SoftDecline3dsExpiration` | The 3D Secure authentication session expired before completion. |
| `SoftDecline3dsFailure` | The 3D Secure authentication failed. |
| `SoftDecline3dsNotSupported` | The card does not support 3D Secure authentication. |
| `SoftDecline3dsRequired` | The transaction requires 3D Secure authentication, but it was not completed. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `SoftDecline3dsRequired` | The transaction requires 3D Secure authentication, but it was not completed. |
| `SoftDecline3dsRequired` | 3D Secure authentication was required but not completed. |

| `SoftDeclineCardAmountLimitsExceeded` | The transaction exceeds the card's allowed spending limit. The card holder should reach out to their card issuer for more information. |
| `SoftDeclineCardDetailsInvalid` | The card details provided are incorrect or incomplete. The card holder should reach out to their card issuer for more information. |
| `SoftDeclineCardExpired` | The card used is no longer valid because it has expired. |
| `SoftDeclineCardNotActivated` | The card has not been activated yet. The card holder should reach out to their card issuer for more information. |
| `SoftDeclineCardNotSupported` | The card is not supported for this type of transaction. The card holder should reach out to their card issuer for more information. |
| `SoftDeclineCvcCheckFailed` | The CVC security check did not succeed. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `SoftDeclineCvcCheckFailed` | The CVC security check did not succeed. |
| `SoftDeclineCvcCheckFailed` | The card security code (CVC) verification failed. |

| `SoftDeclineCvcInvalid` | The CVC code provided is invalid. |
| `SoftDeclineInsufficientFunds` | The debtor has insufficient funds to fulfill the payment. |
| `SoftDeclineRefundTimeLimitExceeded` | The refund could not be processed because the allowable time limit has passed. |
| `SoftDeclineRejectedByCardIssuer` | The card issuer declined the transaction. The card holder should reach out to their card issuer for more information. |
| `SoftDeclineSwanTechnicalErrorOccurred` | There was a technical error preventing the processing of this payment. |
| `SoftDeclineTransactionAmountIncorrect` | The transaction amount does not match the expected or authorized amount. |
| `SwanRefused` | The transaction was refused by Swan for internal reasons. |
| `SwanTechnicalErrorOccurred` | There was a technical error preventing the processing of this payment. |
Comment on lines +163 to +166
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the difference between SoftDeclineSwanTechnicalErrorOccurred and SwanTechnicalErrorOccurred?


### Chargebacks & disputes {#disputes}

Expand Down
35 changes: 23 additions & 12 deletions docs/topics/merchants/online/checks/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,27 +197,38 @@ A check transaction can be rejected for the following reasons:

| Rejection reason | Explanation |
| --- | --- |
| `AmountMismatch` | Amount on the check and amount declared through the API don't match. |
| `BeneficiaryMismatch` | Beneficiary name on the check and the name declared through the API don't match. |
| `BeneficiaryMissingOrIncorrect` | Merchant's name is missing or incorrect. |
| `CheckNotReceived` | Check wasn't received by Swan's check provider. This reason doesn't appear until 30 days after the check was declared. |
| `CheckReceivedLate` | Check was received by Swan's check provider more than 30 days after the check was declared, or if Swan's check provider received a canceled check. |
| `AmountMismatch` | The amount on the check and the amount declared through the API don't match. |
| `BeneficiaryMismatch` | The beneficiary name on the check and the name declared through the API don't match. |
| `BeneficiaryMissingOrIncorrect` | The merchant's name is missing or incorrect. |
| `CheckNotReceived` | The check wasn't received by Swan's check provider. This reason doesn't appear until 30 days after the check was declared. |
| `CheckReceivedLate` | The check was received by Swan's check provider more than 30 days after the check was declared, or if Swan's check provider received a canceled check. |
| `DateMissing` | There's no date on the check. |
| `DateInvalid` | Date on the check is in the future or isn't valid. |
| `DebtorNameMissing` | Debtor's name (your merchant's customer) must appear on the check. |
| `DateInvalid` | The date on the check is in the future or isn't valid. |
| `DebtorNameMissing` | The debtor's name (your merchant's customer) must appear on the check. |
| `InvalidOrMissingAmount` | No amount is written on the check, the format shows an invalid amount, or the amount is shared in the wrong format (numbers instead of letters). |
| `SignatureMissing` | Debtor's signature is missing, or there was a problem with the signature. |
| `SignatureMissing` | The debtor's signature is missing, or there was a problem with the signature. |

### Returned {#returned}

Checks can be returned up to 10 business days after the transaction is `Booked`, and this window can be extended to 90 calendar days based on the reason for return.
Note that checks aren't mailed back to the merchant.

A check transaction might be returned for the following reasons (this list is not exhaustive):
A check transaction might be returned for the following reasons:

- Insufficient funds
- Account closed
- Loss or theft
| Return reason | Explanation |
|---|---|
| `AccountClosed` | The account is closed. |
| `CheckBlocked` | The payer has blocked the check payment. |
| `CheckOutdated` | The check is outdated. |
| `DebtorDeceased` | The debtor is deceased. |
| `EndorsementMissingOrInvalid` | The check payment can't be fulfilled because the beneficiary's signature on the check is missing or invalid. |
| `Fraudulent` | The payment can't be fulfilled because it's a fraudulent check. |
| `InsufficientFunds` | The payer has insufficient funds to fulfill the check payment. |
| `LegalOrBankDecision` | The check payment can't be fulfilled because of a legal or banking issue on the payer's end. |
| `MandatoryReferenceMissingOnCheck` | The check payment can't be fulfilled because a mandatory piece of information is missing on the check. |
| `SignatureInvalid` | The check payment can't be fulfilled because the payer's signature is invalid. |
| `SwanTechnicalErrorOccurred` | There was a technical error preventing the treatment of this check. |
| `TransactionDuplicated` | This transaction can't be fulfilled because it's a duplicate of another transaction. |

By the time a check is returned, the merchant's account has already been credited.
Therefore, when Swan is notified that a `Booked` check has gone unpaid, a `checkInReturn` transaction is created automatically.
Expand Down
30 changes: 21 additions & 9 deletions docs/topics/merchants/online/idd/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,23 +155,35 @@ Returns and refunds are only possible with **Standard** and can be requested up

When an Internal Direct Debit Standard transaction is **rejected**, the debtor's account is not debited.

An Internal Direct Debit Standard transaction might be rejected for the following reasons (this list is not exhaustive):

- Incorrect account number
- Debtor canceled the payment mandate
- Insufficient funds
An Internal Direct Debit Standard transaction might be rejected for the following reasons:

| Rejection reason | Explanation |
|---|---|
| `AccountClosed` | The account is closed. |
| `AccountSuspended` | The account is suspended. |
| `AccountUnknown` | The IBAN provided doesn't match an existing account. |
| `InsufficientFunds` | The debtor has insufficient funds to fulfil the transaction. |
| `MandateInvalid` | The payment mandate is invalid, possibly because it was canceled, incorrectly completed, or the B2B mandate wasn't declared. |
| `ReasonNotSpecifiedByBank` | The debtor's bank can't disclose the rejection reason due to local data protection laws. |
| `ReasonNotSpecifiedByDebtor` | The payment was rejected at the debtor's request. |
| `RegulatoryReason` | The payment was rejected for regulatory reasons. |
| `SwanRefused` | The transaction was refused by Swan for internal reasons. |

Regardless of the reason, the merchant receives a notification and can attempt a new Internal Direct Debit at a later date.

### Returned {#returned}

When an Internal Direct Debit Standard transaction is **returned**, the debtor's account is debited the amount, but the payment is reversed and the funds return to the debtor's account.

An Internal Direct Debit Standard transaction might be returned for the following reasons (this list is not exhaustive):
An Internal Direct Debit Standard transaction might be returned for the following reasons:

- Debtor disputes the payment
- Payment was made in error
- Insufficient funds
| Return Reason | Explanation |
|---|---|
| `ReasonNotSpecifiedByBank` | The debtor's bank can't disclose the rejection reason due to local data protection laws. |
| `ReasonNotSpecifiedByDebtor` | The payment was rejected at the debtor's request. |
| `RefundRequestedByDebtor` | The payer has requested a refund. |
| `RegulatoryReason` | The payment was returned for regulatory reasons. |
| `SwanTechnicalErrorOccurred` | A technical error prevented the processing of this check. |

Regardless of the reason, the merchant is notified about the return.
They can investigate the reason for return and take whatever action is necessary, which might be refunding the payment or disputing the return with the debtor's bank.
Expand Down
49 changes: 36 additions & 13 deletions docs/topics/merchants/online/sdd/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,26 +147,49 @@ Returns and refunds are only possible with **Core** and can be requested up to 8

When a SEPA Direct Debit Core transaction is **rejected**, the debtor's account is not debited.

A SEPA Direct Debit Core transaction might be rejected for the following reasons (this list is not exhaustive):

- Incorrect account number
- Debtor canceled the payment mandate
- Account is closed
- Insufficient funds
- Technical issues
- Debtor requested refusal of the debit before the date and time of the settlement execution
A SEPA Direct Debit Core transaction might be rejected for the following reasons:

| Rejection reason | Explanation |
|---|---|
| `BankRefused` | The payment was rejected by the bank. |
| `DebtorAccountClosed` | The debtor's bank account is closed. |
| `DebtorAccountConsumer` | The debtor is not a business account, and the transaction is a B2B SDD transaction. |
| `DebtorAccountUnknown` | The IBAN provided doesn't match an existing account at the debtor's bank. |
| `DebtorDeceased` | The debtor is deceased. |
| `InsufficientFunds` | The debtor has insufficient funds to fulfill the transaction. |
| `MandateInvalid` | The payment mandate is invalid, possibly because it was canceled, incorrectly completed, or the B2B mandate wasn't declared. |
| `ReasonNotSpecifiedByBank` | The debtor's bank can't disclose the rejection reason due to local data protection laws. |
| `ReasonNotSpecifiedByDebtor` | The payment was rejected at the debtor's request. |
| `RegulatoryReason` | The payment was rejected for regulatory reasons. |
| `SwanRefused` | The transaction was refused by Swan for internal reasons. |
| `TransactionDuplicated` | The transaction can't be fulfilled because it is a duplicate of another transaction. |
| `TransactionOnAccountTypeNotAllowed` | The account can't be debited because direct debits aren't allowed for this account type, for regulatory restrictions. |
| `TransactionTypeNotAllowed` | The direct debit can't be processed because the debtor account is blocked. |

When a SEPA Direct Debit Core transaction is rejected, regardless of the reason, the merchant receives a notification and can attempt a new SEPA Direct Debit at a later date.

### Returned {#returned}

When a SEPA Direct Debit Core transaction is **returned**, the debtor's account is debited the amount, but the payment is reversed and the funds return to the debtor's account.

A SEPA Direct Debit Core transaction might be returned for the following reasons (this list is not exhaustive):

- Debtor disputes the payment
- Insufficient funds
- Invalid payment mandate (example: the mandate was not declared to the debtor bank)
A SEPA Direct Debit Core transaction might be returned for the following reasons:

| Return reason | Explanation |
|---|---|
| `BankRefused` | The payment was refused and returned by the debtor's bank. |
| `DebtorAccountClosed` | The debtor's bank account is closed. |
| `DebtorAccountConsumer` | The debtor is not a business account, and the transaction is a B2B SDD transaction. |
| `DebtorAccountUnknown` | The IBAN provided doesn't match an existing account at the debtor's bank. |
| `DebtorDeceased` | The debtor is deceased. |
| `InsufficientFunds` | The debtor has insufficient funds to fulfill the transaction. |
| `MandateInvalid` | The payment mandate is invalid, possibly because it was canceled, incorrectly completed, or it wasn't declared to the debtor bank. |
| `ReasonNotSpecifiedByBank` | The debtor's bank can't disclose the return reason due to local data protection laws. |
| `ReasonNotSpecifiedByDebtor` | The payment was returned at the debtor's request. |
| `RegulatoryReason` | The payment was returned for regulatory reasons. |
| `SwanRefused` | The transaction was refused by Swan for internal reasons. |
| `TransactionDuplicated` | The transaction can't be fulfilled because it's a duplicate of another transaction. |
| `TransactionOnAccountTypeNotAllowed` | The account can't be debited because direct debits aren't allowed for this account type, for regulatory restrictions. |
| `TransactionTypeNotAllowed` | The direct debit can't be processed because the debtor account is blocked. |

When a SEPA Direct Debit Core transaction is returned, regardless of the reason, the merchant is notified about the return.
They can investigate the reason for return and take whatever action is necessary, which might be refunding the payment or disputing the return with the debtor's bank.
Expand Down