Android SDK - Transaction Module

The transaction module of the SDK exposes legacy endpoints that enable the wallet to invoke a specific step in a specific kind of transaction.

Note: While the SDK does still support utilization of the calls documented in this topic, the SDK Rule Engine is a much more effective means of processing transactions. Refer to the Transaction Flow Rule Module for information about utilizing transactional metadata and flow rules to construct a richer, more flexible transaction flow.

The transaction module endpoints are exposed through several different service interfaces in the SDK. This topic is organized according to each different service.

Transaction Retrieval Service

This interface exposes the endpoints that retrieve relevant data from the Paydiant platform that the app needs to populate certain selections forms for the transaction.

Item Description
UI Service com.paydiant.android.ui.service.transaction.TransactionRetrievalService
Core Service com.paydiant.android.core.facade.TransactionManagerFacade

Set Retrieval Listeners

Item Description
Set Retrieval Listener void setTransactionRetrievalListener (ITransactionRetrievalListener listener);
com.paydiant.android.ui.service.transaction.ITransactionRetrievalListener
or an overridden instance of
com.paydiant.android.ui.service.transaction.TransactionRetrievalListenerAdapter
or com.paydiant.android.ui.service.transaction.ITransactionRetrievalWithSplitTenderInfoListener
Remove a Listener void removeListener();
Call this method from within the corresponding service class to remove the associated listener and set it to null.

Retrieve Split Tender Transaction Information

Pass the scanned checkout token with one of the following method options to connect to a transaction and retrieve the relevant information from the POS related to split tender support. You can optionally filter the results according to the parameters in the request.

UI Implementation

Item Description
UI Method 1 void retrieveTransactionDetailsWithSplitTenderInfo(String checkoutToken, final int startIndex, final int noOfRecords);

checkoutToken - The decoded value of the scanned QR Code.
startIndex - Return results only from this record number forward.
noOfRecords - The maximum number of records to return.
Overloaded UI Method 2 void retrieveTransactionDetailsWithSplitTenderInfo(String checkoutToken, int startIndex, int noOfRecords Date startDate, Date endDate);

checkoutToken - The decoded value of the scanned QR Code.
startIndex - Only return results from this record number forward.
noOfRecords - The maximum number of records to return.
startDate - Only return records relevant to this date or after.
endDate- Only return records relevant up through this date.
Success: void onTransactionInformationRetreivalSuccess (TransactionInformation transactionInformation);
Failure void onTransactionInformationRetrievalError(PaydiantException exception);

The failure callback returns an instance of PaydiantException for the transaction module including relevant error codes.

Core service

Item Description
Method 1 TransactionInformation retrieveTransactionDetailsWithSplitTenderInfo (String checkoutToken, int startIndex, int noOfRecords);

checkoutToken - The decoded value of the scanned QR Code.
startIndex - Only return results from this record number forward.
noOfRecords - The maximum number of records to return.
Overloaded Method 2 TransactionInformation retrieveTransactionDetailsWithSplitTenderInfo (String checkoutToken, int startIndex, int noOfRecords Date startDate, Date endDate);

checkoutToken - The decoded value of the scanned QR Code.
startIndex - Only return results from this record number forward.
noOfRecords - The maximum number of records to return.
startDate - Only return records relevant to this date or after.
endDate - Only return records relevant up through this date.

Returns raw output of the TransactionInformation results or relevant exception.

Errors

When retrieving transaction information, the following errors are applicable:

Error Description
400 The checkout token value is invalid.
403 The user must be logged-in to perform this operation.
406 The checkout token is blocked.
409 The checkout token is already in use by a processing transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out.
500 An unknown error occurred internally in the server.
503 The scanned code is not valid for this transaction.
508 The transaction request is not supported for this merchant.

Apply Tender Discounts

Call this method to update the transaction information with payment account discounts that are applicable for the current transaction.

Item Description
UI Method void applyDiscountsForPaymentAccounts (ListPaymentAccountComplete paymentAccounts, TransactionInformation transactionInformation);

paymentAccounts - The set of paymentAccountComplete objects for which this call is updating the discountAmount attribute.
transactionInformation - An instance of the object representing the current transaction for which this call is updating the discountMap value.

This call does not return any payload upon completion or failure.
Core Method void applyDiscountsForPaymentAccounts (ListPaymentAccountComplete paymentAccounts, TransactionInformation transactionInformation);

paymentAccounts - The set of paymentAccountComplete objects for which this call is updating the discountAmount attribute.
transactionInformation - An instance of the object representing the current transaction for which this call is updating the discountMap value.

This call does not return any payload upon completion or failure.

Clear Tender Discounts

Call this method to remove payment account discounts from the specified payment accounts once the relevant transaction for the discounts has completed.

Item Description
UI Method void clearDiscountsForPaymentAccounts (List < PaymentAccountComplete > paymentAccountsList);

