SCA Functional Specification

Integration with APMs

Last updated: 04-Dec-2024
Download as PDF

This section provides the details on integration with Alternate Payment Methods (APMs).
SCA supports the following list of APMs as Payment Types:

  • Alipay
  • Klarna
  • WeChat Pay
  • PayPal
  • Venmo
  • Affirm

Each APM Transaction should be triggered in a separate session. SCA does not support multiple APM transactions within the same session. This would cause the APM application to error out on the second transaction.

Ensure that the required Cloud Proxy configuration to indicate terminal to a specific instance of Greenbox, has been installed on the terminal. The cloud proxy by default directs to the production instance of Greenbox. For test environments it is required to install a separate configuration.

Required Fields for Capture/Credit Transactions

Capture/Credit Request

Field Rule Type Minimum Maximum Value(s) Description
PAYMENT_TYPE Conditional List    
  • Alipay
  • Klarna
  • WeChat Pay
  • PayPal
  • Venmo
  • Affirm
 Required when CTROUTD is sent. Optional otherwise. When present, will bypass the consumer payment selection screen. For APM transactions, payment types are mentioned in Values(s) column. Alipay/Klarna/WeChat/PayPal/Venmo - in case of APM

Capture/Credit Response

Field Type Value(s) Description
CTROUTD Numeric   CTROUTD is a sequence number for PAYMENT transactions (always enabled) that is generated per Client ID. Each Client ID has its own CTROUTD sequence counter. NOTE: In case of APM transaction, if this field is present, then order ID will be received from alternate payment method. For example, Alipay, Klarna, WeChat, PayPal, Venmo. CTROUTD field length is increased to 16 characters. Example: 1629760677599520
PAYMENT_TYPE Conditional   Type of payment (example, CREDIT, DEBIT, APM, CHECK). NOTE: PAYMENT_TYPE field will return value if this is entered in capture request. Example: PayPal

APM based Response Fields - (Conditional)

Field Type Value(s) Description
APM_TRAN Numeric Valid Value are 0 and 1 If this returns value 1 then indicates the current transaction is performed with alternate payment method.
CP_MERCH_RECEIPT_DATA Conditional   Additional field will be sent along with RECEIPT_DATA field.
CP_CUST_RECEIPT_DATA Conditional   Additional field will be sent along with RECEIPT_DATA field.

Following flow diagrams show the complete capture transactions for APMs.

Capture Transaction Flows (w/o Payment Type)

../_images/apm_capture_wo_paymenttype.png

Capture Transaction Flows (With Payment Type)

../_images/apm_capture_with_paymenttype.png

Sample Capture Request – Payment Type Not Specified

<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<COMMAND>CAPTURE</COMMAND>
<COUNTER>...</COUNTER>
<MAC>...</MAC>
<MAC_LABEL>...</MAC_LABEL>
<TRANS_AMOUNT>5.00</TRANS_AMOUNT>
</TRANSACTION>

Sample Capture Request – Payment Type Specified

<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<COMMAND>CAPTURE</COMMAND>
<PAYMENT_TYPE>PAYPAL</PAYMENT_TYPE>
<COUNTER>...</COUNTER>
<MAC>...</MAC>
<MAC_LABEL>...</MAC_LABEL>
<TRANS_AMOUNT>5.00</TRANS_AMOUNT>
</TRANSACTION>

Sample Capture Response – Approved

<RESPONSE>
<APPROVED_AMOUNT>1000.00</APPROVED_AMOUNT>
<AUTH_CODE>1423261445929360</AUTH_CODE>
<APM_TRAN>1</APM_TRAN>
<CTROUTD>1423261445929360</CTROUTD>
<INVOICE>2</INVOICE>
<MERCHID>RCTST0000042337</MERCHID>
<PAYMENT_TYPE>PAYPAL</PAYMENT_TYPE>
<RESPONSE_TEXT>APPROVED</RESPONSE_TEXT>
<RESULT>APPROVED</RESULT>
<RESULT_CODE>5</RESULT_CODE>
<TERMID>00000004</TERMID>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TRAINING_MODE>OFF</TRAINING_MODE>
<TRANS_AMOUNT>1000.00</TRANS_AMOUNT>
<RECEIPT_DATA>
        <RECEIPT>
                <TEXTLINE>              VERIFONE SCA              </TEXTLINE>
                <TEXTLINE>          11700 Great Oaks Way          </TEXTLINE>
                <TEXTLINE>               Suite 210                </TEXTLINE>
                <TEXTLINE>          Alpharetta, GA 30022          </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>07/04/20                        01:59:26</TEXTLINE>
                <TEXTLINE />
                <TEXTLINE>Merchant ID: RCTST0000042337            </TEXTLINE>
                <TEXTLINE>Term ID: 00000004                       </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>                  SALE                  </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>Appr Code: 1423261445929360             </TEXTLINE>
                <TEXTLINE>Payment Type: PAYPAL                    </TEXTLINE>
                <TEXTLINE>Invoice: 2                              </TEXTLINE>
                <TEXTLINE>Response: APPROVED                      </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE>Total:           USD   $        1,000.00</TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                  <TEXTLINE />
                <TEXTLINE>         NO SIGNATURE REQUIRED          </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>             Merchant Copy              </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
        </RECEIPT>
        <RECEIPT>
                <TEXTLINE>              VERIFONE SCA              </TEXTLINE>
                <TEXTLINE>          11700 Great Oaks Way          </TEXTLINE>
                <TEXTLINE>               Suite 210                </TEXTLINE>
                <TEXTLINE>          Alpharetta, GA 30022          </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>07/04/20                        01:59:27</TEXTLINE>
                <TEXTLINE />
                <TEXTLINE>Merchant ID: RCTST0000042337            </TEXTLINE>
                <TEXTLINE>Term ID: 00000004                       </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>                  SALE                  </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>Appr Code: 1423261445929360             </TEXTLINE>
                <TEXTLINE>Payment Type: PAYPAL                    </TEXTLINE>
                <TEXTLINE>Invoice: 2                              </TEXTLINE>
                <TEXTLINE>Response: APPROVED                      </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE>Total:           USD   $        1,000.00</TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE>               THANK YOU                </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE>             Customer Copy              </TEXTLINE>
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
                <TEXTLINE />
        </RECEIPT>
