About Credit Account Disputes
A credit account dispute occurs when an account holder disagrees with a charge on their credit account. Marqeta enables you to manage the dispute process by performing tasks such as creating a dispute, retrieving information on a dispute, and updating the amount and status of a dispute in the credit system of record. Additionally, Marqeta issues provisional credits when a dispute is initiated and reverses those credits if the account holder is later found responsible for the disputed charge.
On Marqeta’s credit platform, you can create a dispute using the /credit/accounts/{account_token}/disputes endpoint.
For the complete endpoint reference, see Credit Disputes.
At the end of this guide, you should understand:
-
What a dispute is and what can be disputed.
-
What the different statuses of a dispute represent.
-
How certain dispute activities trigger the application of account and interest adjustments, including provisional credits.
-
What the dispute process entails.
-
What dispute events you can configure a webhook to capture.
What is a dispute?
Copy section link
A dispute is an investigation into the validity of a journal entry charge and whether the account holder is responsible for the charge. An account holder usually initiates a dispute when they believe a charge on their credit account is invalid. This can occur if the account holder:
-
Did not receive a product or service.
-
Was charged twice for the same product or service.
-
Was charged the wrong amount for a product or service.
-
Believes the product to be damaged, defective, or not as described.
-
Did not recognize the charge or business name on their statement.
-
Was the victim of fraud, card theft, or identity theft.
The dispute process
Copy section link
The dispute process begins when the account holder initiates a dispute.
-
The account holder disputes a purchase journal entry.
-
You create a dispute on Marqeta’s credit platform.
-
Marqeta issues a provisional credit to the account holder’s account by applying a credit account adjustment in the amount of the disputed purchase.
-
If the disputed purchase appears on the account during any prior billing periods that charged interest, Marqeta issues an additional interest credit by applying a credit interest adjustment to the account holder’s account.
-
If the dispute resolves in the account holder’s favor, you update the dispute status, along with the amount, to indicate that the account holder won. No further action is needed.
-
If the dispute resolves in the merchant’s favor, you update the dispute status, along with the amount, to indicate that the account holder lost. Marqeta reverses any provisional credits, including interest credits, previously issued by applying debit account adjustments.
-
If the dispute resolves in the merchant’s favor and interest would have accrued while the dispute was active, Marqeta recalculates interest and charges the interest amount to the account holder’s account by applying a debit interest adjustment.
What can be disputed?
Copy section link
Only authorization.clearing type journal entry events are eligible for dispute, which are purchase journal entries with a POSTED status.
Purchase journal entries in PENDING cannot be disputed until their status moves to POSTED.
Other journal entries cannot be disputed.
Only one dispute can be created per journal entry.
Dispute statuses
Copy section link
Disputes can have one of the following statuses:
| Name | Description |
|---|---|
|
The dispute is active and awaiting resolution. Disputes are active when a dispute has been created but a resolution has not yet been reached. |
|
The dispute has been reversed and is no longer active. Disputes are reversed when the dispute request has been withdrawn. |
|
The account holder won the dispute; the dispute resolved in the account holder’s favor. |
|
The account holder lost the dispute; the dispute resolved in the merchant’s favor. |
The dispute lifecycle
Copy section link
A purchase journal entry can be disputed if the status is POSTED and type is authorization.clearing.
Only one dispute can be created per journal entry token.
Once a dispute is created, the dispute status is ACTIVE.
This is the initial state.
Once a resolution is reached, the dispute status transitions to either REVERSED, AH_WON, or AH_LOST.
These are the end states.
A dispute cannot transition from an end state back to the initial state.
The following diagram outlines the possible transitions between states.
Account adjustments
Copy section link
During the dispute process, Marqeta may apply credit or debit adjustments on the credit account to which the disputed purchase journal entry belongs. A credit account adjustment reduces the account balance whereas a debit account adjustment increases the account balance.
Provisional credits
Copy section link
A provisional credit is a temporary credit issued to a credit account during the dispute process. Although provisional credits reduce the account balance, they do not increase the available credit until a dispute resolution is reached.
When an account holder initiates a dispute, Marqeta issues a provisional credit to the account holder’s account by applying a credit account adjustment in the amount of the disputed journal entry so that while the dispute is active, the account holder is not responsible for the disputed journal entry charge.
For example, if an account holder disputes a $100 purchase journal entry, Marqeta applies a -$100 credit account adjustment to the account holder’s account.
Interest credits
Copy section link
In the cases where the disputed journal entry appears on the account holder’s account during any prior billing periods where interest was charged, Marqeta recalculates interest and issues an interest credit per prior billing period by applying credit account adjustments to the account holder’s account. The amount of each credit account adjustment is the difference in interest when the disputed journal entry is included and then excluded from the billing period.
For example, if $15 of interest was charged for a prior billing period that includes the disputed journal entry, and then $11.50 of interest was recalculated when excluding the disputed journal entry from the same billing period, Marqeta applies a -$3.50 credit account adjustment to the account holder’s account.
Interest credits are not issued if interest was not charged in a prior billing period on which the disputed journal entry appears.
Dispute resolutions
Copy section link
A dispute can resolve in favor of the account holder or the merchant.
Account holder wins
Copy section link
If the account holder wins the dispute, any provisional credits, including interest credits, remain in their account, thereby increasing their available credit.
For example, if the account holder was issued a -$100 provisional credit and -$3.67 interest credit and then won the dispute, they keep the -$103.67 credits in their account, thereby increasing their available credit by $103.67.
Merchant wins
Copy section link
If the merchant wins the dispute, Marqeta reverses any provisional credits, including interest credits, that were issued when the dispute was initiated by applying debit account adjustments to the account holder’s account in the amount of the provisional credits previously issued.
Additionally, if interest would have accrued while the dispute was active, Marqeta recalculates that interest and charges the interest amount to the account holder’s account by applying debit interest adjustments.
For example, if the account holder was issued a -$100 provisional credit and -$3.67 interest credit and then lost the dispute, Marqeta applies a $100 debit account adjustment and $3.67 debit interest adjustment to their credit account so that the account holder is responsible for the disputed journal entry charges.
Additionally, if the same $100 disputed journal entry took 30 days to reach a resolution and that journal entry would have accrued a total of $1.67 interest during that time, Marqeta applies an additional $1.67 debit account adjustment to the account holder’s account so that the account holder is responsible for the interest that would have accrued on the disputed journal entry while the dispute was active.
Webhooks for dispute events
Copy section link
Marqeta’s credit platform sends webhook notifications when certain dispute activity occurs. You can configure a webhook to capture the following dispute events:
| Name | Description |
|---|---|
|
An account adjustment was applied for a purchase journal entry. |
|
An account adjustment was applied for an interest journal entry. |
For more on subscribing to webhook notifications, see the About Webhooks tutorial.
Tutorial
Copy section link
This tutorial walks through how to create and resolve a dispute.
Step one. Create a dispute
Copy section link
Send a POST request to the /credit/accounts/{account_token}/disputes endpoint with the following fields included:
-
token— Set the value to the unique identifier of the credit account on which the disputed journal entry exists. -
ledger_entry_token— Set the value to the unique identifier of the disputed journal entry. -
amount— Set the value to the amount of the disputed journal entry. -
category— Set the value to the category to which the dispute belongs, eitherFRAUD,AUTH,PROCESSING_ERROR, orCONSUMER_DISPUTE. -
notes— Set the value to any additional notes on the dispute, such as a dispute reason.
The following code block shows a sample dispute as it would appear in a POST request:
Upon dispute creation, Marqeta automatically issues any necessary provisional credits to the credit account.
Step two. Resolve a dispute
Copy section link
When a dispute resolution is reached, you must update the dispute amount and its status to indicate the outcome.
Send a POST request to the /credit/accounts/{account_token}/disputes/{dispute_token}/transitions endpoint with at least the following fields included:
-
amount— Set the value to the final amount of the dispute. -
status— Set the value to the new status of the dispute, depending on resolution, eitherREVERSED,AH_WON, orAH_LOST. For more on what each status represents, see the Dispute statuses section earlier in this guide.
The following code block shows a sample dispute update as it would appear in a POST request:
Upon dispute resolution, Marqeta automatically recalculates any necessary interest and applies account adjustments to the credit account.