SCA Functional Specification

Triggers

Last updated: 04-Dec-2024
Download as PDF

Triggers are payment application initiated and are of two types.

  • Notification, which is one way, means fired by the payment application.
    Example: Payment Application sends notification.
    CP_SYSTEM_NOTIFIES_<TRANSACTION_STARTED>
  • Request, which is two-way, means payment application sends a request message, and expects to receive response.
    Example: Payment Application sends request, and expects to response back.
    CP_SYSTEM_REQUESTS_<BASKET_ADJUSTMENT>
    CP_SYSTEM_RECEIVES_<BASKET_ADJUSTMENT>
Examples of CP Application Request and Response format.
CP_APP_REQUESTS_<ENCRYPTED_CARD>
CP_APP_RECEIVES_<ENCRYPTED_CARD>

The following table describes the list of Triggers and it invoke points in SCA application.

Trigger Description Invoke Points in SCA Application SCI Fields Information
CP_SYSTEM_NOTIFIES_TRANSACTION_STARTED This is to indicate the start of a transaction. This trigger is invoked up on receiving SESSION START command from POS.  
CP_SYSTEM_REQUESTS_BASKET_ADJUSTMENT The pre-adjusted basket may be responded to by the Commerce Application by explicit offer format against the basket line details. This will be the case when the Commerce Application is basket aware and can quickly adjudicate the basket. This trigger is invoked on receiving LINE_ITEM_END command from POS and if the basket state is open. CP Application sends the offer details in response to this trigger, the same will be passed on to POS (On POS IP and POS PORT sent in start session command) and to the LINE_ITEM_END command response. Refer to LINE_ITEM_END Response, where the mentioned fields are sent which are received from commerce application. Payment application acts as a passthrough with respect to fields that has been received from commerce application. OFFER_LIST field can contain multiple OFFER fields. Refer to Line Item End command for more details.
CP_SYSTEM_NOTIFIES_BASKET_FINALIZED Notifies the line items of finalized basket. This trigger is invoked on receiving the payment command and if line items are present in current session. This trigger is also invoked up on receiving LINE_ITEM_END for the second time from POS and if the basket state is basket adjusted.  
CP_SYSTEM_REQUESTS_LOYALTY This trigger occurs when the Commerce Application wants to provide and use Loyalty for the current transaction. This request trigger is invoked as first step in the transaction flow up on receiving the payment request (like, CAPTURE) from the POS. The transaction is halted if loyalty details are received from commerce application and those details will be sent to POS (On POS IP and POS PORT sent in start session command) and to the payment command response. NOTE: POS needs to re-initiate the transaction after applying the loyalty details on its end. Refer to Payment Response – LOYALTY, where the mentioned fields are sent which are received from commerce application. Payment application acts as a passthrough with respect to fields that’s been received from commerce application.
CP_SYSTEM_REQUESTS_AMOUNT_ADJUSTMENT This is for Commerce Application to adjust the final amount. This permits the Commerce Application to adjust the final either by an amount or by a percentage. As part of the payment transaction (like, Sale) flow, this trigger is invoked after prompting for configured amounts like TIP, Split tender etc. If there is any adjustment to the amount by commerce application, then payment application applies the adjustment to the transaction amount and continues with the transaction flow. In the payment response, adjusted amount details are shared to the POS. In the payment response, the mentioned fields are sent which are received from commerce application to indicate that amount is adjusted. The Unsolicited response on the POS_IP, POS_PORT (that has been sent in the START SESSION) is sent to POS. Refer to Unsolicited Response below for more details.
CP_SYSTEM_NOTIFIES_AMOUNT_FINALIZED Allows Commerce Application to know intermediate and finalized amount of the transaction. As part of the payment transaction (like, Sale) flow, this trigger is invoked after prompting for configured amounts like TIP, Split tender etc. and after the AMOUNT_ADJUSTMENT trigger processing.  
CP_SYSTEM_REQUESTS_ALT_PAYMENT Provides alternate payment methods to the users. During payment transaction (like, Sale) flow, this trigger is invoked when one of the alternate payment label on the card read screen has been selected by cardholder or PAYMENT_TYPE field indicates the APM values like ALIPAY, WECHAT, KLARNA etc. Refer to APM Integration Details for more information. NOTE: It is required to call CP_APP_REQUESTS_APPEND_RECEIPT API during processing of Alternate Payment Trigger to pass the details that need to be printed on the receipt with respect to current APM transaction and also to indicate the status of the transaction.
CP_SYSTEM_NOTIFIES_CARD_PRESENTED Access to the card data on-demand and action based on card info by the commerce application. During payment transaction (like, Sale) flow, this trigger is invoked after the card is presented by the cardholder and application validates the card data.  
CP_SYSTEM_NOTIFIES_CARD_BIN_RECEIVED Access to the card data on-demand and action based on card bin by the commerce application. During payment transaction (like, Sale) flow, this trigger is invoked after the CARD_PRESENTED trigger processing.  
CP_SYSTEM_REQUESTS_CARD_PAYMENT_AMOUNT_ADJUSTMENT Amount Adjustment for certain types of cards or currency conversion. During payment transaction (like, Sale) flow, after capturing card details and validating the same, application prompts for cash back amount and surcharge amount based on eligibility/configuration, post to that CP_SYSTEM_REQUESTS_PAYMENT_AMOUNT_ADJUSTMENT trigger is invoked. If there is any amount adjustment here same fields that are mentioned in AMOUNT_ADJUSTMENT row applies here.
CP_SYSTEM_NOTIFIES_AUTHORIZATION_COMPLETED Notifies Commerce Application about the completion of authorization and its status. During payment transaction (like, Sale) flow, this trigger is invoked after receiving and processing the response from the payment processor/host.  
CP_SYSTEM_NOTIFIES_PAYMENT_COMPLETED Notifies for next actions after the Payment is completed, with information on payment. During payment transaction (like, Sale) flow, this trigger is invoked after framing receipt data and before sending the payment response to POS.  
CP_SYSTEM_NOTIFIES_TRANSACTION_ENDED Notifies when transaction is ended. This trigger is invoked up on receiving SESSION FINISH command from POS. In case of APM transaction, this trigger is invoked as a last step of payment transaction flow before sending the response back to POS and after PAYMENT_COMPLETED trigger processing.  
CP_SYSTEM_NOTIFIES_IDLE_ENTERED This allows the Commerce Applications to control the screen and devices in between transactions when payment application reaches the idle screen when application first starts up and each time after a transaction completes. This trigger is invoked whenever application goes to idle screen after waiting for configured cpidlewait time during start up and each time after processing the commands like FINISH SESSION, LANE CLOSED and DEVICE COMMANDS.  
CP_SYSTEM_NOTIFIES_MANUAL_LAUNCH_SELECTED Initiates a transaction from MAC screen. This trigger is invoked when POS send CPLAUNCH device command or when CPLAUNCH menu option is selected.  