</RECEIPT_DATA>
<CP_MERCH_RECEIPT_DATA>
        <CPAPP_1>DATE:                      2020-07-04
                TIME:                           01:58:33
                TERMINAL ID:                    783257
                INVOICE:                        2
                PAYPAL Payment
                TRANSACTION ID:                             2020 0704 2200 1457 7505 0104 1299
                PARTNER TRANSACTION ID:         1423 2614 4592 9360
                AMOUNT (USD):                   1000.00
                SUCCESS
                NO SIGNATURE REQUIRED
        </CPAPP_1>
</CP_MERCH_RECEIPT_DATA>
<CP_CUST_RECEIPT_DATA>
        <CPAPP_1>DATE:                      2020-07-04
                TIME:                           01:58:33
                TERMINAL ID:                    783257
                INVOICE:                        2
                PAYPAL Payment
                TRANSACTION ID:                 2020 0704 2200 1457 7505 0104 1299
                PARTNER TRANSACTION ID:         1423 2614 4592 9360
                AMOUNT (USD):                   1000.00
                SUCCESS
                NO SIGNATURE REQUIRED
                I AGREE TO PAY THE ABOVE TOTAL AMOUNT
                ACCORDING TO PAYPAL AGREEMENT
        </CPAPP_1>
</CP_CUST_RECEIPT_DATA>
<COUNTER>3</COUNTER>
</RESPONSE>

Sample Capture Response – Declined

<RESPONSE>
<INVOICE>123456</INVOICE>
<MERCHID>RCTST0000042337</MERCHID>
<PAYMENT_TYPE>PAYPAL</PAYMENT_TYPE>
<APM_TRAN>1</APM_TRAN>
<RESPONSE_TEXT>DECLINED</RESPONSE_TEXT>
<RESULT>DECLINED</RESULT>
<RESULT_CODE>6</RESULT_CODE>
<TERMID>00000004</TERMID>
<TERMINATION_STATUS>FAILURE</TERMINATION_STATUS>
<TRAINING_MODE>OFF</TRAINING_MODE>
<TRANS_AMOUNT>11.00</TRANS_AMOUNT>
<COUNTER>6</COUNTER>
</RESPONSE>

In the payment response, APM_TRAN field with value 1 is added to indicate that current transaction is performed with alternate payment method.
<APM_TRAN>1</APM_TRAN>
<PAYMENT_TYPE>KLARNA</PAYMENT_TYPE>

APM Commerce application or any other commerce application can request the payment application to append the data to the receipt. Content is always added at the bottom of the receipt as part of the RECEIPT_DATA and content may be appended to either the merchant or cardholder receipt.
Along with the RECEIPT_DATA field, two additional fields with the receipt data will be sent in the SCI response by name CP_MERCH_RECEIPT_DATA and CP_CUST_RECEIPT_DATA.
If there are multiple CP apps that request for appending, CP_MERCH_RECEIPT_DATA/ CP_CUST_RECEIPT_DATA field will have list of CPAPP_1, CPAPP_2, … CPAPP_X

<CP_MERCH_RECEIPT_DATA>
        <CPAPP_1>DATE: 2020-05-30
                TIME: 17:00:04
                TERMINAL ID: 783257
                INVOICE: 123456
                Klarna Payment
                TRANSACTION ID: 1234
                PARTNER TRANSACTION ID: 67
                AMOUNT (USD): 12.20
                SUCCESS
                NO SIGNATURE REQUIRED
        </CPAPP_1>
</CP_MERCH_RECEIPT_DATA>
<CP_CUST_RECEIPT_DATA>
        <CPAPP_1>DATE: 2020-05-30
                TIME: 17:00:04
                TERMINAL ID: 783257
                INVOICE:  123456
                Klarna Payment
                TRANSACTION ID: 1234
                PARTNER TRANSACTION ID: 67
                AMOUNT (USD):  12.20
                SUCCESS
                NO SIGNATURE REQUIRED
        </CPAPP_1>