paymentAccountsList - The set of paymentAccountComplete objects for which this call is removing the previously set discounts.

This call does not return any payload upon completion or failure.
Core Method void clearDiscountsForPaymentAccounts (ListPaymentAccountComplete paymentAccountsList);

paymentAccountsList - The set of paymentAccountComplete objects for which this call is removing the previously set discounts.

This call does not return any payload upon completion or failure.

Process Payment Service

This interface exposes the endpoints that submit the final details from the app to process the payment through the relevant processor for the merchant.

Item Description
UI Service com.paydiant.android.ui.service.transaction.ProcessPaymentService
Core Service com.paydiant.android.core.facade.TransactionManagerFacade
Set Process Listener ProcessPaymentService.setProcessPaymentListener (IProcessPaymentListener listener)com.paydiant.android.ui.service.transaction.IProcessPaymentListener
or an overridden instance of
com.paydiant.android.ui.service.transaction.ProcessPaymentListenerAdapter
or
com.paydiant.android.ui.service.transaction.IProcessSplitPaymentListener
Remove a Listener void removeListener();

Call this method from within the corresponding service class in order to remove the associated listener and set it to null.

Process Split Tender Payment

Call this method to submit the user specified payment details for a transaction where split-tender is supported. Continue processing until the success callback response returns complete rather than partial.

Item Description
UI Method void doSplitPayment(Payment splitTenderPayment);

splitTenderPayment - An instance of the Payment class that encapsulates the relevant payment details, such as the transaction identifier, the amount of the payment, any discount or tip adjustments, and the selected payment account, for one of multiple payments in the transaction.
Success void onProcessSplitPaymentSuccess(PaymentTransaction paymentTransaction);

paymentTransaction - An instance of the PaymentTransaction class that confirms the processed details for the completed payment. For split tender transactions, the paymentStatus attribute of the response class will be partial until the balance for the transaction amount is 0, at which point the final response will have a paymentStatus of complete.
Failure void onProcessPaymentError(PaydiantException exception);

The failure callback returns an instance of PaydiantException for the transaction module including relevant error codes.
Core Method PaymentTransaction makePayment(Payment payment);

payment - An instance of the Payment class that encapsulates the relevant payment details, such as the transaction identifier, the amount of the payment, any discount or tip adjustments, and the selected payment account for one of multiple payments in the transaction.

Returns raw output of the PaymentTransaction class or relevant exception.

Errors

When submitting a split tender payment, the following errors are applicable:

Error Description
400 The transaction was declined.
402 Suspected fraud.
403 Access to the server is prohibited because the user is not logged-in.
406 The tender type is not supported for this merchant.
409 The checkout token is already in use by a processing transaction.
410 The amount specified is not valid.
414 The offer specified is not redeemable for the current transaction.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out.
419 The checkout token is not valid.
420 Tipping is not supported at the current location.
421 An error occurred during the tipping calculation.
422 An error has occurred on the POS terminal.
423 The payment account specified has been deleted from the wallet.
500 An unknown error occurred internally in the server.
501 A processing error has occurred.
502 The transaction is being reviewed.
503 The scanned code is not valid for this transaction.
504 The card number specified is invalid.
505 The card specified has expired.
506 The wallet is not supported at this acceptance location.
507 The billing address specified is not valid.
508 Split Tender transactions are not supported at this location.
510 The transaction requested is not valid for this location.

ATM Cash Service

This interface exposes the endpoints that submit the final details from the app to process a cardless cash withdrawal from an ATM.

UI implementation

Item Description
UI Service com.paydiant.android.ui.service.mobilecash.ATMCashService
Core Method com.paydiant.android.core.facade.IATMCashManagerFacade
Set Process Listener ATMCashService.setATMCashServiceListener(IATMCashServiceListener listener)
com.paydiant.android.ui.service.mobilecash.IATMCashServiceListener
or an overridden instance of com.paydiant.android.ui.service.mobilecash.ATMCashServiceListenerAdapter
Remove a Listener void removeListener();

Call this method from within the corresponding service class in order to remove the associated listener and set it to null.

Withdraw ATM Cash

Call this method to submit the user specified details for a cash withdrawal from an ATM.

Item Description
UI Method void submitATMCashAmount(CashTransaction cashTransaction);

cashTransaction - An instance of the CashTransactionclass populated with the relevant withdrawal details, such as the transaction identifier, the cash amount, the selected debit account, and the cash access type (only withdrawal is supported at this time).
Success void onSubmitATMCashAmountSuccess(CashTransactionResult cashTransactionResult);

cashTransactionResult - An instance of the cashTransactionResult class that confirms the processed details for the completed withdrawal.
Failure void onATMCashServiceError(PaydiantException exception);

The failure callback returns an instance of PaydiantException for the transaction module including relevant error codes.
Core Method CashTransactionResult submitATMCashAmount(CashTransaction cashTransaction);

cashTransaction - An instance of the CashTransaction class populated with the relevant withdrawal details, such as the transaction identifier, the cash amount, the selected debit account, and the cash access type (only withdrawal is supported at this time).

Returns raw output of the CashTransaction class or relevant exception.

Errors

When withdrawing cash, the following errors are applicable:

Error Description
400 The transaction was declined.
403 Access to the server is prohibited because the user is not logged-in.
405 The specified account contains insufficient funds.
423 The payment account specified has been deleted from the wallet.
500 An unknown error occurred internally in the server.
510 The transaction requested is not valid for this location.

Process Refund Service

This interface exposes the endpoints that submit the final details from the app to issue a refund for a previously completed payment.

Item Description
UI Service com.paydiant.android.ui.service.transaction.RefundTransactionService
Core Service com.paydiant.android.core.facade.TransactionManagerFacade
Set Process Listener RefundTransactionService.setRefundTransactionListener(IRefundTransactionListener listener)
com.paydiant.android.ui.service.transaction.IRefundTransactionListener

or an overridden instance of
com.paydiant.android.ui.service.transaction.RefundTransactionListenerAdapter
Remove a Listener void removeListener();
Call this method from within the corresponding service class to remove the associated listener and set it to null.

Process a Refund

Call this method to submit the user specified details for a transaction of type REFUND.

Item Description
UI Method void refundTransaction(RefundRequest refund);

refund - An instance of the RefundRequest class populated with the relevant details, such as the transaction identifier, the original receipt identifier, and the original merchant.
Success void onRefundTransactionSuccess(RefundTransaction refundTransaction);

refundTransaction - An instance of the RefundTransaction class that confirms the processed details for the completed refund, including amount and the credited account.
Failure void onRefundTransactionError(PaydiantException exception);

The failure callback returns an instance of PaydiantException for the transaction module including relevant error codes.
Core Method RefundTransaction refundTransaction(RefundRequest refundRequest);

refundRequest - An instance of the RefundRequest class populated with the relevant details, such as the transaction identifier, the original receipt identifier, and the original merchant.

Returns raw output of the RefundTransaction class or relevant exception.

Errors

When processing a refund, the following errors are applicable:

Error Description
400 Cannot process the request due to a syntactical error.
403 Access to the server is prohibited because the user is not logged-in.
404 The specified receipt cannot be located.
408 The refund amount exceeds the sale amount.
411 The refund transaction failed, possibly due to invalid parameters.
500 An unknown error occurred internally in the server.
416 The transaction has been canceled by the POS terminal.
417 The transaction has timed out.
419 The checkout token is not valid.
422 An error has occurred on the POS terminal.
423 The payment account specified has been deleted from the wallet.
500 An unknown error occurred internally in the server.
501 A processing error has occurred.
502 The transaction is being reviewed.
503 The scanned code is not valid for this transaction.
504 The card number specified is invalid.
505 The card specified has expired.
506 The wallet is not supported at this acceptance location.
507 The billing address specified is not valid.
510 The transaction requested is not valid for this location.

Cancel Transaction Service

This interface exposes the endpoints that submit the final details from the app to process a transaction that issues a refund for a previously completed payment.

Item Description
UI Service com.paydiant.android.ui.service.transaction.CancelTransactionService
Core Service com.paydiant.android.core.facade.TransactionManagerFacade
Set Cancel Listener CancelTransactionService.setCancelTransactionListener(ICancelTransactionListener listener)
com.paydiant.android.ui.service.transaction.ICancelTransactionListener

or an overridden instance of
com.paydiant.android.ui.service.transaction.CancelTransactionListenerAdapter
Remove a Listener void removeListener();
Call this method from within the corresponding service class in order to remove the associated listener and set it to null.

Cancel a Transaction

Call this method to terminate a transaction that is in process, but has not been submitted to the processor for authorization.

Item Description
UI Method void cancelTransaction(String checkoutToken, String paydiantTransactionRefId);

checkoutToken - The checkout token that was scanned to initiate the transaction.
paydiantTransactionRefId - The unique identifier of the transaction in the Paydiant system.
Success void onCancelTransactionSuccess();
Failure void onCancelTransactionError(PaydiantException exception);

The failure callback returns an instance of PaydiantException for the transaction module including relevant error codes.
Core Method void cancelTransaction(String checkoutToken,String paydiantTransactionRefId);

checkoutToken - The checkout token that was scanned to initiate the transaction.
paydiantTransactionRefId - The unique identifier of the transaction in the Paydiant system, which is returned with the TransactionInformation response.

Returns no payload upon completion. Failure returns the raw output of the PaydiantException class with relevant error information.

Errors

When canceling a transaction, the following errors are applicable:

Error Description
400 Cannot process the request due to a syntactical error.
403 Access to the server is prohibited because the user is not logged-in.
500 An unknown error occurred internally in the server.

Other Resources

javadocs

Feedback

Have feedback?

Let us know.