Wallet transactions

Learn how wallet transactions provide insight into funds that move in and out of an account’s wallet.

For each transfer, a corresponding transaction is created representing how that initial source impacted a wallet. This granularity enables you to:

Reconcile a wallet’s balance on any given day
Create itemized reports leveraging transaction types (fees earned and paid, payouts, refunds, etc)
Monitor your wallet activity to stay informed on the latest transactions

Each transaction is paired with a detailed memo that provides more context about the transaction. For additional insight into how the transaction was created, you can provide the source ID to grab details. The source ID is used to link back to a transfer, dispute, or card issuing transaction.

You can retrieve the sourceID using the wallet transaction GET endpoint.

Pending transactions

A pending transaction will only apply to credits, or incoming funds. Any funds in a pending state will not affect the wallet balance, or be available for use until that transaction is completed. If a pending transaction results in a failure, we’ll simply omit it from the transaction list.

Use the wallet GET endpoint to check a wallet's available balance or access a failed transaction's details.

Completed transactions

The available balance at the time of transaction is included on each completed wallet transaction. Once a transaction moves to completed, the completedOn timestamp will be populated along with the availableBalance.

Wallet transaction types

The list wallet transactions and retrieve a wallet transaction endpoints will display the transactionType in the response. We categorize wallet transactions by the following distinct types:

ACH

Type	Description	Source	Memo
payment	An ACH payment from a bank to the account’s wallet	transfer	ACH payment from {displayName}
top-up	Transfer of funds into a wallet from the account’s bank	transfer	Top up from {bankAccountType} {lastFourAccountNumber}
payout	A payment from a wallet to another accounts bank	transfer	ACH payment to {displayName}
cash-out	Transfer of funds out of a wallet to the account’s bank	transfer	Cash out to {bankAccountType} {lastFourAccountNumber}
ach-reversal	When an ach payment is returned, funds are either returned or taken from the wallet balance	transfer	Returned ACH credit/debit

Card acquiring

Type	Description	Source	Memo
card-payment	A payment that was made from a card	transfer	Card payment from {displayName}
refund	The requested refund amount is debited from the wallet	transfer	Refund to {displayName}
refund-failure	To account for refund failures, a credit will be made back into the wallet	transfer	Failed refund to {displayName}
dispute	When a customer disputes a charge, the disputed amount is debited from the wallet	dispute	Cardholder dispute
dispute-reversal	If a dispute is won by a merchant, funds will be credited back to their wallet	dispute	Cardholder dispute reversed

RTP

Type	Description	Source	Memo
payout	A payment from a wallet to another accounts bank	transfer	Card payout to {displayName}
cash-out	Transfer of funds out of a wallet to the account’s bank	transfer	RTP cash out to {bankAccountType} {lastFourAccountNumber}
rtp-failure	The receiving bank has rejected the transfer	transfer	Failed RTP payment {failureCode}

Push to card

Type	Description	Source	Memo
payout	A payment from a wallet to another accounts bank	transfer	Card payout to {displayName}
cash-out	Transfer of funds out of a wallet to the account’s bank	transfer	Card cash out to {brand} {lastFourCardNumber}
card-decline	The authorization has failed	transfer	Declined card payout {reason}
card-reversal	The authorization has been reversed, cancelling the transfer and returning funds	transfer	Card payment reversed

Pull from card

Type	Description	Source	Memo
account-funding	Debit or prepaid card transfer to an external account owned by the cardholder	transfer	Account funding from {displayName}
top-up	Transfer of funds into a wallet from the account’s bank	transfer	Wallet funding from {brand} {lastFourCardNumber}
refund	When a refund is initiated, the requested refund amount is debited from the wallet	transfer	Refund to {displayName}
refund-failure	To account for refund failures, a credit will be made back into the wallet	transfer	Failed refund to {displayName}
dispute	When a customer disputes a charge, the disputed amount is debited from the wallet	dispute	Cardholder dispute
dispute-reversal	If a dispute is won by a merchant, funds will be credited back to their wallet	dispute	Cardholder dispute reversed

