API Docs
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.
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.
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:
|
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.
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.
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.
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.
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”.
Updated: June 2, 2017
SUBMIT A DEVELOPER SUPPORT REQUEST
Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341