Android SDK - Transaction Module
DOCS
Last updated: Aug 15th, 5:57am
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.ITransactionRetrievalListeneror 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 request 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 (List<PaymentAccountComplete> 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 (List<PaymentAccountComplete> 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 (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. |
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.IProcessPaymentListeneror 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 request 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.IATMCashServiceListeneror 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 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). |
| 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.IRefundTransactionListeneror 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 request 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.ICancelTransactionListeneror 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. |