Transactions life cycle

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 attribute
• authorizationNote 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.

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.

1. An authorization request of €150 is issued by the dispenser.
2. The cardholder account balance is €100.
3. The card transaction is partially authorized.
4. 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 INTRACOUNTRY
• 6537 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 10^th to 11^th day, the Authorized Balance is freed up.

Expirations don't create cardTransaction webhooks or operations.

Examples

Please check our list of transactions examples