Card Payment
There are two steps to managing card payments:
  • Authorization: allowing a merchant to verify, in real-time, that the payer really has the authorization to make the payment (security features are respected, there is sufficient available balance, active card status, spending limits haven't been exceeded...) This can be online or offline depending on the payment terminal.
  • Clearing: allowing the merchant to ask, asynchronously, for debit or credit on a card.
The transaction object contains a specialized CardTransactioninterface featuring the specific payment data per card such as:
  • Terminal ID: unique identifier of the terminal in the Mastercard network
  • Merchant ID: unique identifier of the merchant in the Mastercard network
  • Merchant Name
  • Merchant City
  • Merchant Category Code (MCC)
  • Original Amount and Currency

Authorization

Online

When a cardholder makes a payment with their card, the majority of payment terminals make an authorization request online.
If the authorization is refused, a transaction of CardOutAuthorization type is created with the refused status and the reasonCode describing the reason for the refusal.
On the other hand, when the authorization is accepted, a transaction of CardOutAuthorization type is created with pending status, and the available balance of the account is impacted. The spending amount linked to the card is updated.
In some cases, such as fuel distributors, an authorization can be partial. In fact, if the merchant asks for 120€ while the available account balance is only 55€, Swan can accept the authorization for just 55€.
Sometimes, an authorization can also be updated at a later time. In fact, the fuel distributor could have received authorization for 55€ but the moment the client hangs up the nozzle, the authorization is updated to 24€, corresponding to the amount actually consumed. In this case, the amount of the transaction with pending status is updated and the amount that is no longer authorized is free from the available balance.
An authorization is not valid forever, we've decided to wait for a clearing of between 10 and 30 days depending on the type of business before expiring the transaction. The expiration date is in the pendingEndDate field of the PendingTransactionStatusInfo object describing the pending status of a transaction.
Once an authorization is expired, the available balance that has not been debited is freed and the transaction is updated to released status. The spending amount linked to that card is decreased to the amount of the authorization.
All transactions linked to an authorization are linked by the same payment: authorization, debits, credits, chargeback.
To simulate these exterior events in the Sandbox, we have added the Event Simulator tab to your dashboard. It lets you test different scenarios.
The Mastercard network always requires Swan to either approve or deny transactions. With the Payment control feature, you are brought into the process. Payment Control allows you to approve or deny every single card transaction. More details here.

Offline

It can happen that some payment terminals in physical sales points are not able to carry out authorizations online (parking, tolls, planes, trains, network failure, ...). In this case, the payment can still be accepted offline in the limit of an amount defined by Swan, depending on the account holder's risk level.
In this case, the payment is still taken into account by Swan at the moment of clearing without having to use the online authorization process.

Clearing

Debit

When a merchant requests debit on a card, Swan receives the information asynchronously and creates a new transaction of CardOutDebit type with booked status. This impacts the account's booked balance.
If a debit transaction is linked to an authorization, the corresponding transaction , withCardOutAuthorization type and pending status, is updated with the remaining amount to be debited. If the amount of this authorization is ≤ 0, the status released is applied. The spending amount linked to the card is updated with the right amount.
It's possible to have one or several partial debits on an authorization. Example: a client buys 2 products for 150€ at an online shop, the first product worth 50€ is shipped but the second of 100€ is out of stock. The first transaction of 150€ with pending status is updated to 100€ and a new transaction is created with booked status for an amount of 50€.
Watch out, it's also possible to be debited more than the amount initially authorized. It's possible to receive a debit after an authorization has expired (and was therefore already Released). In this case the two transactions will be linked together within the same Payment.
To simulate these exterior events in the Sandbox, we have added the Event Simulator tab to your dashboard. It lets you test different scenarios.

Credit

When a merchant requests credit on a card, Swan receives the information asynchronously and creates a new transaction with CardOutCredit type and booked status. This impacts the account's booked balance.
If a credit is a debit reversal, the 2 transactions will be linked to the same payment and the type will be CardOutDebitReversal
To simulate these exterior events in the Sandbox, we have added the Event Simulator tab to your dashboard. It lets you test different scenarios.

Chargebacks

When a client is a victim of fraud, they must declare it to Swan. If, after an investigation by our fraud team, the chargeback is admissible, a new credit transaction of InternalCreditTransferIn type with booked status is created and will impact the account's booked balance.
The transaction of the chargeback is linked to the same payment as the transaction of the initial debit.
To simulate these exterior events in the Sandbox, we have created the tab Event Simulator to your dashboard. It lets you test different scenarios.