Cards for merchants
Accepting card payments is in private beta.
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. AmericanExpress isn't supported.
Merchants can use payment links to accept payments from cardholders anywhere. Collect rent, share invoices, and accept customer payments through a Swan merchant account.
This section only applies to merchants accepting card payments. Visit the cards 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 |
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​
Card payments can be rejected (declined) for a long list of reasons, including:
- Failed 3-D Secure (3DS) authentication
- Insufficient funds
- Bank refusal (often without further information)
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.