Sample Response

Following is an example of LINE_ITEM_END Response.

<OFFER_LIST>
<OFFER>
  <OFFER_ID>7836938109</OFFER_ID>
  <PROGRAM_ID>MCD-1601</PROGRAM_ID>
  <OFFER_TYPE>OTHER_COUPON</OFFER_TYPE>
  <OFFER_DESCRIPTION>Get 20% off your Purchase</OFFER_DESCRIPTION>
  <OFFER_REFUNDABLE>FALSE</OFFER_REFUNDABLE>
  <OFFER_COMBINABLE>TRUE</OFFER_COMBINABLE>
  <MERCHANT_OFFER_CODE>931343</MERCHANT_OFFER_CODE>
  <OFFER_PERCENT_DISCOUNT>0.20</OFFER_PERCENT_DISCOUNT>
  <OFFER_DOLLAR_DISCOUNT />
  <PRODUCT_CODE>ZM9475L</PRODUCT_CODE>
  <ASSOCIATED_PRODUCT_CODE>null</ASSOCIATED_PRODUCT_CODE>
  <SPECIAL_PRODUCT_OFFER>null</SPECIAL_PRODUCT_OFFER>
  <PUBLISHER>Valid0</PUBLISHER>
  <PUBLISHER_ID>Valid0-560090096095</PUBLISHER_ID>
  <BARCODE_CONTENT />
  <BARCODE_TYPE />
  <BARCODE_X_DIMENSION>-453.92</BARCODE_X_DIMENSION>
  <BARCODE_ROWS>43448</BARCODE_ROWS>
  <BARCODE_COLUMNS>64747</BARCODE_COLUMNS>
  <BARCODE_ERROR_CORRECTION_LEVEL />
