Integration Guidance: Transaction and Capture States

All transactions received for processing by CWS are assigned a transaction state in the transaction database. When capturing a batch of transactions, each transaction is assigned a capture state and the transaction state is updated according to the current capture state of the batch.

Note: All responses returned by CWS include the TransactionState and CaptureState of each transaction.

 


 

Understanding Transaction States

All transactions processed by CWS are assigned a transaction state in the transaction database. When capturing a batch of transactions, each transaction will also be assigned a capture state and the transaction state is updated according to the current capture state of the batch.

TransactionState is an enumeration object that identifies the current status of each transaction in a batch. The valid enumeration values and descriptions for each TransactionState are listed below.

Transaction State Description
Adjusted The original transaction was successfully authorized and the amount subsequently successfully adjusted.
Authorized The original transaction was successfully authorized. The transaction has not yet been captured.
Captured The transaction was successfully captured.
CaptureDeclined An attempt to capture the transaction was declined by the service provider.
Declined The original transaction was successfully transmitted but declined by the service.
ErrorConnecting There was a connection error during the processing of this transaction.
ErrorUnknown An unknown error occured during the processing of this error.
ErrorValidation There was a validation error on the transaction request message.
InProcess Transaction is in process.
Note: There is no associated CaptureState for InProcess transactions.
PartiallyCaptured The transaction was captured with the expectation that another capture may be attempted.
PartiallyReturned A successfully captured transaction was returned for less than the captured amount. The return has been captured.
PartialReturnRequested A successfully captured transaction was returned for less than the captured amount. The return has not yet been captured.
Returned Either the original transaction was a standalone return (ReturnUnlinked), or a successfully captured transaction (ReturnById) was subsequently returned for the full amount. The return has been captured.
ReturnRequested Either the original transaction was a standalone return (ReturnUnlinked), or a successfully captured transaction was subsequently returned (ReturnById) for the full amount. The return has not yet been captured.
ReturnUndone A standalone return (ReturnUnlinked) or a return of a successfully captured transaction (ReturnById) was voided.
Undone The transaction was completely voided or reversed.
Verified A verify transaction was successfully run. Check response for details.

For more information about TransactionState, refer to the QueryTransactionsParameters and TransactionInformation objects in the CWS Transaction Management Developer's Guide.

 


 

Understanding Capture States

When capturing a batch of transactions, each transaction is assigned a capture state and the transaction state is updated according to the current capture state of the batch.

CaptureState is an enumeration object that identifies the current capture status of each transaction in a batch. The valid enumeration values and descriptions for each CaptureState are listed below.

Capture State Description
BatchSent Batch has been sent, response is out of band.
BatchSentUndoPermitted Batch has been sent, an Undo operation is allowed.
CannotCapture Transaction cannot be captured due to declined authorization or subsequent Undo of a successful authorization.
Captured The transaction was successfully captured.
CaptureDeclined Capture was successfully submitted but declined by the service.
CapturedUndoPermitted Indicates if an Undo is permitted for the Captured state.
CaptureError Indicates an error state during capture.
CapturePending Successfully transmitted capture but it is not yet known whether the processor accepted it. Future Use.
CapturePendingUndoPermitted Indicates if an Undo is permitted for the CapturePending state. Future Use.
CaptureUnknown Unknown capture state.
InProcess The capture is in process.
Note: The TransactionState may be any of the following:
  • Adjusted
  • Authorized
  • ErrorUnknown
  • PartialReturnRequested
  • Returned
  • ReturnRequested
  • ReturnUndone
  • Undone
ReadyForCapture Successfully authorized but capture not requested.
UndoReported Undo transaction has been captured by a CaptureAll. Presented as CannotCapture.

Important! Invoking the CaptureSelective operation for transactions with a CaptureState of "CaptureUnknown" may cause duplicate billing to the cardholder. Therefore, these operations should only be called when the merchant is certain that the transactions were not successfully captured. This requires communication with the service provider. Only by invoking the CaptureSelective operation will CWS attempt to re-process and capture transactions in the "CaptureUnknown" state. If the CaptureSelective operation is not implemented and the merchant has transactions in a "CaptureUnknown" state, you must contact your NAB Velocity Sales Engineer.

For more information about CaptureState, refer to Expected States - ACH, Expected States - BCP, and/or Expected States - SVA.

Additional information can be found in the QueryTransactionsParameters and TransactionInformation objects in the CWS Transaction Management Developer's Guide.

 


 

Expected States - ACH

The following table lists the transaction and capture states returned when processing Electronic Checking/ACH transactions.

Operation ACH Transaction Type Transaction State Capture State
Authorize ACH CHECK Authorized CapturedUndoPermitted
CaptureAll ACH COMMITBATCH Authorized Captured
CaptureSelective ACH BATCH Authorized Captured
QueryAccount ACH ACCTVAL NotSet CannotCapture
Undo ACH VOID Undone CannotCapture

Note: QueryAccount transactions are not assigned a specific TransactionState.

The above use of CaptureSelective for ACH BATCH assumes Authorize would process “offline” check for service providers that only support batches rather than individual checks.

For more information about resolving error conditions associated with a specific TransactionState, refer to Payment Status Messaging.

 


 

Expected States - BCP

The following table lists the transaction and capture states returned when processing Bankcard Credit/PIN Debit transactions on both Terminal and Host Capture systems.

Important! The AuthorizeAndCapture operation should always be used for PIN Debit transactions on both Host and Terminal Capture systems.

PIN Debit transactions are automatically captured for settlement even if they are not specifically captured using CaptureAll or CaptureSelective, while Credit transactions must be captured for settlement to ensure the proper funding of transactions.

