Skip to main content

Authorization messages

Open Fabric forwards real-time authorization messages to your backend for an approval/decline decision. These requests must be handled in sub-second time to avoid network timeouts and customer-facing declines.

You are expected to expose two REST endpoints that we call for each type of authorization message. After performing your evaluation (for example: customer balance, risk checks, and business rules), respond with a 200 OK and indicate whether you approve or decline the authorization.

If we receive an error (i.e., any non-200 response such as 4xx/5xx) or a timeout, we will decline the payment on your behalf.

info
  • If you are using our Real-time Authorization and Clearing Reports integration, you will need to update your internal ledgers based on the authorization message (see below your typical ledger action for each type of authorization message).
  • If you are using our Ledger APIs integration, you will receive separate API calls to update your internal ledgers.

Types of authorization​

Final authorization​

This is sent when the merchant knows the exact amount that should be charged for a payment.

  • Your typical ledger action: deduct available balance.
  • Clearing note: final authorizations are typically not repeated in clearing files unless the merchant later submits a clearing amount that differs from the authorized amount.

Once a final authorization has been approved, it can be active for 7 days. During this period, merchants can request settlement. If the merchant does not request settlement, the authorization will expire after 7 days and we will inform you of this expiry in the clearing file and/or the Ledger APIs.

Please see the Authorization message in our API Reference for implementation details.

Request Example
{
  "transaction_id": "6182bde8-ee3e-4bd5-935e-e56507e0f808",
  "network_transaction_ref": "awqcB1rPDuJIm4yKOQbqJUj5MvpdcH6D",
  "customer_id": "8e64c3c2-f409-4e0b-afb7-05cce88d26d7",
  "tenant_customer_ref": "01HG04B4NDBB7XT9JY6H1Y2B3A",
  "account_id": "5ce21f7b-7651-43ea-bf61-b1175f5acbbe",
  "tenant_account_ref": "FR12345678901",
  "provision_id": "f4e52b39-3664-48ce-844c-7a92772b1f2e",
  "provision_type": "customer_account_device",
  "device_id": "f4e52b39-3664-48ce-844c-7a92772b1f2e",
  "network_message_ref": "CZLIzgNfeyMCabcsXp3liJPgSVGyQypHI2A",
  "network_merchant_name": "Merchant123456",
  "network_merchant_id": "6000123456",
  "network_merchant_outlet_address": "Central, Singapore",
  "network_merchant_category_code": "1234",
  "network_merchant_country_code": "SG",
  "network_acquirer_id": "000003",
  "token_requestor_id": "50120834693",
  "auth_indicator": {
	"is_partial_approval": false,
	"is_converted_pre_auth": false,
	"is_incremental_approval": false
  },
  "amount": 20.0,
  "currency": "SGD",
  "billing_amount": 20.0,
  "billing_currency_code": "SGD",
  "billing_exchange_rate": 1.0,
  "settlement_amount": 20.0,
  "settlement_currency_code": "SGD",
  "settlement_exchange_rate": 1.0,
  "transaction_source": "terminal",
  "transaction_category": "other",
  "verification_data": {}
}
Response Example
{
  "tenant_reference_id": "31XXXX6723173605",
  "approved_amount": 20.0,
  "authorization_code": "8ABJ6S",
  "status": "approved",
  "reason": null
}

Pre-authorization​

This is sent when the merchant does not yet know the exact amount to be charged (e.g., hotel deposit, transit) or when fulfillment of the goods or services is not happening right away.

  • Your typical ledger action: place a hold on funds (earmark balance).
  • A pre-authorization can later be:
    • finalized (final clearing)
    • partially cleared multiple times
    • expired (release remaining hold)
    • incremented (additional pre-authorization approvals)

Once a pre-authorization has been approved, it can be active for up to 30 days. During this period, merchants can request any of the above actions. If the merchant does not act on the authorization, it will expire after 30 days and we will inform you of this expiry in the clearing file and/or the Ledger APIs.

Please see the Authorization message in our API Reference for implementation details.

Request Example
{
  "transaction_id": "6182bde8-ee3e-4bd5-935e-e56507e0f809",
  "network_transaction_ref": "awqcB1rPDuJIm4yKOQbqJUj5MvpdcH6E",
  "customer_id": "8e64c3c2-f409-4e0b-afb7-05cce88d26d7",
  "tenant_customer_ref": "01HG04B4NDBB7XT9JY6H1Y2B3A",
  "account_id": "5ce21f7b-7651-43ea-bf61-b1175f5acbbe",
  "tenant_account_ref": "FR12345678901",
  "provision_id": "f4e52b39-3664-48ce-844c-7a92772b1f2e",
  "provision_type": "customer_account_device",
  "device_id": "f4e52b39-3664-48ce-844c-7a92772b1f2e",
  "network_message_ref": "CZLIzgNfeyMCabcsXp3liJPgSVGyQypHI2B",
  "network_merchant_name": "Merchant123456",
  "network_merchant_id": "6000123456",
  "network_merchant_outlet_address": "Central, Singapore",
  "network_merchant_category_code": "1234",
  "network_merchant_country_code": "SG",
  "network_acquirer_id": "000003",
  "token_requestor_id": "50120834693",
  "auth_indicator": {
	"is_incremental_approval": false,
  },
  "amount": 200.0,
  "currency": "SGD",
  "billing_amount": 200.0,
  "billing_currency_code": "SGD",
  "billing_exchange_rate": 1.0,
  "settlement_amount": 200.0,
  "settlement_currency_code": "SGD",
  "settlement_exchange_rate": 1.0,
  "transaction_source": "terminal",
  "transaction_category": "other",
  "verification_data": {}
}
Response Example
{
  "tenant_reference_id": "31XXXX6723173606",
  "approved_amount": 200.0,
  "authorization_code": "8ABJ6S",
  "status": "approved",
  "reason": null
}
  • Perform your checks: customer balance, risk rules, merchant rules, etc.
  • Return a clear decision: approved/declined, plus a reason for declines.
  • Update ledgers: update your customer's balance where required.
  • Be idempotent: handle retries safely if Open Fabric resends the same request.

Scenarios where authorization amount can change​

Partial approval

If auth_indicator.is_partial_approval is true, you may choose to approve a partial amount by decreasing approved_amount in the response. This can be useful if the customer's balance is not sufficient for the full amount.

Common use cases are fuel pump pre-authorizations, partial payments via gift cards, or high value amounts where merchants allow multiple cards to be charged for a single purchase.

Incremental authorizations

Merchants may increase the authorization amount by sending an additional pre-authorization request referring to a previously approved pre-authorization.

  • If you approve this request, increase the hold on the customer's balance.
  • If you decline this request, you decline the increase, but the original hold/authorization is still valid.

Common use cases are hospitality (additional charges such as room service), car rentals (tolls, fuel or late fees) or online groceries/deliveries (basket modifications, weight-based adjustments or tipping).

note

An incremental authorization can also be used by merchants to extend the validity of the pre-authorization by another 30 days.

Mismatched amounts in clearing file

There are edge cases where the amount in the clearing file is either higher or lower than the amount in the authorization.

  • In the case where the amount is less than the original amount and the clearing file indicates this is a final authorization (final_auth, final_auth_partial or pre_auth_final), you are required to refund the customer the difference.
  • In the case where the amount is more than the original amount, or where you receive an unlinked authorization in the clearing file, you are required to deduct the additional amount. In such cases, you may raise a chargeback to request a refund (is_potential_chargeback in the record will be true).
note

There are specific cases (for example, transit operators) where there may be a pre-existing agreement allowing the merchant or operator to instruct increased amounts to be cleared and settled.