/credit/accounts/{account_token}/journalentries endpoint. For the complete endpoint reference, see Journal Entries.
At the end of this guide, you should understand:
- What journal entries are and how they originate.
- What the journal entry groups.
- Each journal entry group’s details and event types.
Journal entry statuses
Journal entries can have one of two statuses.-
PENDING— The journal entry affects the account’s pending balance. The account’s available credit is temporarily decreased in the journal entry amount, unless the journal entry is an initiated dispute or initiated payment. -
POSTED— The journal entry is posted to the account and the account balance is increased in the journal entry amount. In the case of a dispute resolved in the account holder’s favor or a completed payment, the hold on available credit is released.
Journal entry groups
Every journal entry belongs to a group, which is represented by thegroup field and useful for categorizing journal entries.
Journal entries can belong to one of the following groups:
-
PURCHASE -
REFUND -
DISPUTE -
FEE -
REWARD -
INTEREST -
PAYMENT -
ADJUSTMENT -
BALANCE_REFUND -
ORIGINAL_CREDIT
Differences between the state and status fields
Although thestatus and state fields may appear similar at first, they are not related to each other.
status is passed directly to, or returned directly from, the /credit/accounts/{account_token}/journalentries endpoint and indicates how the journal entry impacts the present or future account balance. Every journal entry type maps to an immutable status value. For example, status fields for journal entries of the type authorization are always PENDING, those of type authorization.clearing are always POSTED, and so on. Every time a journal entry of a given type is retrieved, it includes the original status value with which it was created, and that value is the same as every other journal entry of that type.
state is a field of the detail_object that is returned with a journal entry when it is requested from the endpoint. It represents the state of the journal entry at a point in time, such as whether a purchase is PENDING or DECLINED or whether a dispute is ACTIVE or REVERSED. Unlike the value of the status field, the value of the state field can change over time for many types of journal entries. For example, a journal entry with a type of authorization might have a detail_object.state value of PENDING when initially retrieved, but that value might change to CLEARED when the journal entry is retrieved again.
Journal entry details
Each journal entry contains a detail object, which is represented bydetail_object and contains fields specific to the journal entry’s group. These fields vary based on the group.
For example, a journal entry belonging to the purchase group returns purchase details, which are fields that come from the card network and are relevant to purchase transactions. A journal entry belonging to the reward group will not return purchase details but rather, reward details, which are fields relevant to rewards.
Each journal entry also contains the detail_token field, which identifies a journal entry’s details and populates fields in detail_object with values specific to that journal entry.
Time fields
The meanings of thecreated_time, request_time, and impact_time fields on a journal entry depend on the journal entry’s group. These fields are not present for journal entries with certain status values.
In this section, you will learn:
- What these fields mean for different journal entry groups
-
For which
statusvalues these fields are returned empty.
Different meanings of impact_time by transaction type
The meaning ofimpact_time differs between purchases and purchase authorization clearings. In purchases, the impact_time field represents the time when the purchase was authorized. In purchase authorization clearings, impact_time refers to the settlement time. In both cases, the impact time is the time at which an account balance is affected. For a purchase, the impact time is typically the time at which the available credit changes. For a purchase authorization clearing, the impact time is the time at which the credit balance changes.
Conditions where blank fields are returned
The three fields discussed in this section,created_time, request_time, and impact_time, as well as two others, token and id, are returned empty when status is CLEARED, DECLINED, or ERROR.
Purchases
When a cardholder makes a purchase, a journal entry belonging to thePURCHASE group is created on the credit account. Merchants may send purchases as single-message or dual-message transactions. For more, see Transactions in the payments ecosystem in the About Transactions guide.
Purchase details
When retrieving a purchase journal entry, purchase details are the fields returned in thedetail_object. These fields come from the card network and are conditionally returned based on the journal entry’s type. For more on these fields, see Transactions.
The following code sample shows a journal entry’s detail_object containing purchase details for an authorization clearing:
JSON
Purchase events
Marqeta’s credit platform sends webhook notifications when purchase authorizations and purchase authorization clearings occur. You can configure a webhook to capture the following purchase events:-
authorization -
authorization.incremental -
authorization.clearing -
authorization.reversal -
authorization.advice -
authorization.reversal.issuerexpiration -
pindebit -
pindebit.authorization.clearing
Purchase refunds
When a merchant initiates a purchase refund, a journal entry belonging to theREFUND group is created on the credit account. Merchants may send refunds as single-message or dual-message transactions. For more, see Transactions in the payments ecosystem in the About Transactions guide.
Purchase refund details
When retrieving a purchase refund journal entry, refund details are the fields returned in thedetail_object. These fields come from the card network and are conditionally returned based on the journal entry’s type. For more on these fields, see Transactions.
The following code sample shows a journal entry’s detail_object containing purchase details for a refund:
JSON
Purchase refund events
Marqeta’s credit platform sends webhook notifications when purchase refunds occur. You can configure a webhook to capture the following refund events:-
pindebit.refund -
refund -
refund.authorization -
refund.authorization.reversal -
refund.authorization.clearing -
refund.authorization.reversal.issuerexpiration
Interest
When the conditions that cause an interest charge to be applied on a credit account are met, such as a cardholder carrying a balance from the previous month at the end of a billing period, a journal entry belonging to theINTEREST group is created on the account.
You can configure interest calculation during the creation of a credit product policy. For more, see Creating a credit product policy in the Credit Programs in the Marqeta Dashboard guide.
Interest details
When retrieving an interest journal entry, interest details are the fields that are returned in thedetail_object, including interest charge calculation data. For field descriptions, see the Retrieve account journal entry response fields.
The following code sample shows a journal entry’s detail_object containing interest details:
JSON
Interest event
Marqeta’s credit platform sends webhook notifications when interest charges are applied on a credit account. You can configure a webhook to capture this interest event:account.interest
Fees
When the conditions that cause a fee to be applied on a credit account are met, a journal entry belonging to theFEES group is created on the account.
- A late payment fee is applied when a payment is made past the payment due date.
- A returned payment fee is applied when a completed payment is returned.
- A minimum interest fee is applied when an account is charged interest that is lower than the minimum interest amount.
Fee details
When retrieving a fee journal entry, fee details are the fields that are returned in thedetail_object. For field descriptions, see the Retrieve account journal entry response fields.
The following code sample shows a journal entry’s detail_object containing fee details:
JSON
Fee events
Marqeta’s credit platform sends webhook notifications when late payment, returned payment, and minimum interest fees are applied on a credit account. You can configure a webhook to capture the following fee events:-
account.fee.payment.late -
account.fee.payment.returned -
account.fee.interest.minimum
Rewards
When the conditions that cause a reward to be applied on a credit account are met, a journal entry belonging to theREWARD group is created on the account.
- A cash back reward is applied as cash back statement credits when a cardholder makes a qualifying purchase that results in cash back.
/credit/accounts/{account_token}/rewards endpoint. For the complete endpoint reference, see Account Rewards.
Reward details
When retrieving a reward journal entry, reward details are the fields that are returned in thedetail_object. For field descriptions, see the Create account reward response fields.
The following code sample shows a journal entry’s detail_object containing reward details:
JSON
Reward events
Marqeta’s credit platform sends webhook notifications when rewards are applied on a credit account. You can configure a webhook to capture the following reward events:account.reward.cashback
Payments
When an account holder makes a payment toward their credit account balance, a journal entry belonging to thePAYMENT group is created on the account.
You can create a payment using the /credit/accounts/{account_token}/payments endpoint. For the complete endpoint reference, see Payments.
For more on payments, see About Credit Account Payments.
Payment details
When retrieving a payment journal entry, payment details are the fields that are returned in thedetail_object. For field descriptions, see the Retrieve account payment response fields.
The following code sample shows a journal entry’s detail_object containing payment details:
JSON
Payment events
Marqeta’s credit platform sends webhook notifications when payment activity occurs on a credit account. You can configure a webhook to capture the following payment events:-
account.payment.pending -
account.payment.completed -
account.payment.returned -
account.payment.canceled -
account.payment.refunded
Disputes
When a purchase is disputed, a journal entry belonging to theDISPUTE group is created on the credit account.
You can create a dispute using the /credit/accounts/{account_token}/disputes endpoint. For the complete endpoint reference, see Credit Disputes.
For more on disputes, see About Credit Account Disputes.
Dispute details
When retrieving a dispute journal entry, dispute details are the fields that are returned in thedetail_object. For field descriptions, see the Retrieve account dispute response fields.
The following code sample shows a journal entry’s detail_object containing dispute details:
JSON
Dispute events
Marqeta’s credit platform sends webhook notifications when dispute events occur on a credit account. You can configure a webhook to capture the following dispute events:- account.dispute
- account.dispute.reversed
- account.dispute.won
- account.adjustment.lost
- account.adjustment.lost.graceperiod
Adjustments
When the amount of an existing journal entry or the account balance is adjusted, a journal entry belonging to theADJUSTMENT group is created on the credit account.
There are many reasons to adjust a journal entry or account balance, including interest adjustments due to returned or canceled payments, waived fees, account write-offs, and more.
You can adjust the amount of a journal entry or account balance by creating an adjustment using the /credit/accounts/{account_token}/adjustments endpoint.
To adjust a journal entry amount, pass the journal entry’s token in the original_journal_entry_token field. To adjust an account balance, which creates a general credit adjustment that does not affect a journal entry, do not pass original_journal_entry_token and pass a negative value in amount, which is the adjustment amount.
For the complete endpoint reference, see Adjustments.
Adjustment details
When retrieving an adjustment journal entry, adjustment details are the fields that are returned in thedetail_object. For field descriptions, see the Retrieve account adjustment response fields.
The following code sample shows a journal entry’s detail_object containing adjustment details:
JSON
Adjustment events
Marqeta’s credit platform sends webhook notifications when adjustments are applied on a credit account. You can configure a webhook to capture the following adjustment events:-
account.adjustment -
account.adjustment.purchase -
account.adjustment.purchase.graceperiod -
account.adjustment.fee -
account.adjustment.interest -
account.adjustment.reward
Credit balance refunds
When an account holder’s credit account balance is negative and a balance refund is issued to bring the balance closer to 0.00, a journal entry belonging to theBALANCE_REFUND group is created on the credit account.
You can create a balance refund using the /credit/accounts/{account_token}/creditbalancerefunds endpoint. For the complete endpoint reference, see Balance Refunds.
Balance refund details
When retrieving a balance refund journal entry, balance refund details are the fields that are returned in thedetail_object. For field descriptions, see the Create balance refund response fields.
The following code sample shows a journal entry’s detail_object containing balance refund details:
JSON
Balance refund event
Marqeta’s credit platform sends webhook notifications when balance refunds are issued on a credit account. You can configure a webhook to capture the following balance refund event:account.balancerefund
Original credit transactions (OCT)
When the card network pushes an OCT payment that disburses funds to a credit card, a journal entry belonging to theORIGINAL_CREDIT group is created on the credit account.
OCT details
When retrieving an OCT journal entry, OCT details are the fields returned in thedetail_object. These fields come from the card network and are conditionally returned based on the journal entry’s type. For more, see the original_credit object in Transactions.
The following code sample shows a journal entry’s detail_object containing OCT details:
JSON
OCT events
Marqeta’s credit platform sends webhook notifications when OCT events occur. You can configure a webhook to capture the following OCT events:-
original.credit.authorization -
original.credit.authorization.reversal -
original.credit.authorization.clearing -
original.credit.authpluscapture -
original.credit.authpluscapture.reversal