Operation Provider Type Transaction Class Transaction State Capture State
AuthorizeAndCapture Host Capture PIN Debit Authorized CapturedUndoPermitted
Credit Authorized Captured
Terminal Capture PIN Debit Authorized CapturedUndoPermitted
Credit N/A
Invalid transaction. Use Authorize
N/A
Invalid transaction. Use Authorize
Authorize Host Capture PIN Debit N/A
Invalid transaction. Use AuthorizeAndCapture
N/A
Invalid transaction. Use AuthorizeAndCapture
Credit Authorized ReadyForCapture
(Undo allowed)
Terminal Capture PIN Debit N/A
Invalid transaction. Use AuthorizeAndCapture
N/A
Invalid transaction. Use AuthorizeAndCapture
Credit Authorized ReadyForCapture
(Undo allowed)
Adjust Host Capture PIN Debit N/A
Invalid transaction for PIN Debit.
N/A
Invalid transaction for PIN Debit.
Credit Adjusted Captured
(Undo not allowed)
Terminal Capture PIN Debit N/A
Invalid transaction for PIN Debit.
N/A
Invalid transaction for PIN Debit.
Credit Adjusted ReadyForCapture
(Undo allowed)
ReturnById,
ReturnUnlinked
Host Capture PIN Debit Returned CapturedUndoPermitted
Credit Returned Captured
(Undo not allowed)
Terminal Capture PIN Debit Returned CapturedUndoPermitted
Credit Returned ReadyForCapture
(Undo allowed)
Undo Host Capture PIN Debit Undone CannotCapture

Note: When CaptureAll is supported, Undo totals are reported back to the client, but will not be sent on BatchRelease to the service provider.
Credit Undone CannotCapture

Note: When CaptureAll is supported, Undo totals are reported back to the client, but will not be sent on BatchRelease to the service provider.
Terminal Capture PIN Debit Undone CannotCapture

Note: When CaptureAll is called, Undo totals are reported back to the client, but will not be sent on Batch to the service provider.
Credit Undone CannotCapture

Note: When CaptureAll is called, Undo totals are reported back to the client, but will not be sent on Batch to the service provider.
Capture Host Capture PIN Debit   N/A
Invalid transaction. Use AuthorizeAndCapture.
Credit   Captured
Terminal Capture PIN Debit   N/A
Invalid transaction. Use AuthorizeAndCapture.
Credit   N/A
Invalid transaction. Use AuthorizeAndCapture.
CaptureAll

Note: CaptureAll is only supported on Host Capture systems that support BatchRelease.
Host Capture PIN Debit   N/A
Invalid transaction. Use AuthorizeAndCapture.
Credit   Captured
Terminal Capture PIN Debit   N/A
Invalid transaction. Use AuthorizeAndCapture.
Credit Captured Captured
CaptureSelective

Note: CaptureSelective is not supported on Host Capture systems.
Host Capture PIN Debit    
Credit    
Terminal Capture PIN Debit   N/A
Invalid transaction. Use AuthorizeAndCapture.
Credit Captured Captured

Note: There may be other capture states assigned to a specific transaction that are not listed in the table above, such as "BatchSent" and "BatchSentUndoPermitted". Refer to Understanding Capture States for the complete list fo enumeration values.

For more information about resolving error conditions associated with a specific TransactionState, refer to Payment Status Messaging Guidelines.

 


 

Expected States - SVA

The following table lists the transaction and capture states returned when processing Stored Value Account transactions.

Operation SVA Transaction Type Transaction State Capture State
Authorize
(when AUTHONLY supported)
SVA REDEEM Authorized NotSet
Authorize
(when AUTHONLY not supported)
SVA REDEEM Authorized NotSet
AuthorizeAndCapture SVA REDEEM Authorized Captured
ManageAccount SVA ACTIVATE
SVA RELOAD
SVA DEACTIVATE
SVA BALTXFR
SVA STATUS
NotSet NotSet
Capture SVA REDEEM Authorized Captured
ReturnById SVA RETURN Returned Captured
ReturnUnlinked SVA RETURN Returned Captured
Undo SVA VOID Undone CannotCapture
QueryAccount SVA BALINQ NotSet NotSet

Note: Transactions with a CaptureState of “CaptureInProcess” cannot be captured.

Transactions with a CaptureState of "Captured" cannot be re-captured.

Transactions with a TransactionState of "Undone" cannot be captured, returned, or undone.

Transactions with a CaptureState of "ReadyForCapture" cannot be returned. Use Undo.

There may be other capture states assigned to a specific transaction that are not listed in the table above, such as "BatchSent" and "BatchSentUndoPermitted". Refer to Understanding Capture States for the complete list fo enumeration values.

For more information about resolving error conditions associated with a specific TransactionState, refer to Payment Status Messaging Guidelines.

 


 

Offline Batch Processing

When processing with service providers that support offline batch processing, transactions are captured by CWS and sent to the service provider for settlement. If the batch is successfully sent to the host, the CaptureState is set to "BatchSent". From a CWS perspective, BatchSent is functionally the same as "Captured", except there is no way to confirm whether the transactions in the batch were successfully settled by the service provider.

Note: It is the merchant's responsibility to contact their service provider to determine if the transactions in the batch have been successfully captured before taking further action.

If the batch is successfully sent to the service provider, but due to connection errors, CWS does not receive a confirmation, the CaptureState of all transactions in the batch are updated to "CaptureUnknown". In such cases, a batch settlement error is returned to the client application indicating the specific batch number.

The application must then query the batch using the QueryBatch operation provided by the Transaction Management Service API to retrieve a list of all transactions. Additionally, the merchant must contact the service provider to determine the capture state.

In the event that validation or connection errors are returned to the client application, all transactions in the batch are returned to the CaptureState of "ReadyForCapture".

Comments