Balance and status inquiry

Use a nexo Acceptor Authorization Request to retrieve the remaining balance and status of a preauthorization. The request references the original Gateway order; it does not authorize or capture an additional amount.

The examples below show the fields relevant to the balance inquiry. Standard environment, header, and security elements required by the nexo message are omitted for readability.

Normal balance inquiry

A normal balance inquiry retrieves the remaining amount of an active preauthorization. It is approved only when the referenced preauthorization is still valid and its remaining balance is greater than zero.

Request fields

m = mandatory

Request example

The following fragment is taken from a caaa.001.001.06 Acceptor Authorization Request:

<Hdr>
    <MsgFctn>AUTQ</MsgFctn>
    <PrtcolVrsn>6.0</PrtcolVrsn>
    <!-- Other required header fields -->
</Hdr>
<AuthstnReq>
    <Envt>
        <!-- Acquirer, merchant and POI data -->
        <PmtCntxt>
            <CrdhldrPres>false</CrdhldrPres>
            <CardDataNtryMd>PHYS</CardDataNtryMd>
        </PmtCntxt>
    </Envt>
    <Tx>
        <TxCaptr>false</TxCaptr>
        <TxTp>BALC</TxTp>
        <SaleRefId>71581515684</SaleRefId>
        <TxId>
            <TxDtTm>2026-06-12T07:07:57.9+00:00</TxDtTm>
            <TxRef>999</TxRef>
        </TxId>
        <TxDtls>
            <Ccy>EUR</Ccy>
            <TtlAmt>0.00</TtlAmt>
            <AmtQlfr>ACTL</AmtQlfr>
        </TxDtls>
    </Tx>
</AuthstnReq>

Successful response

The Gateway returns the remaining authorized balance in TxRspn/Bal/Amt. When available, Tx/TxDtls/VldtyDt contains the expiration date of the preauthorization.

m = mandatory, c = conditional

Response example

The following fragment is taken from a caaa.002.001.06 Acceptor Authorization Response:

<AuthstnRspn>
    <Tx>
        <TxId>
            <TxDtTm>2026-06-12T07:07:57.9+00:00</TxDtTm>
            <TxRef>999</TxRef>
        </TxId>
        <RcptTxId>71581515684</RcptTxId>
        <TxDtls>
            <Ccy>EUR</Ccy>
            <TtlAmt>0.00</TtlAmt>
            <VldtyDt>2026-06-26+02:00</VldtyDt>
        </TxDtls>
    </Tx>
    <TxRspn>
        <AuthstnRslt>
            <RspnToAuthstn>
                <Rspn>APPR</Rspn>
                <RspnRsn>00:Function performed error-free</RspnRsn>
            </RspnToAuthstn>
            <CmpltnReqrd>false</CmpltnReqrd>
        </AuthstnRslt>
        <Bal>
            <Amt Ccy="EUR">1.00</Amt>
        </Bal>
    </TxRspn>
</AuthstnRspn>

In this example, the preauthorization remains valid until 26 June 2026 and has a remaining balance of 1.00 EUR.

Extended balance and status inquiry

An extended inquiry can also retrieve status information when the referenced preauthorization has already been completed or has expired. Add the following value to the normal balance inquiry:

Request example

<Tx>
    <TxCaptr>false</TxCaptr>
    <TxTp>BALC</TxTp>
    <SaleRefId>1786584455</SaleRefId>
    <TxId>
        <TxDtTm>2026-06-12T08:38:33.6+01:00</TxDtTm>
        <TxRef>999</TxRef>
    </TxId>
    <TxDtls>
        <Ccy>SEK</Ccy>
        <TtlAmt>0.00</TtlAmt>
        <AmtQlfr>ACTL</AmtQlfr>
    </TxDtls>
    <AddtlTxData>/SuccessOnCompletedPreauth</AddtlTxData>
</Tx>

Additional response information

For an extended inquiry, TxRspn/AuthstnRslt/RspnToAuthstn/AddtlRspnInf contains semicolon-separated key-value pairs.

m = mandatory for a successful extended response, c = conditional

Last transaction type values

LastTxType describes the latest successful transaction. A later declined or otherwise unsuccessful attempt does not replace this value.

Response example

<AuthstnRspn>
    <Tx>
        <TxId>
            <TxDtTm>2026-06-12T08:38:33.6+01:00</TxDtTm>
            <TxRef>999</TxRef>
        </TxId>
        <RcptTxId>1786584455</RcptTxId>
        <TxDtls>
            <Ccy>SEK</Ccy>
            <TtlAmt>0.00</TtlAmt>
        </TxDtls>
    </Tx>
    <TxRspn>
        <AuthstnRslt>
            <RspnToAuthstn>
                <Rspn>APPR</Rspn>
                <RspnRsn>00:Function performed error-free</RspnRsn>
                <AddtlRspnInf>LastTxType=CRDP;PEM=ECTL;ReturnedAmount=0.00;TotalAmount=21.00</AddtlRspnInf>
            </RspnToAuthstn>
            <CmpltnReqrd>false</CmpltnReqrd>
        </AuthstnRslt>
        <Bal>
            <Amt Ccy="SEK">0.00</Amt>
        </Bal>
    </TxRspn>
</AuthstnRspn>

In this example:

• LastTxType=CRDP indicates that the latest successful transaction was a Sale.
• PEM=ECTL indicates contactless card entry.
• TotalAmount=21.00 is the amount completed by Sale or PostAuth transactions.
• ReturnedAmount=0.00 indicates that no Credit or Return amount was processed.
• Bal/Amt=0.00 indicates that no preauthorization balance remains.

How the balance is calculated

The Gateway evaluates the successful transactions associated with the referenced order:

• An authorized preauthorization contributes to the remaining balance.
• Captured or settled Sale and PostAuth transactions contribute to TotalAmount.
• Captured or settled Credit and Return transactions contribute to ReturnedAmount.
• If a completed or returned amount is greater than zero, the returned balance is 0.00.
• Declined, voided, waiting, or otherwise unsuccessful transactions do not contribute to these amounts.

The values in AddtlRspnInf do not carry separate currency attributes. Interpret them using the transaction currency returned in the response, unless the integration uses a DCC-specific payment-currency configuration.

Response identifier behavior

Tx/TxId/TxDtTm and Tx/TxId/TxRef in the response are copied from the balance-inquiry request. They are not replaced with the identifiers of the referenced preauthorization, including when /SuccessOnCompletedPreauth is used.

Do not use the response TxId as the identifier of the original preauthorization. Use the returned RcptTxId and/or SaleRefId, according to the configured response profile, to correlate the referenced Gateway order.

Result summary