In-person cards
For many businesses, accepting card payments in person is a must-have. Retail stores, health professionals, home care providers, taxi drivers, and contractors all need to accept card payments on the go.
With Swan's API, merchants can turn their smartphone into a card terminal. They accept payments through a simple terminal app in just a few taps.
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 and a refund, for a total of two transactions.
These transactions are grouped in the merchant payment object. We suggest using this object in your integration to help merchants match orders, invoices, and sales to the correct payment. This makes it easier to track payments and resolve issues.
Card transaction types
There are four transaction types for in-person merchant card payments.
These statuses are specific to in-person card payments. Other payment methods might behave differently.
Authorizations aren't a transaction type.
Instead, they appear at the payment level through the payment object status Authorized and the balance totalAuthorized.
| Transaction type | Explanation | Possible statuses |
|---|---|---|
CardInCredit | Captured payment that will be settled through a separate credit transfer. | Upcoming, Settled |
CardInCreditReversal | Refunded payment that will be settled through a separate credit transfer. | Upcoming, Settled |
CardInCreditChargeback | Disputed payment that will be settled through a separate credit transfer. | Upcoming, Settled |
CardInCreditChargebackReversal | Overturned dispute that will be settled through a separate credit transfer. | Upcoming, Settled |
Settled status
The Settled status means a credit transfer was Booked on the account to settle the merchant.
Individual card transactions don't affect the balance. The Settled status is final.
Instead, the credit transfer affects the Booked balance directly.
Every Settled transaction includes a settlementTransactionId field. Use it to identify the credit transfer that affects the balance.
Each settlement credit transfer also includes the list of settled transactions.
Payment object statuses
The merchant payment object has distinct statuses to follow a payment's lifecycle.
| Payment object status | Explanation |
|---|---|
Initiated | The payment was created on the terminal app and is ready to be taken. |
Authorized | Authorization received, but funds aren't captured yet. The funds are guaranteed for the merchant. |
Captured | Funds moved out of the customer's account. This can be a final status if the customer doesn't dispute or request a refund. |
Rejected | Authorization denied by the issuer or by Swan. |
Canceled | Card payment canceled. The authorization is voided and funds can't be captured. |
Refunded | Payment 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. Use these balances to check what happened on a payment and what you can still do (such as cancel or refund).
| Payment object balance | Explanation |
|---|---|
totalAuthorized | The total authorized amount for this merchant payment. |
availableToCancel | The authorized amount that can be released. Check this balance to verify if 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 merchants can capture if the capture isn't automatic. |
totalCaptured | The amount captured by the merchant. When capture is automatic, totalCaptured always equals totalAuthorized. |
availableToRefund | The amount the merchant can refund. Check this balance to know if a refund is possible. |
totalRefunded | The total amount refunded for this merchant payment. |
totalDisputed | The total amount of this merchant payment disputed by the customer. |
Rolling reserve
In-person card payments are not subject to a rolling reserve by default. This could change if Swan's monitoring systems detect suspicious patterns.
Payment amount limits
The minimum amount to create a payment intent is €0.50.
In-person card payments are not subject to a maximum payment amount limit by default. This could change if Swan's monitoring systems detect suspicious patterns.
Settlement process
For in-person card payments, the settlement is a credit transfer.
- When the merchant payment is created, underlying transactions are created as
Upcoming. - When the settlement arrives as a credit transfer, the transactions are updated to
Settled. - The credit transfer is immediately
Booked. It affects the balance and makes the corresponding funds available. Card transactions don't affect any account balances. - Transactions captured on a given day are
Settledwithin one business day. No rolling reserve applies to the settlement credit transfer.
The minimum amount for a settlement credit transfer is €1.
Days are measured as business days. Time is expressed with the 24-hour clock.
Refunds
Refunds are currently not supported for in-person card payments. To initiate a refund, ask your merchant to submit a request to the Swan Support team.
R-transactions
Rejected
Card payments can be rejected for the following reasons:
| Status reason | Explanation | Next steps |
|---|---|---|
CardNotSupported | The card doesn't support this type of purchase. | Ask the customer to use a different card. |
RejectedByCardAcquirer | The payment was declined by the acquirer due to fraud or risk rules. | Present this as a generic decline without sharing details. |
RejectedByCardIssuer | The card was declined by the issuer. It might be invalid, lost, stolen, or restricted. | Ask the customer to contact their card issuer. |
SoftDecline3dsRequired | The transaction requires 3D Secure authentication. | Retry with authentication. If already done, ask the customer to contact their issuer. |
SoftDeclineCardDetailsInvalid | The card number or expiry date is incorrect. | Ask the customer to retry with the correct details. |
SoftDeclineCardExpired | The card has expired. | Ask the customer to use a different card. |
SoftDeclineCvcInvalid | The CVC is incorrect. | Ask the customer to retry with the correct CVC. |
SoftDeclineInsufficientFunds | The card has insufficient funds. | Ask the customer to use a different payment method. |
SoftDeclineInvalidPinAttemptsExceeded | Too many incorrect PIN attempts. | Ask the customer to use a different card or payment method. |
SoftDeclinePinInvalid | The PIN entered is incorrect. | Ask the customer to retry with the correct PIN. |
SoftDeclinePinRequired | A PIN is required for this card. | Ask the customer to insert their card and enter their PIN. |
SoftDeclineRejectedByCardIssuer | The card was declined by the issuer. Possible causes include velocity limits or issuer downtime. | Retry the payment. If still declined, ask the customer to contact their issuer. |
SoftDeclineSwanTechnicalErrorOccurred | A technical error occurred while processing. Possible causes include an incorrect address, invalid amount, or processing failure. | Retry the payment. If it still fails, try again later. |
SwanTechnicalErrorOccurred | A technical error occurred on Swan's side. | Retry the payment. If the issue persists, contact Swan Support. |
Chargebacks and disputes
Cardholders might request a chargeback, which opens a dispute. Merchants can view the dispute right away. The payment object status and balances update to reflect it. However, it's not possible to act on disputes directly using Swan's APIs or dashboards.
To respond to disputes, ask your merchant to submit a request to the Swan Support team.
Known issues
The following issues have been identified and are not yet resolved. This section will be removed once they are fixed.
MerchantPayment.Created webhook not triggered (issue 1881)
When a payment succeeds or fails, the MerchantPayment.Created webhook is not sent.
Workaround: use other webhooks to track merchant payments. For successful payments, MerchantPayment.Authorized and MerchantPayment.Captured are both triggered. For failures, use MerchantPayment.Rejected.
Gateway timeout on invalid payment amount (issue 1835)
Calling createInPersonPaymentIntent with an invalid amount (such as an empty string or "1,5") returns a gateway timeout instead of a ValidationRejection.
Workaround: validate the amount value before passing it to the mutation.
Incorrect refund balance on rejected payments (issue 1759)
When a merchant payment is Rejected, the full payment amount appears on the availableToRefund balance even though refunds aren't supported for rejected payments.
Workaround: treat the availableToRefund balance as 0 for rejected payments.
Guides
- Accept in-person card payments
- Set up the development environment
- Request in-person card payment method
- Initialize the device for payments
- Create in-person card payments
Testing scenarios for in-person card payments are in development.