</CP_CUST_RECEIPT_DATA>

APM Result Codes

Following table lists the result/status codes for APM transactions.

  RESULT_CODE RESULT_TEXT
APM Approvals 5 APPROVED
APM Declines 6 DECLINED BY CARD
APM Transaction Timed out (When Payment Type is passed as PAYPAL/KLARNA/ALIPAY etc.) 59001 Cancelled by Timeout
APM Transaction Cancelled (When Payment Type is passed as PAYPAL/KLARNA/ALIPAY etc.) 59001 Cancelled by Customer
  

Note

If Payment is not passed, then Cancel/Timeout will result in going back to card read screen where the user can choose to pay by card.


Processing APM Refund

There are two ways to initiate refund for an APM Transaction:

  1. By manually entering the APM Transaction ID when APM prompts.
    • This process triggers the Refund transaction, and followed by selecting APM via the Card Read Screen.
    • Then APM prompts for transaction ID. Merchant is required to enter this transaction ID for processing APM Refund.
  2. By passing the APM Transaction ID in the CTROUTD field.
    • CTROUTD field has been enhanced to accept the APM Transaction ID. i.e. CTROUTD is allowed to accept 16 digit values.
    • Refund Transaction with the CTROUTD value must contain PAYMENT_TYPE which will contain the APM name.

Example

<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<COMMAND>CREDIT</COMMAND>
<CTROUTD>2415161621245678</CTROUTD>
<TRANS_AMOUNT>1.00</TRANS_AMOUNT>
<PAYMENT_TYPE>PAYPAL</PAYMENT_TYPE>
<MANUAL_ENTRY>FALSE</MANUAL_ENTRY>
</TRANSACTION>

Here, PAYMENT_TYPE field accepts the following - PAYPAL, KLARNA, WECHAT, ALIPAY, VENMO etc.

  

Note

For Standalone mode, application supports only the 1st method (Manually entering APM Transaction ID when APM prompts) to execute APM Refund.

Klarna ID Check Functionality

Klarna CP application requires a validation during the transaction processing to ensure the correct account holder is performing the transaction. In this case, the CP application provides a notification to SCA that confirmation is required. SCA would send notification to POS and ensure that merchant must validates the authenticity of the account holder and then send an approval of the ID check via the secondary port channel.

Klarna supports multiple ID Check configuration options:

  1. Confirmation on POS: Klarna application send a notification to SCA which in turn would notify the POS for ID Check Requirement through an unsolicited message as provided below.
<RESPONSE>
<RESPONSE_TEXT>User Identity Confirmation Required</RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>3</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<PAYMENT_TYPE>KLARNA</PAYMENT_TYPE>
<PROMPT>Validation of Identity Check - Verification Code:</PROMPT>
</RESPONSE>

Refer to Klarna ID Check Notification section for more information on Unsolicited Messages.

The POS is expected to respond back to this message using Secondary port confirmation command.

<TRANSACTION>
<FUNCTION_TYPE>SECONDARYPORT</FUNCTION_TYPE>
<COMMAND>CONFIRMATION</COMMAND>
<VALUE>CONFIRMED</VALUE>
</TRANSACTION>

The VALUE field can be set to DENIED if the ID check is not successful.
Refer to Confirmation command section in Secondary port Messages for more information.

  1. Show on Terminal: Klarna Application prompts the ID Check confirmation directly on the screen of terminal and allow merchant to accept or decline. This is generally used in the Standalone mode of operation or when customer does not have a POS capable of ID Check.
  2. Notification to POS: Klarna Application notifies that ID Check needs to be done and still move ahead with transaction processing. The merchant is responsible to ensure that ID Check is completed in the background. SCA would forward this notification via an unsolicited message to POS as noted below.
<RESPONSE>
<RESPONSE_TEXT>CP POS Display Notification</RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>4</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<PAYMENT_TYPE>KLARNA</PAYMENT_TYPE>
<PROMPT>Validation of Identity Check - Verification Code: </PROMPT>
</RESPONSE>

Refer to Klarna ID Check Notification section for more information on Unsolicited Messages.

  1. Customer Facing Terminal: In this case, Klarna Application only prompts the customer if they have the ID available to show to the merchant and would continue processing transaction based on this input from customer.

Additional Information

  • This functionality is supported in SCA Applications with Platform Version 5.4.1 and above.
  • Minimum Klarna Application Version needed for this feature is 1.61.
  • Default ID Check configuration in Klarna Application is set to “Show On Terminal”.
  • Polling Timeout configuration would control the maximum time that should be taken for the APM Transaction to complete. Hence this also controls the time allowed for ID confirmation. Polling timeout for the CP Application must be set according to the maximum POS timeout.
  • It is recommended to have the Polling timeout of 5 minutes to ensure sufficient time for ID verification.
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