Transactions lifecycle
You will find below details about each possible step, why they occur, and how to use them. Except for one, each step sends a cardtransaction.create
webhook.
Authorization
Authorization is the first step of a card payment.
An authorization allows the merchant to request the approval of the issuer for a transaction. When a cardholder pays or makes a withdrawal with their card, an authorization request is sent to Treezor, allowing the cardholder's spending limits and restrictions to be enforced.
A yes/no decision (accepted/declined) is then provided to the acquirer and merchant/ATM.
Authorization accepted
This immediately deduces the amount from the Authorized Balance of the cardholder but leaves the Balance unchanged.
When an authorization is accepted, a card transaction is created, with one of the following payment status.
paymentStatus | Event | Description |
---|---|---|
A (Accepted) | cardTransaction.create | When the transaction is authorized normally. |
C (Cleared) | cardTransaction.create | When the authorization occurred offline. |
Information – Offline transactions are processed asynchronously
You're notified only once the merchant's clearing is received. It may take up to several days after the cardholer's purchase for the clearing to occur.
Authorization declined
A declined transaction is final and not followed by any other operations. It doesn't affect either the Balance nor the Authorized Balance.
When an authorization is declined, a card transaction is created, with the following payment status.
paymentStatus | Event | Description |
---|---|---|
I (Declined) | cardTransaction.create | When the transaction isn't authorized. |
Possible reasons for decline include (but are not limited to):
- An online payment is attempted, but the Card options don't allow online payments
- The payment amount is higher than the Card payment limit
- The
merchantId
that requests the authorization is blacklisted in the Card options - The cardholder has insufficient funds
- A network error occurred
Information – The decline reason is in the cardtransaction
webhook:
authorizationResponseCode
attributeauthorizationNote
attribute when relevant
In some situations, when an error occurred high up in the banking network (Negative Advice), you were not notified of the transaction attempt and of its decline. Producing a situation where your customer was aware of an authorization failure, but your Support Users were not.
You can now opt-in to receive these notifications. They will produce cardtransaction.create
webhooks with a paymentStatus
valued to I
and an authorizationMti
valued to 120
.
Authorization accepted, then declined
This is a very rare case. It can occur when Treezor accepts an authorization, but the acceptance doesn't reach the merchant because of card network errors. When this happens, a declined authorization is emitted in the hours that follow.
Partial Authorization
A partial authorization occurs when there are insufficient funds to cover the full amount of the transaction. In such cases, if the merchant handles partial authorizations and if the transaction is in euros, then only the amount available is authorized.
The partial authorization have the following attributes.
Attribute | Value |
---|---|
paymentStatus | A (Accepted) |
authorizationResponseCode | 10 (PARTIAL_APPROVAL) |
Example
Let's take the example of a transaction at an automated fuel dispenser.
- An authorization request of €150 is issued by the dispenser.
- The cardholder account balance is €100.
- The card transaction is partially authorized.
- The cardholder can use the dispenser for up to €100 of fuel.
Pre-Authorization
A pre-authorization is generally used when the final transaction amount is not yet known in order to put a hold on an amount approved by the issuer. For example, at an automated fuel dispenser.
Pre-Authorization behaves exactly like authorization. Only the authorizationNote
attribute of a webhook may specify "pre-authorization".
Information – Specific processing for USA and Canada AFDs
Treezor applies a fixed pre-authorized amount of €160 for all pre-authorization requests made in the USA or Canada for automated fuel dispensers (AFD) payments. Learn more in the automated fuel dispenser example.
Settlement
The settlement is the step where funds are actually debited from the cardholder's wallet/account and credited to the merchant's wallet/account. It generally shows up three days after the authorization and affects the Balance.
A settlement can be complete, partial, and even multiple
Consider an authorization of €1,000. There could be:
- A single settlement of €1,000 complete
- One settlement of €750 and a reversal of €250partial
- Two settlements of €500 eachpartial+multiple
- Three settlements of €333.33 eachpartial+multiple
- etc.
When a settlement occurs, a card transaction is created, with the following payment status.
paymentStatus | Event | Description |
---|---|---|
S (Settled) | cardTransaction.create | When the transaction is settled. |
MoneySend
Important – Progressive feature rollout
The MoneySend transaction feature will be rolled out progressively. Your Account Manager will contact you to adjust your implementation as needed.
A MoneySend card transaction credits the cardholder's account.
It occurs in 2 steps:
- Authorization, during which Treezor verifies the MoneySend validity (account and card).
- Settlement, after which the funds can be used by the cardholder. This generally the day after the authorization.
These transactions can be accepted or refused in the same way as authorizations.
Note – The amount is not available to the cardholder until the settlement is received
You can rely on the authorization webhook which indicates that the transaction is in progress.
In the webhooks received for MoneySend transactions, amounts are displayed as negative values. For example: "paymentAmount": "-7.00"
Also, MoneySend card transactions can have one of the following MCC:
6536
for MONEYSEND INTRACOUNTRY6537
for MONEYSEND INTERCOUNTRY available soon
When a MoneySend transaction occurs, a card transaction is created, with one of the following payment status.
paymentStatus | Event | Description |
---|---|---|
M (MoneySend) | cardTransaction.create | When the MoneySend transaction is accepted. |
S (Settled) | cardTransaction.create | When the MoneySend transaction is settled. |
I (Declined) | cardTransaction.create | When the MoneySend transaction is refused. |
MoneySend and external validation
When using Transactions external validation, you can identify MoneySend transactions thanks to the mcc
attribute valued to 6536
or 6537
.
Alert – MoneySend Intercountry is not available yet
Therefore, even if you accept a MoneySend transaction with the 6537
MCC through external validation, Treezor will decline the transaction.
The webhooks sent will be exactly the same as for a regular MoneySend transaction, as described above.
Reversal
A reversal follows an accepted authorization and cancels it at the merchant's request. Funds have not yet been debited nor credited when a reversal occurs, so only the Authorized Balance of the cardholder is affected.
A reversal can be complete or partial.
Consider an authorization of €1000. There could be:
- One reversal of €1,000 complete
- One reversal of €100 and a settlement of €900 partial
- One reversal of €900 and a settlement of €100 partial
- etc.
When a Reversal occurs, a card transaction is created, with the following payment status.
paymentStatus | Event | Description |
---|---|---|
V (Reversed) | cardTransaction.create | When the merchant cancels an accepted authorization. |
Refunds
A refund is the act of requesting a refund, when funds have effectively been debited from the cardholder's wallet (due to a previous settlement).
Therefore it affects the actual Balance.
They behave in a similar way as authorizations do:
- They can be either accepted or declined
- They can be followed by a complete or partial settlement (of negative amount value)
Refund accepted
When a Refund is accepted, 2 card transactions are created, with the following payment status.
paymentStatus | Event | Description |
---|---|---|
R (Refund) | cardTransaction.create | When the Refund is accepted. A negative amount is displayed. |
S (Settled) | cardTransaction.create | When the Refund is settled. A negative amount is displayed. |
Refund declined
When a Refund is declined, a card transaction is created, with the following payment status.
paymentStatus | Event | Description |
---|---|---|
I (Declined) | cardTransaction.create | When the Refund is declined. |
Chargeback
Chargeback is a process that happens when the cardholder disputes a card payment that has been approved and settled.
The reason for the dispute may be due to a suspected fraud or an unfulfilled order of goods/services. The chargeback is initiated by the issuer at the request of the cardholder. If accepted, the cardholder account will be credited.
Expiration
An expiration occurs when an Authorization was accepted but was not followed by any settlement or reversal in the 10 following days.
On the night of the 10th to 11th day, the Authorized Balance is freed up.
Expirations don't create cardTransaction
webhooks or operations.
Examples
Please check our list of transactions examples