Manage Transactions

Provides the ability for a user to monitor and track the transactions performed on their virtual cards.

Transaction records represent a transaction performed against a provisioned virtual card (for more information on virtual cards, see here). Transactions cannot be created or deleted by the consumer directly. Transactions are generated by using the virtual card to make purchases at merchants.

Each transaction record has a sequenceId property which can be used to cross reference related transactions. For example, a pending transaction may have already been partially transacted and have related debit transactions (for more information on transaction states, see here).

Transactions may also contain a detail property which includes some supplementary information. For more information, see here.

Transaction States

Transactions can exist in 4 different states:

• pending

• complete

• refund

• decline

When a transaction is pending, it has entered the first state of authorization and is currently awaiting to be debited, or further action. A transaction that is pending will typically be completely debited, thus deleting the existing pending transaction, and being replaced with a debit transaction. A transaction can be partially debited however, which means that a new debit transaction record will be created for each partial debit.

A pending transaction record will continue to persist until its value has been decreased to 0, either via debits or reversal charges. Reversals will not be recorded via the transaction records, except through the decreasing value of the pending transaction. This is not to be confused with a refund transaction, which will generate a new transaction record.

Note - Reversal transactions relate to a transaction that has had its value decreased before it has been fully transacted (completed). A refunded transaction occurs after a fully completed transaction.

When a transaction is represented as being complete, it has entered a state that represents a successful debit. A completed transaction can be associated with a previously pending transaction via the sequenceId if the completed transaction was a partial debit.

When a transaction is represented as a refund, it means that a previously transacted record (state is complete) has been refunded. This can be either for a partial amount or the full amount. If a transaction is refunded, it will not remove the complete transaction record.

When a transaction is represented as a decline, it means that an error has occurred while attempting to process a transaction. For more information on decline reasons, see here.

Transaction Details

Transactions can contain supplementary details in the form of the detail property. Supplementary details generally refer to the interactions with the user's actual funding source. Pending, complete, and refund transactions will always contain at least 1 detail. The information contained in details is recorded below:

Detail	Summary
virtualCardAmount	Amount merchant charged virtual card
markup	Markup formula applied to billedAmount to calculate
markupAmount	Markup amount added to transaction's transactedAmount
fundingSourceAmount	Amount charged to the funding source
transactedAt	Timestamp indicating when the transaction was sent to the funding source. This is optional because not all funding sources require interaction at each stage.
settledAt	Timestamp indicating when the transaction was settled with the funding source. This is optional until the transaction is settled.
fundingSourceId	ID of the funding source that funded this item
description	Description that will show on the real funding source statement
state	State returned by the funding source as a result of this transaction. Valid states are: Cleared, Pending, Insufficient Funds, and Failed.

Each interaction (authorization, charge, refund) with the funding source will result in a separate detail entry and should be able to be correlated with an entry on the user's account statement.

For pending and complete transactions, if there is no detail entry with state Cleared, then the transaction will continue to be counted against transaction velocity limits irrespective of the velocity limits' periods.

Decline Reasons

A transaction can be declined for a number of reasons. The table below shows a list of reasons and what they mean:

Reason	Cause
INSUFFICIENT_FUNDS	Funding source related to card has insufficent funds to perform the transaction
FUNDING_ERROR	Funding source related to card declined to perform the transaction for a reason other than insufficient funds.
CARD_STOPPED	Card associated with the transaction is inactive. This will occur implicitly if the funding source is also inactive
CARD_EXPIRED	Card associated with the transaction has expired.
MERCHANT_BLOCKED	Merchant that has been attempted to transact with is restricted
MERCHANT_CODE_BLOCKED	The merchant category code (MCC) of the merchant that has been attempted to transact with is restricted
MERCHANT_COUNTRY_BLOCKED	The country of the merchant that has been attempted to transact with is restricted
AVS_CHECK_FAILED	Address verification has failed
CSC_CHECK_FAILED	CSC verification has failed - occurs when the CSC provided to the merchant does not match the CSC of the virtual card
EXPIRY_CHECK_FAILED	Expiry verification has failed - occurs when the expiry date provided to the merchant does not match the expiry date of the virtual card
PROCESSING_ERROR	An error has occurred while attempting to process the transaction. Please contact support
DECLINED	Transaction is declined
VELOCITY_EXCEEDED	The transaction has exceeded its velocity policies
CURRENCY_BLOCKED	The transaction that has been attempted is in an unsupported currency

Retrieving Transactions

Transactions can be accessed in two ways: via its identifier (Single Transaction by Id), or via a list method (Multiple Transactions).

A fetch of single or multiple transactions can be performed remotely or locally by specifying the appropriate CachePolicy as part of the input.

Single Transaction by Id

To retrieve a single virtual card given its unique id, use the getTransaction method. This method will return the record if it exists.

TypeScript

