> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/psdk-latest/reference-material/code-labs/advanced-payments.md).
# Advanced Payments
{% columns %}
{% column width="41.66666666666667%" %} :clock: 1 minutes reading time\ :calendar: Last updated: 10th October, 2025
{% endcolumn %}
{% column width="24.999999999999986%" %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
{% stepper %}
{% step %}
## Introduction - Early & Background Card Capture
* This code lab describes steps for performing early card capture and Background card read based transactions while developing PSDK POS application.
* PSDK provides [**requestCardData2**](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#requestcarddata2-cardacquisitionrequest) api which will read the card information after detecting the card then payment processing can be done via **startPayment** api.
* This api takes [**CardAcquisitionRequest**](https://docs.verifone.com/psdk-api-latest/android-java/index/cardacquisitionrequest) data as intake parameter and will trigger the [**handleCardInformationReceivedEvent**](https://docs.verifone.com/psdk-api-latest/android-java/index/commercelistener2#handlecardinformationreceivedevent-cardinformationreceivedevent) of [CommerceListenerAdapter ](https://app.gitbook.com/s/yzyMJNwlQJZoQOIC8vZ8/api/moduleindex-4/_commerce_listener_adapter_8java)callback which been set to PSDK during initialization.
* This complete process is referred as Card Acquisition.
### What you should already know
* The device you will be using for integration.
* Setting up the device and development environment for developing PSDK application
* Initialization of PSDK on the POS application ([init](https://docs.verifone.com/psdk-api-latest/android-java/index/paymentsdkbase#initializefromvalues-commercelistener2-hashmapstringstring), [login](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#loginwithcredentials-logincredentials) and [startSession](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#startsession2-transaction))
* Adding the [CommerceListenerAdapter ](https://app.gitbook.com/s/yzyMJNwlQJZoQOIC8vZ8/api/moduleindex-4/_commerce_listener_adapter_8java)for PSDK status and informations
### What you'll need
* Any Verifone device with necessary software loaded. Watch the PSDK Getting started code labs for more details on devices and software.
* Internet connectivity
### What you'll do
* Integrate early capture payment code in a POS sample application
* Build and test the transaction
{% endstep %}
{% step %}
## Configuration Settings
To use **Card Acquisition + Payment** feature, you need to configure one terminal setting i.e. **CardAcquisitionBehaviour**. Based on this value Card Acquisition process will behave differently as mentioned below. This can be used for AGPA payment solution, for other payment solution you can reach out the support staff.
### Terminal.CardAcquisitionBehaviour
* **0** -> No follow on operations like payment allowed using acquired card data
* **1** -> Allow for follow on operations like payment using acquired card data without asking for card presentation again
{% endstep %}
{% step %}
## Usage
* This feature is used to read the card information and then will continue for payment proceesing with the amount details.
* To perform Payment along with Card Acquisition process **Terminal.CardAcquisitionBehaviour** parameter must be set to **1** as already mentioned in Configuration Settings .
* This will include two PSDK api call i.e. **requestCardData2** and **startPayment**.
* Early card capture is a foreground task where as Background card read feature is a background task and is only supported for ON Device integration mode.
### Creation of CardAcquisitionRequest object for EarlyCardCapture
This object can be created by using [**createEarlyCardCapture()**](https://docs.verifone.com/psdk-api-latest/android-java/index/cardacquisitionrequest#createearlycardcapture-string-arraylistpresentationmethod-decimal-earlycaptureoperationtype) api.
```java
String message = "Read Card";
ArrayList presentationMethods = new ArrayList<>();
presentationMethods.add(PresentationMethod.CHIP);
presentationMethods.add(PresentationMethod.CTLS_CARD);
presentationMethods.add(PresentationMethod.MAG_STRIPE);
CardAcquisitionRequest cardAcquisitionRequest =
CardAcquisitionRequest.createEarlyCardCapture(
message,
presentationMethods,
Decimal.valueOf(BigDecimal.ONE),
EarlyCaptureOperationType.PAYMENT
);
```
### Creation of CardAcquisitionRequest object for BackgroundCardRead
This object can be created by using [**create()**](https://docs.verifone.com/psdk-api-latest/android-java/index/cardacquisitionrequest#create-boolean-string-arraylistpresentationmethod-arrayliststring-arrayliststring-arrayliststring-boolean) api. Here the last parameter of [**create()**](https://docs.verifone.com/psdk-api-latest/android-java/index/cardacquisitionrequest#create-boolean-string-arraylistpresentationmethod-arrayliststring-arrayliststring-arrayliststring-boolean) api is responisble to enable or disable the background read card.
```java
// Api Defnition : CardAcquisitionRequest create(boolean isTokenRequest,
// String message, ArrayList [PresentationMethod] presentationMethodNames,
// ArrayList [String] aidList, ArrayList [String] allowedPaymentBrand,
// ArrayList [String] allowedLoyaltyBrand, Boolean isBackground)
String message = "Background read card";
ArrayList [PresentationMethod] presentationMethods = new ArrayList<>();
presentationMethods.add(PresentationMethod.MAG_STRIPE);
presentationMethods.add(PresentationMethod.CHIP);
presentationMethods.add(PresentationMethod.CTLS_CARD);
CardAcquisitionRequest cardAcquisitionRequest = CardAcquisitionRequest. create(false,message, presentationMethods, null,null,null,true);
```
### API call to **requestCardData2**
```java
if (TransactionManagerState.SESSION_OPEN == PaymentSdk.getTransactionManager().
getState()) {
Status status = PaymentSdk.getTransactionManager().
requestCardData2(cardAcquisitionRequest);
//"requestCardData2, status : " + status.getStatus() + ",
// type : " + status.getType() + ",// message : " +
//status.getMessage();
} else {
// Invalid state,
// Kindly refer the PSDK documentation for starting the session.
}
```
### Status callback event from PSDK
The status event will be received on [**handleCardInformationReceivedEvent**](https://docs.verifone.com/psdk-api-latest/android-java/index/commercelistener2#handlecardinformationreceivedevent-cardinformationreceivedevent) of [CommerceListenerAdapter](https://app.gitbook.com/s/yzyMJNwlQJZoQOIC8vZ8/api/moduleindex-4/_commerce_listener_adapter_8java) PSDK callback.
```java
@Override
public void handleCardInformationReceivedEvent(CardInformationReceivedEvent
cardInformationReceivedEvent) {
// You can retrieved all the required details here.
CardInformation cardInformation = cardInformationReceivedEvent.
getCardInformation();
if (cardInformationReceivedEvent.getStatus() == StatusCode.SUCCESS &&
cardInformation != null) {
// "track1 : " + cardInformation.getCardTrack1();
// "track2 : " + cardInformation.getCardTrack2();
// "track3 : " + cardInformation.getCardTrack3();
// "Expiry : " + cardInformation.getCardExpiry();
// "CardPan : " + cardInformation.getCardPan();
// "CardHolderName : " + cardInformation.getCardHolderName();
}
```
}
### Start payment processing
Here with this setting, Card Acquisition works as a session and will return the read card data to the POS as soon as the card is read. If quick chip is enabled an inserted card is allowed to be removed, however if quick chip is not enabled, an inserted card must remain in the terminal until the payment is started and completed or the card acquisition session is cancelled. Payment processing can be started with amount details as mentioned below. For more details kindly refer to Payment codelab.
```java
Payment payment = Payment.create();
// AmountTotals can be set here with all required details
payment.setRequestedAmounts(amountTotals);
payment.setTransactionType(TransactionType.PAYMENT);
PaymentSdk.getTransactionManager().startPayment(payment);
```
{% endstep %}
{% step %}
## Introduction - Basket Management
This code lab describes steps for basket management from the payment application while developing PSDK based POS application.
### **Basket Management:**
public class Basket
This class represents all of the items that have been added to the basket. Adding items should generally be performed through the [com.verifone.payment\_sdk.BasketManager](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager), so that the display is updated and the appropriate events are sent. This object is useful to store the current basket, save it for later, then quickly restore all of the items to the screen, in case an order is put on hold and then retrieved.
Adding items to the basket is done via the [addMerchandise()](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#addmerchandise-arraylistmerchandise-amounttotals) method of the [basketManager ](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager)class. It adds the items to the basket, notifying listening applications and updating the display. This method requires the following parameters:
* The merchandise list
* The Amount
As an example, in the below code we are adding merchandise of amount 1.00.
Its important to check the state of the [TransactionManager](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager) before adding the merchandise. This can be done using the [getState()](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#getstate) method.
```java
//TransactionManager state must be in a valid state, as here it is in session open
if( PaymentSdk.getTransactionManager().getState()== TransactionManagerState.
SESSION_OPEN)
{
BasketManager basketManager = PaymentSdk.getTransactionManager().
getBasketManager();
int count = basketManager.getBasket() != null &&
basketManager.getBasket().getMerchandise() != null
? basketManager.getBasket().getMerchandise().size()
: 0;
count++;
Merchandise merchandise = Merchandise.create();
merchandise.setName("Item " + count);
merchandise.setAmount(Decimal.valueOf(BigDecimal.valueOf(1.00)));
mAmounts.setTotal(Decimal.
valueOf(mAmounts.getTotal().toBigDecimal().
add(merchandise.getAmount().toBigDecimal())));
basketManager.addMerchandise(new ArrayList<>(Collections.
singletonList(merchandise)), mAmounts);
}
```
After adding the items, you can use the [handleBasketEvent()](https://docs.verifone.com/psdk-api-latest/android-java/index/commercelistener2#handlebasketevent-basketevent) method to hande the response. This method checks the status of the event and performs actions based on whether the adding was successful or not.
```java
//callback event for the addMerchandise method
@Override public void handleBasketEvent(BasketEvent basketEvent)
{
if (basketEvent.getBasketAction() == BasketAction.ADDED)
{
if (basketEvent.getStatus() == StatusCode.SUCCESS)
{
// Add successful
} else {
// Add failure
}
}
}
```
You can modify the items in the basket, notifying listening applications and updating the display. You can use the Basket Item ID to apply the new values of the proper items from the basket.
Modifying the items to the basket is done via the modifyMerchandise() method of the basketManager class. It modifies the items to the basket, notifying listening applications and updating the display. This method requires the following parameters:
* The merchandise list
* The Amount
As an example, in the below code we are modifying the name of the last merchandise in the basket.
```java
//TransactionManager state must be in valid state, as here it is session open
if( PaymentSdk.getTransactionManager().getState()== TransactionManagerState.
SESSION_OPEN)
{
if (PaymentSdk.getTransactionManager().getBasketManager() != null) {
BasketManager basketManager = PaymentSdk.getTransactionManager().
getBasketManager();
if (basketManager.getBasket() != null &&
basketManager.getBasket().getMerchandise() != null &&
!basketManager.getBasket().getMerchandise().isEmpty()) {
Merchandise merchandise = basketManager.getBasket().
getMerchandise().get(basketManager.
getBasket().getMerchandise().
size() - 1);
merchandise.setName("Modified " + merchandise.getName());
basketManager.modifyMerchandise(new ArrayList<>(Collections.
singletonList(merchandise)),mAmounts);
}
}
}
```
After modifying the items, you can use the [handleBasketEvent()](https://docs.verifone.com/psdk-api-latest/android-java/index/commercelistener2#handlebasketevent-basketevent) method to handle the response. This method checks the status of the event and performs actions based on whether the modifying was successful or not.
```java
//callback event for the modifyMerchandise method
@Override
public void handleBasketEvent(BasketEvent basketEvent) {
if(basketEvent.getBasketAction()== BasketAction.MODIFIED) {
if(basketEvent.getStatus()==StatusCode.SUCCESS) {
//Modification successful
}else {
//Modification failure
}
}
}
```
You can remove the items from the basket, notifying listening applications and updating the display. You can use the Basket Item ID to remove the proper items from the basket.
Removing the items to the basket is done via the modifyMerchandise() method of the basketManager class. It modifies the items to the basket, notifying listening applications and updating the display. This method requires the following parameters:
* The merchandise list
* The Amount
As an example, in the below code we are removing the last merchandise in the basket.
```java
if( PaymentSdk.getTransactionManager().getState()== TransactionManagerState.
SESSION_OPEN)
{
if (PaymentSdk.getTransactionManager().getBasketManager() != null) {
BasketManager basketManager = PaymentSdk.getTransactionManager().
getBasketManager();
if (basketManager.getBasket() != null && basketManager.getBasket().
getMerchandise() != null &&
!basketManager.getBasket().getMerchandise().isEmpty()) {
Merchandise merchandise = basketManager.getBasket().getMerchandise()
.get(basketManager.getBasket().getMerchandise().size() - 1);
mAmounts.setTotal(Decimal.valueOf(mAmounts.getTotal().toBigDecimal()
.subtract(merchandise.getAmount().toBigDecimal())));
basketManager.removeMerchandise(new ArrayList<>(Collections.
singletonList(merchandise)), mAmounts);
}
}
}
```
After removing the items, you can use the [handleBasketEvent()](https://docs.verifone.com/psdk-api-latest/android-java/index/commercelistener2#handlebasketevent-basketevent) method to handle the response. This method checks the status of the event and performs actions based on whether the removal was successful or not.
```java
//callback event for the removeMerchandise method
@Override
public void handleBasketEvent(BasketEvent basketEvent) {
if(basketEvent.getBasketAction()== BasketAction.REMOVED) {
if(basketEvent.getStatus()==StatusCode.SUCCESS){
//Removal successful
}else{
//Removal failure
}
}
}
```
### **Finishing a Basket and initiating Basket sale:**
Finalizing the basket lets the payment application know that the POS has finished with the initial basket and can allow other applications to make adjustments via the REQUEST\_BASKET\_ADJUSTMENT trigger. The attached transaction listeners will be notified if any changes are made, and can respond with a finalized basket directly to the event. After closing the basket, no further actions should be performed on it using the basket manager.
```java
//To Finalize a Basket
BasketManager basketManager = PaymentSdk.getTransactionManager().
getBasketManager();
int basketItemCount = basketManager.getBasket() != null &&
basketManager.getBasket().getMerchandise() != null ?
basketManager.getBasket().getMerchandise().size(): 0;
//checking if basket is not null or empty & invoke the API
if(basketItemCount>0)
basketManager.finalizeBasket();
```
After finalizing the basket, invoke sale transaction using [TransactionManager().startPayment(payment)](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#startpayment-payment) with the respective basket total to process the basket sale.
The code snippet for the callback event is below:
```java
//callback event for the above methods
@Override
public void handleBasketEvent(BasketEvent basketEvent) {
if(basketEvent.getBasketAction()== BasketAction.FINALIZED) {
Payment paymentObject = Payment.create();
paymentObject.setRequestedAmounts(mAmounts);
//For more information on startPayment method,see payments codelab
Status result = PaymentSdk.getTransactionManager().
startPayment(paymentObject);
}
}
```
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.verifone.com/psdk-latest/reference-material/code-labs/advanced-payments.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.