</OFFER>
    </OFFER_LIST>

    DONATION_LIST field which can contain multiple DONATION.

    <DONATION_LIST>
    <DONATION>
            <DONATION_AMOUNT>1.00</DONATION_AMOUNT>
            <DONATION_DESCRIPTION>March Of Dimes</DONATION_DESCRIPTION>
            <PUBLISHER>Valid0</PUBLISHER>
            <PUBLISHER_ID>Valid0-560090096095</PUBLISHER_ID>
    </DONATION>
    </DONATION_LIST>

Following is an example of Payment Response – LOYALTY.

LOYALTY_IDENTIFIERS_LIST which contains list of LOYALTY_IDENTIFIER fields.

    <LOYALTY_IDENTIFIERS_LIST>
<LOYALTY_IDENTIFIER>
  <PUBLISHER>vwallet</PUBLISHER>
  <PUBLISHER_ID>878343322</PUBLISHER_ID>
  <PROGRAM_ID>JK223123</PROGRAM_ID>
  <CUSTOMER_PHONE_NUMBER>678-555-1212</CUSTOMER_PHONE_NUMBER>
  <CUSTOMER_NAME>John Doe</CUSTOMER_NAME>
  <CUSTOMER_EMAIL>jd@redmail.com</CUSTOMER_EMAIL>
  <CUSTOMER_LOYALTY_IDS />
  <LOYALTY_POINTS_BALANCE>30000</LOYALTY_POINTS_BALANCE>
  <LOYALTY_PAYLOAD>null</LOYALTY_PAYLOAD>
  <CONSUMER_ID>IP6304034</CONSUMER_ID>
</LOYALTY_IDENTIFIER>
    </LOYALTY_IDENTIFIERS_LIST>

    OFFER_LIST which can contains list of OFFER fields

    <OFFER_LIST>
<OFFER>
  <OFFER_ID>7836938109</OFFER_ID>
  <PROGRAM_ID>MCD-1601</PROGRAM_ID>
  <OFFER_TYPE>OTHER_COUPON</OFFER_TYPE>
  <OFFER_DESCRIPTION>Get 20% off your Purchase</OFFER_DESCRIPTION>
  <OFFER_REFUNDABLE>FALSE</OFFER_REFUNDABLE>
  <OFFER_COMBINABLE>TRUE</OFFER_COMBINABLE>
  <MERCHANT_OFFER_CODE>931343</MERCHANT_OFFER_CODE>
  <OFFER_PERCENT_DISCOUNT>0.20</OFFER_PERCENT_DISCOUNT>
  <OFFER_DOLLAR_DISCOUNT />
  <PRODUCT_CODE>ZM9475L</PRODUCT_CODE>
  <ASSOCIATED_PRODUCT_CODE>null</ASSOCIATED_PRODUCT_CODE>
  <SPECIAL_PRODUCT_OFFER>null</SPECIAL_PRODUCT_OFFER>
  <PUBLISHER>vwallet</PUBLISHER>
  <PUBLISHER_ID>878343322</PUBLISHER_ID>
  <BARCODE_CONTENT />
  <BARCODE_TYPE />
  <BARCODE_X_DIMENSION>-453.92</BARCODE_X_DIMENSION>
  <BARCODE_ROWS>43448</BARCODE_ROWS>
  <BARCODE_COLUMNS>64747</BARCODE_COLUMNS>
  <BARCODE_ERROR_CORRECTION_LEVEL />
</OFFER>
    </OFFER_LIST>

Following is an example of Unsolicited Response.

<RESPONSE>
    <PUBLISHER_ID>Valid0-560090096095</PUBLISHER_ID>
    <ADJUSTMENT_LIST>
            <ADJUSTMENT>
           <ADJUSTMENT_AMOUNT>0.81</ADJUSTMENT_AMOUNT>
            <ADJUSTMENT_DESCRIPTION />
            <PUBLISHER>Valid0</PUBLISHER>
            <PUBLISHER_ID>Valid0-560090096095</PUBLISHER_ID>
            </ADJUSTMENT>
    </ADJUSTMENT_LIST>
    </RESPONSE>

In the payment response, following fields are included:

<ADJUSTED_AMOUNT>1.62</ADJUSTED_AMOUNT>
<INITIAL_AMOUNT>15.00</INITIAL_AMOUNT>

The ADJUSTED_AMOUNT field indicates the amount to adjust the original transaction amount. String amount formatting is applied, this can be positive or negative. If it is negative then this field contains minus(-) sign.

Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo