API Documentation

API Documentation

Triggers and APIs | Trigger Point Execution


Triggers and APIs

Trigger Processing | List of Triggers and Application Ideas Using Them | Notification Mechanism and Triggers | Trigger Point Application Selection | Payment Flow | Multiple Commerce Apps Launched


Trigger Processing
The Commerce Platform supports use cases that integrate Terminal Commerce application flows (such as Loyalty, Coupons, etc.) with payment flows implemented by payment applications. This is accomplished with a triggering mechanism that launches Terminal Commerce applications on pre-defined trigger points indicated by the payment application.

The Application Controller is in charge of handling the trigger evaluation and launches Terminal Commerce applications that have registered for the trigger point in question. The payment application does not necessarily know which Terminal Commerce application will be triggered.  


List of Triggers and Application Ideas Using Them
It should be noted that not all payment applications will support or 'trigger' each triggering event within its payment flow. There is not a prescribed order to the triggers, as the payment flows for every payment application may differ from region to region or environmentally. Example: Loyalty interaction and idle times may differ in petro when compared to general retail or restaurant.
 

  Trigger App Use Case App ideas using the Trigger
1 CP_SYSTEM_NOTIFIES_TRANSACTION_            STARTED Know that a transaction started WelcomeApp
Metrics/Analytics Service
2 CP_SYSTEM_REQUESTS_BASKET_             ADJUSTMENT Edit Basket Line Details AddWarranty
Discount for specific product
3 CP_SYSTEM_NOTIFIES_BASKET_FINALIZED Know the line items of finalized basket PersonalizationApp: Building purchase history
Metrics/Analytics Service
4 CP_SYSTEM_REQUESTS_LOYALTY Provide and Use Loyalty Loyalty
Points: use and collect
5 CP_SYSTEM_REQUESTS_AMOUNT_           ADJUSTMENT Adjusts final amount Pennies app:   Rounds up the final amount. e.g.: amount of $8.19 is rounded up to $9.00
TipApp
6 CP_SYSTEM_NOTIFIES_AMOUNT_FINALIZED Know intermediate and finalized amount GoodSamaritan app knows how much adjustments/discounts you got, and gratuity you gave.
Charity: Keeps track of you charity for tax purposes
7 CP_SYSTEM_REQUESTS_ALT_PAYMENT Provide alternate payment methods PayPal app 
Bitcoin app
8 CP_SYSTEM_NOTIFIES_CARD_PRESENTED Action based on Card Info CardLinkedOffers (call API CP_GET_ENCRYPTED_CARD to get PAN info)
Personalization app (name of card holder using CP_GET_CARD_DATA)
9 CP_SYSTEM_NOTIFIES_CARD_BIN_RECEIVED Action based on Card info

Restricted to apps which match the bin range, prevents CardBrand-A being able to see CardBrand-B swiped BINs
CardLinkedOffers (call API CP_GET_ENCRYPTED_CARD to get PAN info)
Personalization app (name of card holder using CP_GET_CARD_DATA)
10 CP_SYSTEM_REQUESTS_CARD_PAYMENT_ AMOUNT_ADJUSTMENT Amount Adjustment for certain types of cards or currency conversion DCC (Dynamic Currency Conversion)
11 CP_SYSTEM_NOTIFIES_AUTHORIZATION_   COMPLETED Know when authorization passed and why failure occurred NewCardOffer,
IncreaseCreditLimit , if credit is crossed
12 CP_SYSTEM_NOTIFIES_PAYMENT_               COMPLETED Do actions knowing that Payment is completed, with info on payment Offer for 20% off next purchase in next 30 days
SplitTender
13 CP_SYSTEM_NOTIFIES_TRANSACTION_                ENDED Know when transaction is ended Survey App
PrintReceipt
14 CP_SYSTEM_NOTIFIES_IDLE_ENTERED Control the screen and device in between transactions Advertisements,, "Buy One, Get One Free"
Background services, Connection to externals, time consuming activities
15 CP_SYSTEM_NOTIFIES_MANUAL_LAUNCH_    SELECTED Initiate a transaction from Desktop Ez Top Up (call APIs CP_START_SALE, and CP_VOID_SALE)
Sale
Configuration



List of APIs and Application Ideas Using Them
APIs are originated by the Terminal Commerce Applications, and response is received for them. The following table lists the APIs and app ideas that use them:
 

  APIs App Use Case App ideas using the APIs
1 CP_APP_REQUESTS_ENCRYPTED_CARD Get PAN info from card

Behavior is listed at Getting Card Data API
PayWithPoints,
CardLinkedOffer
2 CP_APP_REQUESTS_CARD_DATA Get Name, last 4 digits of card

Behavior is listed at Getting Card Data API
PersonalizationApp using customer purchase patterns
3 CP_APP_REQUESTS_PRINT Print HTML content Voucher/Coupon, independent
4 CP_APP_REQUESTS_APPEND_RECEIPT  Print HTML content at the bottom of the receipt LoyaltyApp appending info to end of payment receipt
5 CP_APP_REQUESTS_PAYMENT_TRANSACTION Initiate or void a previous payment transaction EzTopUp App 
6 CP_APP_REQUESTS_SEND_DATA_TO_POS Free form payload to POS through the Payment App. Send VAS data sent and selected by user to POS for updating bucket or any other POS processing.  Google's SmartTap 
Apple's VAS App 


 
Notification Mechanism and Triggers
A general notification mechanism is used for communication between the Payment and Terminal Commerce Applications. Notifications are messages sent to the receivers with either a distinct name or with an alias for a single or broadcast target. Notifications carry a unique notification ID that equals the trigger ID along with the notification parameter.

The application controller observes notifications and launches Terminal Commerce Applications that have registered for this notification/trigger ID.

Terminal Commerce Applications must subscribe to notification/trigger IDs. Subscription is defined in the application manifest file. Terminal Commerce Applications will be launched by application controller if a matching notification ID is defined in the manifest file. The Commerce Applications SDK guides the developer on setting trigger points for the Terminal Commerce Application. 
On launch of the Terminal Commerce Application, the notification parameters are provided as part of the ARGV array.

When the Terminal Commerce Applications run, they can use the pre-defined JavaScript APIs to send notifications and requests to the payment terminal. At the exit, Terminal Commerce Applications will send back processing results to the payment application using a notification.  

Trigger Point Application Selection
Terminal Commerce Application can register with one or multiple trigger points. Registration data is provided with the application manifest file. Additionally, a global trigger point configuration will define trigger point behavior such as launch policy and display layout (resolution) used.

Terminal Commerce Applications can be launched manually or automatically. In a manual launch, a set of registered Terminal Commerce Apps will be offered for manual selection. In an auto launch, the matching application is launched directly. The Terminal Commerce Application will be started based on the above information according to the following rules:

 

  • If no application can be found for the trigger point, an error code will be returned immediately to the calling application  
  • If one or multiple applications have registered with a manual launch for the trigger point, a user selection menu with available Terminal Commerce Applications will be shown
  • If one or multiple applications have registered with an auto launch for the same trigger point, apps will be run on a specified priority order. If multiple apps are set at the same priority order, apps are run one after another in a random order.
  • If different applications have registered with manual and auto launch for the same trigger point, the manual policy takes precedence
Once an appropriate application has been determined, the display layout will be adjusted and the Terminal Commerce Application will be launched.


Payment Flow
The triggers described in this section are fired by the Payment Application. Not all payment applications will support or 'trigger' each triggering event within its payment flow. There is not a prescribed order to the triggers, as the payment flows for every payment application may differ from region to region or environmentally. Example: Loyalty interaction and idle times may differ in petro when compared to general retail or restaurant.

Multiple Commerce Apps Launched
When the Payment Application requests the list of triggers for all Terminal Commerce Apps, it will receive a list of triggers and priorities linked to each trigger. When a trigger is registered by several Terminal Commerce Applications, the Payment Application must launch the trigger for each Terminal Commerce Application in sequence according to priority (lowest value first).

If the Terminal Commerce App is a service on this trigger, the Payment Application fires trigger to this Terminal Commerce Application without waiting for the Terminal Commerce Application to exit. If the Commerce App is an application on this trigger, Payment Application fires trigger to this Terminal Commerce Application and will wait for completion of the Terminal Commerce Application before launching the next Terminal Commerce Application in line.



 



 

