Search…
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 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. 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
fundingSourceId
ID of the funding source that funded this item
description
Description that will show on the real funding source statement

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

Accessing Transactions

To provide the ability for a user to access transactional events performed against their virtual cards, the two APIs getTransactionWithId and listTransactionsWithFilter can be used on iOS or the two APIs getTransaction and listTransactions can be used on Android.
The former is used to access a specific transaction by its id, whereas the latter is sued to access a list of transactions. Both of these APIs support the use of data Caching through the use of the cachePolicy property.

Specific Access

To access a single transaction record, getTransactionWithId can be used. If the input id property does not match an existing record, a nil response will be returned.
Swift
Kotlin
1
client.getTransactionWithId(id, cachePolicy: .useOnline) { result in
2
switch result {
3
case let .success(output):
4
// Success! Can use results from `output`.
5
case let .failure(error):
6
// Something went wrong! handle `error` here.
7
}
8
}
Copied!
1
launch {
2
try {
3
val transaction = withContext(Dispatchers.IO) {
4
virtualCardsClient.getTransaction(transactionId)
5
}
6
} catch (e: TransactionException) {
7
// Handle exception
8
}
9
}
Copied!

Multiple Access

A user can receive multiple transactions against multiple virtual cards. To access multiple records at once, listTransactionsWithFilter may be used. If no results matching the input are found, an empty list will be returned.
This method can be used to restrict the results by providing a filter as a property. For more general details on filtering, see here.
Transactions support filtering on cardId and transactionSequenceId.
Multiple access supports Pagination. For more details, see here.
Swift
Kotlin
1
client.getTransactionsWithFilter(nil, nextToken: nil, cachePolicy: .useOnline) { result in
2
switch result {
3
case let .success(output):
4
// Success! Can use results from `output`.
5
case let .failure(error):
6
// Something went wrong! handle `error` here.
7
}
Copied!
1
launch {
2
try {
3
val transactions = withContext(Dispatchers.IO) {
4
virtualCardsClient.listTransactions {
5
filterTransactionsBy {
6
cardId beginsWith "42"
7
}
8
}
9
}
10
} catch (e: TransactionException) {
11
// Handle exception
12
}
13
}
Copied!

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
Kotlin
1
try client.subscribeToTransactionUpdates(
2
statusChangeHandler: { status in
3
/// Handle status changes
4
},
5
resultHandler: { result in
6
switch result {
7
case let .success(transaction):
8
/// Transaction update event occurred.
9
case let .failure(error):
10
/// Error occurred while receiving transaction update.
11
}
12
)
Copied!
1
val subscriptionId = UUID.randomUUID().toString()
2
launch {
3
try {
4
withContext(Dispatchers.IO) {
5
virtualCardsClient.subscribeToTransactions(subscriptionId) { txn ->
6
// Handle updated transaction
7
}
8
}
9
} catch (e: TransactionException) {
10
// Handle exception
11
}
12
// Some time later ...
13
withContext(Dispatchers.IO) {
14
virtualCardsClient.unsubscribeFromTransactions(subscriptionId)
15
}
16
}
Copied!
Last modified 8mo ago