Clearing reports

Clearing is the process where the network requests funds movement for previously-authorized transactions. Clearing is provided in batches (multiple times per day).

How it works

1. Open Fabric sends a clearing file ready notification (see Clearing file ready notification).
2. You download the clearing report from the provided URL specified in the clearing file ready notification.
3. You process each instruction and apply the appropriate operations in your ledger / settlement accounting.

info

The clearing report will be uploaded to a specific S3 bucket and the complete S3 URL of the report will be included as file_ref in the clearing file ready notification.

The S3 bucket details will be established as part of the onboarding process.

Structure of the clearing report

File name PBA_EOC_<UUID>_<YYYYMMDD>_<HHmmSS>.json

File format JSON

Location S3 Bucket as configured for you.

Frequency 7 times a day, corresponding to the end of clearing cycles from the card network.

note

Approximate times: ~ 05:10 UTC ~ 08:10 UTC ~ 11:10 UTC ~ 14:10 UTC ~ 16:10 UTC ~ 18:10 UTC ~ 02:10 UTC (T+1)

Schema See Clearing report schema

Handling different clearing instructions in a clearing report

Instruction Type	Description
Final-Authorization (final_auth)	Contains clearing details for final authorizations. In the common scenario, there should not be any final authorization clearing record related to a final authorization that has been authorized in real time. However, if the merchant submits a clearing request with an amount that is different from the authorized amount (greater or lesser amount), you will receive this clearing instruction. If the amount is greater, you must deduct the additional amount (cleared amount minus original authorized amount) from the customer account as instructed. You can raise a chargeback to request a refund (is_potential_chargeback will be true). If the amount is lesser, you must refund the customer account by the difference (original authorized amount minus cleared amount). Also see Scenarios where authorization amount can change
Final-Authorization Partial (final_auth_partial)	Exceptional scenario where the merchant submits multiple clearing requests, each with an amount less than the authorized amount. If the total sum of these amounts is greater than the original authorized amount, you must deduct the additional amount (sum cleared amount minus original authorized amount) from the customer account as instructed. You can raise a chargeback to request a refund (is_potential_chargeback will be true). If the total sum of these amounts is still less than the original authorized amount, you must revert the customer account by the difference (original authorized amount minus sum cleared amount). Also see Scenarios where authorization amount can change
Pre-Authorization Partial (pre_auth_partial)	Contains clearing details for pre-authorizations. There could be one partial clearing record or multiple partial clearing records related to a pre-authorization. You should deduct the specified cleared amount from the holding balance in the customer account, but still maintain the rest of the hold. Only when processing pre_auth_expiry or pre_auth_final can the remaining holding balance be released.
Pre-Authorization Final (pre_auth_final)	Contains clearing details for pre-authorizations. There should be only one pre-authorization final record related to a pre-authorization. You should deduct the specified cleared amount from the holding balance in the customer account, and release the remaining holding amount back to the customer account. This transaction is now considered completed in the clearing process. Exceptional scenario: In rare cases when the pre_auth_final was a mistake, the merchant can revert this with a pre_auth_final_reversal, which makes the pre-authorization available again for clearing (with either a second pre_auth_final or a pre_auth_expiry)
Final-Authorization Reversal (final_auth_reversal)	Contains information about a clearing reversal. You should revert the respective amount back to the customer account. This reversal is linked to a final authorization that has been authorized before. In the common scenario, there should not be any final authorization clearing reversal record related to a final authorization that has been authorized in real time. However, if the merchant submitted a clearing request for the final authorization by mistake and decides to reverse it, you may receive this instruction.
Final-Authorization Partial Reversal (final_auth_partial_reversal)	Similar scenario as a final authorization reversal (final_auth_reversal), but the reversal amount will be less than the original authorized amount in this case.
Pre-Authorization Partial Reversal (pre_auth_partial_reversal)	Contains information about a clearing reversal. When processing this, you should revert the specified cleared amount to the holding balance in the customer account.
Pre-Authorization Final Reversal (pre_auth_final_reversal)	Contains information about a clearing reversal. When processing this, you should revert the specified cleared amount to the holding balance in the customer account. Exceptional scenario: This nullifies the last pre_auth_final: the transaction is considered still in the clearing process, and you should expect another pre_auth_final or pre_auth_expiry later.
Expired Final-Authorization (final_auth_expiry)	Contains information about the expired authorization. Final authorizations have an expiry of 7 days. You should revert the authorized amount back to the customer account.
Expired Pre-Authorization (pre_auth_expiry)	Contains information about the expired authorization. By default, a pre-authorization has an expiry of 30 days. When processing this, you should release the remaining hold balance in the customer account.
Refund (refund)	Contains clearing information about refunds. This refund is already approved and cleared, and you should refund the respective amount back to the customer account. This refund clearing is linked to an original final authorization or pre-authorization.
Refund Clearing Reversal (refund_reversal)	Contains information about the refund clearing reversal. When processing this, you should revert the refunded amount from the customer account in the previous refund. This refund clearing reversal is linked to an original final authorization or pre-authorization. If the merchant submitted a clearing request for a refund by mistake and decides to reverse it, you may receive this instruction.
Expired Refund (refund_expiry)	Contains clearing information about refunds that are expired. When a merchant requests an online refund, we automatically accept these. By default, we will not inform you of an online refund authorization, but you can choose to listen to a notification when this event happens. If after the expiry window (typically 7 days after the online refund authorization) the merchant has not yet cleared the refund this instruction will be present in the clearing report. If you do not listen to notifications during online refund authorization, you can ignore this type of instruction in the clearing file. If you are listening to our notifications and have already refunded the customer's account based on that, you can use this instruction to revert that refund.
Chargeback (chargeback)	Contains information about a chargeback after it has been cleared and settled by the acquirer. In conjunction with the chargeback challenge and chargeback challenge reversal messages, you may decide when and how to credit the amount back to the customer account at your discretion. This is called first presentment.
Chargeback Reversal (chargeback_reversal)	Contains information about the reversal of the first presentment.
Chargeback Challenge (chargeback_challenge)	Contains information about the merchant’s challenge related to a chargeback. This is called the second presentment. After a chargeback is created, merchants have 45 days to submit a challenge.
Chargeback Challenge Reversal (chargeback_challenge_reversal)	Contains information about the reversal of the merchant’s second presentment.
Fee Collection Credit (fee_collection_credit)	Contains information about transaction fees collected by the card network crediting your account. These fees will be aggregated in a single fee_collection_credit transaction per clearing cycle. These clearing records are not related to any customer account.
Fee Collection Credit Reversal (fee_collection_credit_reversal)	Contains information about the reversal of a fee_collection_credit. These clearing records are not related to any customer account.
Fee Collection Debit (fee_collection_debit)	Contains information about fee collection from the card network debiting your account. For example: when a chargeback is escalated to the card network, you must pay a fee per disputed case so that it will be ruled by the card network. These clearing records are not related to any customer account.
Fee Collection Debit Reversal (fee_collection_debit_reversal)	Contains information about the reversal of a fee_collection_debit. These clearing records are not related to any customer account.
Unlinked Authorization Partial (unlinked_auth_partial)	You may receive these clearing instructions for an unauthorized transaction (where there is no corresponding final authorization or pre-authorization that can be identified for this clearing). In this case, you must deduct the specified cleared amount from the customer account as instructed in each instruction. You can raise a chargeback to request a refund (is_potential_chargeback will be true).
Unlinked Authorization Final (unlinked_auth_final)	You may receive this clearing instruction for an unauthorized transaction (where there is no corresponding final authorization or pre-authorization that can be identified for this clearing). In this case, you must deduct the specified cleared amount from the customer account as instructed. You can raise a chargeback to request a refund (is_potential_chargeback will be true).
Unlinked Authorization Partial Reversal (unlinked_auth_partial_reversal)	You may receive these clearing instructions for an unauthorized transaction (where there is no corresponding final authorization or pre-authorization that can be identified for this clearing). When processing this, there are 2 scenarios: 1) This clearing reversal is a subsequent reversal of a previous unlinked_auth_partial: you revert the amount back to the customer account as instructed. 2) There is no unlinked_auth_partial prior to this clearing reversal: you can choose to revert the amount back to the customer as instructed or put this amount into a holding balance until settlement is finished.
Unlinked Authorization Final Reversal (unlinked_auth_final_reversal)	Handle the same as unlinked authorization partial reversal (unlinked_auth_partial_reversal).
Unlinked Refund (unlinked_refund)	Contains clearing information about refunds. This refund is not linked to any final authorization or pre-authorization. When processing this, you can choose to refund the respective amount back to the customer account, or put this amount into a holding balance until settlement is finished.
Unlinked Refund Reversal (unlinked_refund_reversal)	You may receive these clearing instructions for an unauthorized transaction (where there is no corresponding final authorization or pre-authorization that can be identified for this clearing). When processing this, there are 2 scenarios: 1) This clearing reversal is a subsequent reversal of a previous unlinked_refund: you revert the refunded amount from the customer account as instructed. 2) There is no unlinked_refund prior to this clearing reversal: you must deduct the specified cleared amount from the customer account as instructed. You can raise a chargeback to request a refund (is_potential_chargeback will be true).