Sweeps

Type	Description	Source	Memo
auto-sweep	Daily transfers to external bank accounts on a set schedule	sweep	Automatic sweep {bankAccountType} {lastFourAccountNumber}, Failed sweep {endDate} {reason}

Moov wallet

Type	Description	Source	Memo
moov-fee	Fee charged to your account for card transfers	transfer	Fee for {feeName}

Wallet to wallet

Type	Description	Source	Memo
wallet-transfer	Funds that move between Moov wallets	transfer	Wallet transfer to/from {displayName}

Fees

Type	Description	Source	Memo
facilitator-fee	Fee earned on a transfer	transfer	Facilitator fee collected
moov-fee	Fee charged to your account for card transfers	transfer	Fee for {feeName}

Issuing*

Type	Description	Source	Memo
issuing-transaction	Reflects funds moving out of the wallet from a cleared authorization, a refund, or a force post	issuing-transaction	Payment {Merchant Name}, Refund {Merchant Name}, Credit {Merchant Name}, Payment {Merchant Name}
issuing-auth-release	Held funds are released back to the wallet due to an authorization reversal, expiration, or when the authorization is cleared	issuing-authorization	Authorization release {Merchant Name}
issuing-auth-hold	Funds are reserved on the wallet balance due to an approved authorization	issuing-authorization	Authorization hold {Merchant Name}

*Card issuing is currently in a closed beta. Contact Moov for more information.

Webhooks

You can subscribe to the walletTransaction.updated webhook event to get real-time updates on pending or completed transactions. Below is an example of an event for a completed transaction:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
  "eventID": "14980a04-2e32-4921-a771-4959a36534a6",
  "type": "walletTranscation.updated", 
  "data": {
    "accountID": "51015d0d-8dca-49a0-ba70-abfed073f785",
    "walletID": "51015d0d-8dca-49a0-ba70-abfed073f785",
		"transactionID": "51015d0d-8dca-49a0-ba70-abfed073f785",
    "status": "completed",
    },
  },
  "createdOn": "2021-09-02T13:57:50.762679289Z"
}

View transactions via API

Provide the accountID and walletID path parameters to the following endpoints to view wallet transactions for an account. Retrieving a specific wallet transaction additionally requires the transactionID.

Retrieve a wallet transaction - Gets a specific wallet transaction
List wallet transactions - Lists all transactions associated with a wallet

An account ID (also referred to as X-Account-ID) can be found in the Dashboard by navigating to Settings > Business details. Your account ID will be listed at the top of the Business details section and you can copy it to your clipboard.

Navigate to the Wallet section of the Dashboard and click the menu option in the wallet summary section. You'll be able to copy the wallet ID to your clipboard. You can also retrieve a wallet ID by providing accountID to the list payment methods GET endpoint.

A transaction ID can be found by navigating to Wallet in the Dashboard and clicking on a transaction to open the details. In the details modal, the transaction ID can be copied to your clipboard. You can also retrieve a transaction ID by passing accountID and walletID to the list transactions GET endpoint.

You can achieve a faster response by restricting the data with the optional start and end date time parameters.

Adjustments

There are one-off scenarios where Moov may make an immediate adjustment to a wallet’s balance. Some examples include partial chargebacks, fee adjustments, or corrections from transaction processing. You’ll receive a walletTransaction.updated webhook notification once the adjustment is made. More details about the adjustment can be found in the wallet transaction memo and the source type will link to the adjustmentID.

To retrieve a specific wallet adjustment or list all adjustments for a specific wallet, you can use the endpoints listed below. You'll need to pass the walletID to each endpoint, and to retrieve a specific adjustment, you'll also need to pass the adjustmentID.

Retrieve a wallet adjustment - Gets a specific wallet adjustment
List wallet adjustments - Lists all adjustments associated with a wallet

View transactions via Dashboard

Navigate to Wallet in the Dashboard to view transactions. See the Dashboard wallet guide for information.

Was this helpful?