Reversal notifications

The network may reverse a previously-approved authorization (for example, due to timeout/technical failure, or a merchant reversal). When Open Fabric receives these events, we forward them to you as reversal notifications.

These notifications are real-time. You are expected to update the relevant ledgers and customer accounts.

tip

Most commonly, reversal notifications are sent shortly after an authorization (for example, due to a network failure). However, merchants may also reverse an authorization later, potentially days later. As such, you should design your system to be able to process reversals at any time until an authorization expires.

You must implement a REST endpoint (webhook) to receive these notifications. Upon receiving a reversal notification, acknowledge receipt by responding with 200 OK within 60 seconds. If we do not receive a 200 OK, we will assume there was an issue with your systems and will retry the notification according to our retry logic.

Use notification_id to prevent duplicate processing. See Notifications for more information.

info

It is possible to receive reversal notifications for authorizations you've declined. In this case, you do not need to update any ledgers in your system.

Types of reversal notifications

Final authorization reversal

For a final authorization approval, there can only be one final authorization reversal notification (for the full amount). When receiving this notification, reverse the original final authorization (for example, credit back the deducted amount).

Please see the Final authorization reversal for implementation details.

Example Final Authorization Reversal

{
    "notification_id": "8bedf365-8442-4b6e-a480-7dad7b40ac44",
    "type": "v1:pba:transaction:final_auth_reversed",
    "created_at": "2023-06-24T14:15:22Z",
    "data": {
        "notification_id": "8bedf365-8442-4b6e-a480-7dad7b40ac44",
        "transaction_id": "6182bde8-ee3e-4bd5-935e-e56507e0f809",
        "tenant_reference_id": "31XXXX6723173606",
        "network_transaction_ref": "awqcB1rPDuJIm4yKOQbqJUj5MvpdcH6E",
        "network_message_ref": "CZLIzgNfeyMCabcsXp3liJPgSVGyQypHI2B",
        "amount": 10.0,
        "currency_code": "SGD",
        "billing_amount": 10.0,
        "billing_currency_code": "SGD",
        "billing_exchange_rate": 1.0,
        "settlement_amount": 10.0,
        "settlement_currency_code": "SGD",
        "settlement_exchange_rate": 1.0
    }
}

Pre-authorization reversal

For a pre-authorization approval, there can be multiple pre-authorization reversal notifications, and each reversal can be for part or all of the hold balance that was set aside for this payment. When receiving these notifications, adjust or remove the original hold/available balance.

info

If a pre-authorization is fully reversed, it will not be part of the clearing process.

Please see the Pre-authorization reversal for implementation details.

Example Pre-Authorization Reversal

{
    "notification_id": "8bedf365-8442-4b6e-a480-7dad7b40ac44",
    "type": "v1:pba:transaction:pre_auth_reversed",
    "created_at": "2023-06-24T14:15:22Z",
    "data": {
        "notification_id": "8bedf365-8442-4b6e-a480-7dad7b40ac44",
        "transaction_id": "6182bde8-ee3e-4bd5-935e-e56507e0f810",
        "tenant_reference_id": "31XXXX6723173607",
        "network_transaction_ref": "awqcB1rPDuJIm4yKOQbqJUj5MvpdcH6E",
        "network_message_ref": "CZLIzgNfeyMCabcsXp3liJPgSVGyQypHI2C",
        "amount": 50.0,
        "currency_code": "SGD",
        "billing_amount": 50.0,
        "billing_currency_code": "SGD",
        "billing_exchange_rate": 1.0,
        "settlement_amount": 50.0,
        "settlement_currency_code": "SGD",
        "settlement_exchange_rate": 1.0
    }
}

Authorization failed notification

In the scenario where some error happened during the authorization process (e.g. because your endpoint returned a non-200 response or timed out), you may receive the authorization failed notification. This may apply for both final authorizations and pre-authorizations.

If you have previously approved the authorization in your system, you are required to revert it based on this notification. But if the authorization is already declined in your system, you can disregard this notification.

warning

Please take note of the special scenario where a pre-authorization failed for an incremental approval of an existing transaction. If this is the case, do not cancel the entirety of the hold balance but only the additional amount which was requested for incremental approval.

Please see the Authorization failed notification for implementation details.

Example Authorization failed notification

{
    "notification_id": "3e6dd7ab-3360-4269-821e-a591bc94232c",
    "type": "v1:pba:transaction:authorization_failed",
    "created_at": "2024-06-06T18:47:21.175Z",
    "data": {
        "notification_id": "3e6dd7ab-3360-4269-821e-a591bc94232c",
        "transaction_id": "2f8b3dd0-dc7a-4f93-96bf-0042d3ce697e",
        "transaction_type": "final_auth",
        "network_transaction_ref": "MCC0377270606",
        "network_message_ref": "439951",
        "amount": 30,
        "currency": "PHP",
        "billing_amount": 30,
        "billing_currency_code": "PHP",
        "billing_exchange_rate": 1,
        "transaction_status": "declined",
        "reason": "Tenant Service Error: no response from tenant, undefined",
        "advised_action": "reverse_transaction"
    }
}