try {
  const transaction = await virtualCardsClient.getTransaction({
    id,
    cachePolicy: CachePolicy.RemoteOnly
  })
  // `transaction` contains the transaction object, else `undefined` if not found.
} catch (error) {
  // Handle/notify error
}

Swift

do {
  let transaction = try await self.virtualCardsClient.getTransaction(withId: id)
  // If the id matches a transaction, `transaction` will be returned, else nil.
} catch {
  // Handle/notify user of error
}

Kotlin

launch {
    try {
        val transaction = withContext(Dispatchers.IO) {
            virtualCardsClient.getTransaction(
                id
            )
        }
        // If the [id] matches a transaction, [transaction] will be returned, else [null]
    } catch (e: TransactionException) {
        // Handle/notify user of exception
    }
}

Multiple Transactions

The ability to retrieve multiple transactions available to the user is supported. These results can be paginated and can contain transactions in various states.

A call to a list API will return a ListTransactionsResult with a status and depending on the status, a list of matching items and a nextToken to support pagination. If no results matching the input are found, the result will contain empty items. There can be three possible statuses returned:

Status	Definition
Success	A list of all requested transactions are returned.
Partial	A list of all transactions that were successfully fetched and decrypted are returned as well as a list of all transactions that failed to decrypt successfully, including an error indicating the reason for the failure.
Failure	All transactions failed to be fetched or decrypted. Contains an error indicating the reason for the failure.

A transaction may fail to be unencrypted if the version of the client is not up-to-date or if the required cryptographic key is missing from the client device.

All Transactions for a Virtual Card

To retrieve multiple transactions that are associated with a certain virtual card, call the listTransactionsByCardId method by passing in the id of the virtual card to query. An optional sortOrder and dateRange can also be supplied to organise results.

TypeScript

// Collect the input virtual card id however makes sense for your implementation.
const virtualCardId = virtualCard.id
try {
    const result = await virtualCardsClient.listTransactionsByCardId({
        virtualCardId,
        cachePolicy: CachePolicy.RemoteOnly,
        limit: 20,
        nextToken
    })
    if (result.status === ListOperationResultStatus.Success) {
        // `result.items` contains the list of items matching the input.
        // Page through the results if result.nextToken != undefined. 
    } else if (result.status === ListOperationResultStatus.Partial) {
        // `result.items` contains the list of items matching the input that decrypted successfully.
        // `result.failed` contains the list of items that failed decryption with associated error.
        //  Page through the results if `partial.nextToken` != undefined.
    } else {
        // `result.clause` contains the error which caused the failure.
    }
} catch {
    // Handle/notify user of errors
}

Swift

// Collect the input virtual card id however makes sense for your implementation.
do {
  let result = try await self.virtualCardsClient.listTransactions(
    withCardId: "id-of-card",
    nextToken: nil, 
    dateRange: nil,
    sortOrder: nil
  )
  switch result {
  case .success(let output):
     // `output.items` contains the list of items matching the input.
     // Page through the results if `output.nextToken` != nil.
  case .partial(let partial):
     // `partial.items` contains the list of items matching the input that decrypted successfully.
     // `partial.failed` contains the list of items that failed decryption with associated error.
     //  Page through the results if `partial.nextToken` != nil.
} catch {
  // Handle/notify user of error
}

Kotlin

// Collect the input virtual card id however makes sense for your implementation.
// val virtualCardId = virtualCard.id
launch {
    try {
        val result = withContext(Dispatchers.IO) { 
            virtualCardsClient.listTransactions(
                cardId = virtualCardId
                limit = 20, 
                nextToken = null,
                dateRange = null,
                sortOrder = SortOrder.DESC
            )
        }
        when (result) {
            is ListAPIResult.Success -> {
                // [result.items] contains the list of items matching the input.
                // Page through the results if [output.nextToken] != null.
            }
            is ListAPIResult.Partial -> {
                // [result.items] contains the list of items matching the input that decrypted successfully.
                // [result.failed] contains the list of items that failed decryption with associated error.
                //  Page through the results if [partial.nextToken] != null.
            }
        }
    } catch (e: TransactionException) {
        // Handle/notify user of exception
    }
}

All Transactions for a User

To retrieve multiple transactions that are associated across all of a user's virtual cards, call the listTransactions method. An optional sortOrder and dateRange can also be supplied to organise results.

TypeScript

try {
    const result = await virtualCardsClient.listTransactions({
        cachePolicy: CachePolicy.RemoteOnly,
        limit: 20,
        nextToken,
        dateRange,
        sortOrder: SortOrder.ascending
    })
    if (result.status === ListOperationResultStatus.Success) {
        // `result.items` contains the list of items matching the input.
        // Page through the results if result.nextToken != undefined. 
    } else if (result.status === ListOperationResultStatus.Partial) {
        // `result.items` contains the list of items matching the input that decrypted successfully.
        // `result.failed` contains the list of items that failed decryption with associated error.
        //  Page through the results if `partial.nextToken` != undefined.
    } else {
        // `result.clause` contains the error which caused the failure.
    }
} catch {
    // Handle/notify user of errors
}

Swift

do {
  let result = try await self.virtualCardsClient.listTransactions(
    nextToken: nil, 
    dateRange: dateRange,
    sortOrder: SortOrder.ascending
  )
  switch result {
  case .success(let output):
     // `output.items` contains the list of items matching the input.
     // Page through the results if `output.nextToken` != nil.
  case .partial(let partial):
     // `partial.items` contains the list of items matching the input that decrypted successfully.
     // `partial.failed` contains the list of items that failed decryption with associated error.
     //  Page through the results if `partial.nextToken` != nil.
} catch {
  // Handle/notify user of error
}

Kotlin

launch {
    try {
        val result = withContext(Dispatchers.IO) { 
            virtualCardsClient.listTransactions(
                limit = 20, 
                nextToken = null,
                dateRange = null,
                sortOrder = SortOrder.DESC
            )
        }
        when (result) {
            is ListAPIResult.Success -> {
                // [result.items] contains the list of items matching the input.
                // Page through the results if [output.nextToken] != null.
            }
            is ListAPIResult.Partial -> {
                // [result.items] contains the list of items matching the input that decrypted successfully.
                // [result.failed] contains the list of items that failed decryption with associated error.
                //  Page through the results if [partial.nextToken] != null.
            }
        }
    } catch (e: TransactionException) {
        // Handle/notify user of exception
    }
}

Subscribing to Transactions

Typescript Libraries currently do not support subscribing to transactions.

You can subscribe to receive updates as transactions are created, updated and deleted. The subscribeToTransactions, unsubscribeFromTransactions and unsubscribeAll APIs allow you to start and stop receiving updates.

You may receive multiple updates for a single transaction over time. Each time the transaction changes you will receive a new update. You should receive an update when the transaction is first created, the type field of the transaction will be PENDING. Some time later you will receive another update with the type set to COMPLETE, REFUND or DECLINE.

Swift

To subscribe to transaction changes, use the subscribe method. This method accepts a unique subscription identifier and a subscriber object which must implement the notify(notification: SubscriptionNotification) method. This handler should contain application-specific implementation of behavior in the event of a transaction change. The subscription object should also implement the connectionStatusChanged(state: SubscriptionConnectionState) method which is invoked in the event of subscription connection state changes between connected and disconnected. This handler allows the consumer to detect when the subscription connection has been lost and take appropriate corrective action.

Setting Up A Subscription

To setup the subscription for update events, create a Subscriber conforming instance and provide it to the subscription method:

class TransactionUpdatedSubscriber: Subscriber {

    func notify(notification: SubscriptionNotification) {
        if case .transactionUpdated(let transaction) = notification {
            // Handle the updated transaction.
        }
    }

    func connectionStatusChanged(state: SubscriptionConnectionState) {
        switch state {
        case .connected:
            // The subscription has become active.
        case .disconnected:
            // The subscription has become inactive and the subscriber
            // has been automatically unsubscribed.
        }
    }
}    

let subscriber = TransactionUpdatedSubscriber()
let id = UUID().uuidString
try await emailClient.subscribe(id: id, notificationType: .transactionUpdated, subscriber: subscriber)

To setup the subscription for deleted events, call the subscription method as so:

class TransactionDeletedSubscriber: Subscriber {

    func notify(notification: SubscriptionNotification) {
        if case .transactionDeleted(let transaction) = notification {
            // Handle the deleted transaction.
        }
    }

    func connectionStatusChanged(state: SubscriptionConnectionState) {
        switch state {
        case .connected:
            // The subscription has become active.
        case .disconnected:
            // The subscription has become inactive and the subscriber
            // has been automatically unsubscribed.
        }
    }
}
    
let subscriber = TransactionDeletedSubscriber()
let id = UUID().uuidString
try await virtualCardsClient.subscribe(id: id, notificationType: .transactionDeleted, subscriber: subscriber)

Cancelling A Subscription

To cancel a subscription, pass the same id value used to subscribe to the unsubscribe method:

await virtualCardsClient.unsubscribe(id: id)

This will ensure that the subscription is cancelled and system resources are freed. Alternatively you can cancel all subscriptions at once:

await virtualCardsClient.unsubscribeAll()

Kotlin

val subscriptionId = UUID.randomUUID().toString()
launch {
    try {
        withContext(Dispatchers.IO) {
            virtualCardsClient.subscribeToTransactions(subscriptionId) { txn ->
                // Handle updated transaction
            }
        }
    } catch (e: TransactionException) {
        // Handle exception
    }
    // Some time later ...
    withContext(Dispatchers.IO) {
        virtualCardsClient.unsubscribeFromTransactions(subscriptionId)
    }
}