Transaction notifications

You can register for, and receive, transaction notifications. For instance, if your app is interested in certain activities that the UICC Secure Element performs, such as payment transactions, it can register to receive transaction notifications.

All applications that are registered for interest in a given application identifier (AID) receive a transaction notification in the background if a transaction occurs that is associated with that AID.

Register for transaction notifications

Transaction notifications are delivered using the invocation framework. To subscribe to transaction notifications, you need to specify a target in your bar-descriptor.xml file:

<invoke-target id="my.transaction.listener">
    <entry-point>1</entry-point>
    <type>APPLICATION</type> 
    <filter>
        <action>bb.action.NOTIFY</action>
        <mime-type>application/vnd.bb.nfc_transaction
        </mime-type>
        <property var="uris" 
            value="aid://SIM/6e.66.63.74.65.73.74.30.31/"/>
    </filter> 
</invoke-target>

Transaction notifications are always invoked using an action of bb.action.NOTIFY and a MIME-type of application/vnd.bb.nfc_transaction. Use the uris property to specify the URI or URIs your app is interested in receiving. The format of the URI is:

aid://[SE-type]/[AID]/

where:

SE-type is "SIM" (note that this is case sensitive)
AID is the AID of interest, in dotted notation, using lower case letters for hex values. Also, all octets in the dotted notation must be two hex digits long (e.g., a0.04.12). The invocation framework uses prefix-matching for URIs, so a uris value of aid://SIM/a0.11.22.33.44 would receive notifications for all transactions on the UICC Secure Element on AIDs that start with a0.11.22.33.44.
Note: In order to receive a transaction notification for a given transaction, an application must pass an ACF check for all of the AIDs involved in the transaction.

When an app is sent a transaction notification, it is invoked and sent to the background. From the background, the app may launch dialogs or toasts, but if it needs to do more than that, the app may bring itself to the foreground by calling nfc_se_transaction_foreground_application():

    
#include <nfc/nfc_se_transaction.h>
...

void MyApp::slotInvokedReceived(const bb::system::InvokeRequest &request) {
    ...

    nfc_result_t fgResult = nfc_se_transaction_foreground_application();
}

The code above causes MyApp to be invoked again in the foreground, with a MIME type of application/vnd.bb.nfc_foreground and with no data. This method may be called only within 30 seconds of receiving a transaction notification. You can exit the application. We suggest that you exit the application if there is no reason for it to continue running.

If multiple applications are listening for transaction events for the same AID, they will all be launched when an appropriate event occurs, assuming they all pass the appropriate access control file checks. If the device is password-locked when an app requests to be brought to the foreground, the device prompts the user to unlock the device, and then brings the app to the foreground. If multiple apps request to be brought to the foreground while the device is locked, only the most recent app that requests to be brought to the foreground is brought to the foreground.

Parsing a transaction notification

An app can use the SE transaction API functions to parse the transaction notification as shown in the following code sample.

Note: You must dynamically link to the libnfc.so shared object to use the NFC API.

#include <nfc_se_transaction.h>
               
nfc_se_transaction_t* transaction = nfc_se_parse_transaction(jsonTransactionData);
               
if(transaction != NULL) {
    int protocol = nfc_se_transaction_get_protocol(transaction);
    secure_element_id_type_t seType = nfc_se_transaction_get_se_type(transaction);
    int aidCount = nfc_se_transaction_get_number_of_aids(transaction);
               
    for(int i = 0; i < aidCount; i++) {
        const uint8_t *aid;
        int aidLength;
        nfc_se_transaction_get_aid(transaction, i, &aid, &aidLength);
        // use the AID as needed
        // ...
    }
               
    int eventDataLength = nfc_se_transaction_get_event_data_length(transaction);
    if(eventDataLength != 0) {
        uint8_t* eventData = nfc_se_transaction_get_event_data(transaction);
    }
}