Note that for split or declined payments the triggers starting from the CP_SYSTEM_NOTIFIES_AMOUNT_FINALIZED will be launched multiple times within the same payment flow. Application developers must take this into account, for example to avoid their app unnecessarily to be launched multiple times during the same transaction flow.


Trigger Point Execution

Input Data Handling | Services | Trigger Point Completion | Triggers and Contactless Technology | Payment Solution Types | Triggers within the Payment Process, Contact | Triggers within the Payment Process, Contactless

Input Data Handling
Terminal Commerce Applications will be provided on each invocation with a map of key/value pairs that represent the input data for processing passed by the payment application.

Services (or Headless Applications)
Commerce Platform services don’t have a user interface. Services are triggered the same way as any other Terminal Commerce Application, but make sure to not overwrite or occupy any space on the screen.
Services are similar to Applications; but, they have following restrictions:
  • won’t interact with the user
  • won’t use services of the payment applications
  • won’t use the printer
  • don’t need to pause between trigger points while payment application is processing
As the execution of services can span several trigger points, an end trigger is expected to be defined in the application manifest.
 
Trigger Point Completion
A responding Terminal Commerce Application can “end” in different ways:
  1. Exit on its own with or without providing result (data) back
  2. Be explicitly terminated by the native calling application
  3. For a service be terminated by the App Controller, because the specified stop end trigger or “CP_SYSTEM_NOTIFIES_IDLE_ENTERED” trigger has been reached
Runtime will not enforce timeout for Terminal Commerce Applications; any application can decide to exit at any point in time. This could be based on a timer or based on the client or the server’s business logic.

Similarly, native applications can implement timeout for trigger processing and use the provided function to cancel or terminate the trigger processing.

Triggers and Contactless Technology
Due to contactless technology, there is no time for triggers to be fired during the period the payment card is in the field. This is why the triggers for contactless are "delayed in time". However, the payment application still fires all the same triggers as in the contact mode except for one:

"CP_SYSTEM_REQUESTS_CARD_PAYMENT_AMOUNT_ADJUSTMENT".

This trigger is never fired for a contactless transaction as cryptogram has already been generated by the contactless card.
  
Triggers 
Triggers are originated from the Payment App to the Terminal Commerce Apps to communicate information on the flow. They fall in two main buckets: 
  1. Notifications: No response is expected by Payment App
  2. Request/Response: Response is expected by Payment App 

Payment Solution Types
From the perspective of Terminal Commerce Applications, the dialog formed by triggers and APIs is performed with Payment Applications. However, there are many different payment applications and solutions: standalone, integrated, semi-integrated, attended, unattended, etc. It is the responsibility of the payment applications that is CP-enabled to provide the best and most coherent trigger implementation for Commerce Platforms. 

Typically, whether there is an ECR connected to the terminal or not, the payment application is responsible to provide the adequate behavior in terms of triggers.

In order to provide a uniform and global interface for Terminal Commerce Applications, all the triggers are implemented by payment applications. For all the functions it is able to perform, there remain some specific cases.

The best known example is where the payment solution has no knowledge of basket information, in this case “CP_SYSTEM_REQUEST_BASKET_ADJUSTMENT” and “CP_SYSTEM_NOTIFIES_BASKET_FINALIZED” is not implemented.

All implemented triggers will generally be fired by payment application. However, as an example, if a transaction is aborted, some triggers may be skipped.

Triggers within the Payment Process, Contact





Triggers within the Payment Process, Contactless



Due to the contactless technology, there is no time for triggers to be fired during the period the payment card is in the field. This is why the triggers for contactless are "delayed in time" as shown below.

However, the payment application still fires all the same triggers as in the contact mode except one: "CP_SYSTEM_REQUESTS_AMOUNT_ADJUSTMENT".

This trigger is never fired for a contactless transaction as cryptogram has already been generated by the contactless card.


Below is a table showing when the Terminal Commerce Application can call CP_APP_REQUESTS_APPEND_RECEIPT and when payment application can print the different receipts parts: