Cards for merchants
Overview​
Cards are the most common way for customers worldwide to pay. Swan supports most major card issuers, including Visa, Mastercard, and Cartes Bancaires (CB) in France. American Express isn't supported.
Merchants can use payment links to accept payments from cardholders anywhere. Typical implementations of payment links include:
- Adding a payment link to an invoice.
- Sharing a payment link with a QR code.
- Sending a payment link by email or SMS.
Collect rent, share invoices, and accept customer payments through a Swan merchant account.
This section only applies to merchants accepting card payments. Visit the card payments section for information about payments made with cards from a Swan account.
Merchant card payments​
Merchant card payments include one or more transactions. For example, one payment might include a capture transaction and a refund transaction, for a total of two transactions.
These transactions are grouped together in the merchant payment object. Swan recommends using the merchant payment object in your integration to help merchants match orders, invoices, and sales to the correct object. This provides better traceability and can help reconcile issues more efficiently.
Card transaction types​
There are four transaction types for merchant card payments.
Authorizations aren't included in a transaction type.
Instead, they're represented at the payment level, visible through the payment object status Authorized and payment object balance totalAuthorized.
| Transaction type | Explanation | Impacted account balance |
|---|---|---|
CardInCredit | Captured payment that impacts the merchant's Booked balance. | UpcomingBooked |
CardInCreditReversal | Refunded payment that first impacts the merchant's Pending balance, then their Booked balance. | PendingBooked |
CardInCreditChargeback | Disputed payment that immediately impacts the merchant's Booked balance. | Booked |
CardInCreditChargebackReversal | Disputed payment for which the dispute is overturned, impacting the merchant's Booked balance. | Booked |
The impacted balances are Swan's standard account balances, which aren't related to the payment object balances explained later on this page.
Payment object statuses​
The merchant payment object has distinct statuses to follow a payment's lifecycle.
| Card payment object status | Explanation |
|---|---|
Initiated | Customer submitted their card details through the payment link, but the payment hasn't been authorized yet. |
Authorized | Authorization for the payment was received, but the funds aren't captured yet. The funds are guaranteed for the merchant. |
Captured | Authorized payments for which the funds have moved out of the customer's account. This can be a final status if the customer doesn't dispute the payment or request a refund. |
Rejected | Authorization denied by the issuer or by Swan. |
Canceled | Card payment was canceled, authorization voided, and the funds can't be captured. |
Refunded | Payments reversed by the merchant for some or all of the amount. |
Disputed | Customer disputed the payment with their bank for some or all of the amount. |
Payment object balances​
The merchant payment object has distinct balances to follow a payment's lifecycle.
| Card payment object balance | Explanation |
|---|---|
totalAuthorized | The total authorized amount for this merchant payment. |
availableToCancel | The authorized amount that can be released. Refer to this balance to verify whether the payment can be canceled. Cancellations must occur before the amount is captured. |
totalCanceled | The total amount canceled for this merchant payment. |
availableToCapture | The amount available for merchants to capture if the capture isn't automatic. |
totalCaptured | The amount captured by the merchant. When the capture for card payments is automatic, totalCaptured is always equal to totalAuthorized. |
availableToRefund | The amount the merchant can refund. Use this balance to know if a payment is eligible for a refund. |
totalRefunded | The total amount refunded for this merchant payment. |
totalDisputed | The total amount of this merchant payment disputed by the customer. |
Rolling reserve​
Rolling reserve is a policy Swan applies to merchant transactions to protect the merchant and Swan against various risk factors, primarily insufficient funds and attempted fraud. The reserved amount acts as a safety net to cover potential loss for both Swan and the merchant.
Rolling reserve is expressed as a percentage over a period of time (example: 10% of the payment amount over 30 business days), and applies to most payment methods used by merchants to accept payments with Swan.
For the indicated period of time, the amount isn't part of the merchant's available account balance, after which the funds are released to the merchant and can be used.
| Payment method | Rolling reserve | Default amount |
|---|---|---|
| Cards | ✓ Yes | 100% over 5 business days |
You can use the TransactionRollingReserve.Updated and TransactionRollingReserve.Released webhooks to be notified when a transaction's rolling reserve is updated and when the funds are released.
Payment amount limit​
For security and risk management, Swan may apply a payment amount limit to single card payments.
This limit defines the maximum amount a user can spend in one card transaction.
If a payment exceeds this limit, the API returns a ForbiddenRejection error.
To query this limit, use the paymentAmountLimit field at the merchantPaymentMethod level in the API.
Settlement date and booked time​
Merchant card transactions are booked the business day after the transaction is captured at 18:00 Coordinated Universal Time (UTC).
For example, transactions captured on Tuesday between 00:00 (midnight) and 23:59 UTC are booked on Wednesday, assuming both Tuesday and Wednesday are business days.
Days are measured as business days. Time is expressed with the 24-hour clock.
R-transactions​
Rejected​
When a card payment is rejected, the cardholder's account is not charged.
Card payments can be rejected (declined) for the following reasons:
| Rejection reason | Explanation | Action |
|---|---|---|
AmountInvalid | The amount entered is invalid for this payment. | Verify the payment amount is correct and within acceptable limits, then retry the transaction. |
CardDetailsInvalid | The card details provided are incorrect or incomplete. | Double-check the card number, expiration date, and card verification code (CVC). If the issue persists, contact your card issuer for verification and more information. |
CardExpired | The card used is no longer valid because it has expired. | Use a different card with a valid expiration date or request a replacement card from your issuer. |
InvalidPinAttemptsExceeded | Too many incorrect PIN attempts were made. | Reset the card PIN through your card issuer or contact them to unblock the card. |
RejectedByCardIssuer | The card issuer rejected the transaction. | Contact your card issuer immediately to understand the specific reason for rejection and resolve any issues. |
SoftDecline3dsExpiration | The 3D Secure authentication session expired before completion. | Retry the payment and complete the 3D Secure authentication within the time limit. |
SoftDecline3dsFailure | The 3D Secure authentication failed. | Verify your authentication details and retry. If issues persist, contact your card issuer. |
SoftDecline3dsNotSupported | The card does not support 3D Secure authentication. | Use a different card that supports 3D Secure or contact your card issuer for a compatible card. |
SoftDecline3dsRequired | 3D Secure authentication was required but not completed. | Retry the transaction and complete the required 3D Secure authentication. |
SoftDeclineCardAmountLimitsExceeded | The transaction exceeds the card's allowed spending limit. The cardholder should contact their card issuer for more information. | Contact your card issuer to increase your spending limit or split the transaction into smaller amounts. |
SoftDeclineCardDetailsInvalid | The card details provided are incorrect or incomplete. The cardholder should contact their card issuer for more information. | Verify all card details (number, expiration, CVC) are entered correctly and retry. |
SoftDeclineCardExpired | The card used is no longer valid because it has expired. | Use a card with a valid expiration date or request a replacement from your issuer. |
SoftDeclineCardNotActivated | The card has not been activated yet. The cardholder should contact their card issuer for more information. | Activate your card through your issuer's activation process before attempting the transaction again. |
SoftDeclineCardNotSupported | The card is not supported for this type of transaction. The cardholder should contact their card issuer for more information. | Use a different card or contact your card issuer to enable this transaction type. |
SoftDeclineCvcCheckFailed | The card security code (CVC) verification failed. | Verify the 3-digit CVC code on the back of your card and retry with the correct code. |
SoftDeclineCvcInvalid | The CVC code provided is invalid. | Check the CVC code on your card (3 digits on the back) and re-enter it correctly. |
SoftDeclineInsufficientFunds | There are insufficient funds to fulfill the payment. | Add funds to your account before retrying the transaction. |
SoftDeclineRefundTimeLimitExceeded | The refund could not be processed because the allowable time limit has passed. | Contact Swan Support or the merchant to explore alternative refund options. |
SoftDeclineRejectedByCardIssuer | The card issuer declined the transaction. | Contact your card issuer immediately to understand the reason for the decline and resolve the issue. |
SoftDeclineSwanTechnicalErrorOccurred | A technical error prevented the processing of this card payment. | Retry the transaction. If the problem persists, contact Swan Support with the transaction reference. |
SoftDeclineTransactionAmountIncorrect | The transaction amount does not match the expected or authorized amount. | Verify the transaction amount with the merchant and retry with the correct amount. |
SwanRefused | Swan refused the transaction due to risk management or compliance requirements. | Contact Swan Support to understand the specific reason and required next steps. |
SwanTechnicalErrorOccurred | A technical error prevented the processing of this card payment. | Retry the transaction. If the problem persists, contact Swan Support with the transaction reference. |
Chargebacks & disputes​
Cardholders might create chargebacks, which opens a dispute. Merchants can view the dispute automatically; the payment object status, the transaction status, and the merchant's balance all change to reflect the dispute.
To respond to disputes, ask your merchant to submit a request to the Swan Support team.