About Credit Account Ledger Entries

Warning
This page is currently deprecated and the functionality it describes will soon be unavailable. To learn more, contact your Marqeta representative.

This feature will be replaced by journal entries. For documentation on journal entries, see:

About Credit Account Journal Entries - Developer guide
Journal Entries - API reference
Credit journal entry event types - Webhook notifications

A credit account ledger entry is a record of an entry made on a credit account ledger, such as a purchase transaction, fee, adjustment, and more. Ledger entries originate when a ledger entry event occurs, such as a cardholder making a purchase, which creates purchase ledger entry, or an account holder making a payment past due, which creates a late payment fee ledger entry. On Marqeta’s credit platform, you can retrieve ledger entries on a credit account by using the /credit/accounts/{account_token}/ledgerentries endpoint. For the complete endpoint reference, see Credit Account Ledger Entries. At the end of this guide, you should understand:

What ledger entries are and how they originate.
What the ledger entry groups.
Each ledger entry group’s details and event types.

Ledger entry statuses

Ledger entries can have one of two statuses.

PENDING – The ledger entry is pending; the account’s available credit is temporarily decreased in the ledger entry amount.
POSTED – The ledger entry is posted to the account; the account balance is increased in the ledger entry amount.

Ledger entry groups

Every ledger entry belongs to a group, which is represented by the group field and useful for categorizing ledger entries. Ledger entries can belong to one of the following groups:

PURCHASE
FEE
REWARD
INTEREST
PAYMENT
ADJUSTMENT
BALANCE_REFUND
ORIGINAL_CREDIT

For more on each group, see their respective sections in this guide.

Ledger entry details

Each ledger entry contains a detail object, which is represented by detail_object and contains fields specific to the ledger entry’s group. These fields vary based on the group. For example, a ledger 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 ledger entry belonging to the reward group won’t return purchase details but rather, reward details, which are fields relevant to rewards. Each ledger entry also contains the detail_token field, which identifies a ledger entry’s details and populates fields in detail_object with values specific to that ledger entry.

Purchases

When a cardholder makes a purchase, a ledger entry belonging to the PURCHASE group is created on the credit account.

Purchase details

When retrieving a purchase ledger entry, purchase details are the fields returned in the detail_object. These fields come from the card network and are conditionally returned based on the ledger entry’s type. For more on these fields, see Transactions. The following code sample shows a ledger entry’s detail_object containing purchase details for an authorization clearing:

JSON

{
    "detail_object": {
        "type": "authorization.clearing",
        "state": "COMPLETION",
        "identifier": "6457",
        "token": "detail_token_645736",
        "user_token": "user_token4632",
        "acting_user_token": "user_token4632",
        "card_token": "my_credit_card_token7794",
        "preceding_related_transaction_token": "ledger_entry_token2460",
        "gpa": {
            "currency_code": "USD",
            "ledger_balance": 61.70,
            "available_balance": 0.00,
            "credit_balance": 0.00,
            "pending_credits": 0.00,
            "impacted_amount": -9.11,
            "balances": {
                "USD": {
                    "currency_code": "USD",
                    "ledger_balance": 61.70,
                    "available_balance": 0.00,
                    "credit_balance": 0.00,
                    "pending_credits": 0.00,
                    "impacted_amount": -9.11
                }
            }
        },
        "gpa_order": {
            "token": "gpa_order_token2c2c5",
            "amount": 9.11,
            "created_time": "2021-09-25T20:59:43Z",
            "last_modified_time": "2021-09-26T11:53:47Z",
            "transaction_token": "transaction_token42352a",
            "state": "COMPLETION",
            "response": {
                "code": "0000",
                "memo": "Approved or completed successfully"
            },
            "funding": {
                "amount": 9.11,
                "source": {
                    "type": "programgateway",
                    "token": "**********oken",
                    "active": true,
                    "name": "My Funding Source",
                    "is_default_account": false,
                    "created_time": "2021-06-22T18:41:14Z",
                    "last_modified_time": "2021-06-22T18:41:14Z"
                }
            },
            "funding_source_token": "**********oken",
            "jit_funding": {
                "token": "jit_funding_token43a3",
                "method": "pgfs.authorization.capture",
                "user_token": "user_token4632",
                "acting_user_token": "user_token4632",
                "amount": 9.11,
                "original_jit_funding_token": "jit_funding_token4be7"
            },
            "user_token": "user_token4632",
            "currency_code": "USD"
        },
        "duration": 378,
        "created_time": "2021-09-26T11:53:46Z",
        "user_transaction_time": "2021-09-25T20:59:43Z",
        "settlement_date": "2021-09-26T00:00:00Z",
        "request_amount": 9.11,
        "amount": 9.11,
        "currency_conversion": {
            "network": {
                "original_amount": 9.11,
                "conversion_rate": 1.000000,
                "original_currency_code": "840"
            }
        },
        "issuer_interchange_amount": 0.191310,
        "currency_code": "USD",
        "approval_code": "946791",
        "response": {
            "code": "0000",
            "memo": "Approved or completed successfully"
        },
        "network": "VISA",
        "subnetwork": "VISANET",
        "acquirer_fee_amount": 0,
        "acquirer": {
            "system_trace_audit_number": "000000"
        },
        "fees": [
            {
                "type": "INTERCHANGE_FEE",
                "amount": 0.191310,
                "credit_debit": "C"
            }
        ],
        "user": {
            "metadata": {
                "notification_email": "hello@myemail.com"
            }
        },
        "card": {
            "last_four": "4489",
            "metadata": {}
        },
        "issuer_received_time": "2021-09-26T11:53:46.886Z",
        "issuer_payment_node": "042f97a3458b59e3cce0269f66e864d8",
        "network_reference_id": "000218552461989029",
        "clearing_record_sequence_number": "00",
        "batch_number": "2021048291031352",
        "acquirer_reference_data": "43551063958600534001332",
        "card_acceptor": {
            "mid": "000555600244811",
            "mcc": "5814",
            "name": "SWEET TREATS 0484",
            "city": "OAKLAND",
            "state": "CA",
            "postal_code": "94612",
            "country_code": "US"
        },
        "pos": {
            "terminal_id": "00000101",
            "pin_present": false,
            "partial_approval_capable": false,
            "purchase_amount_only": false,
            "is_recurring": false,
            "is_installment": false
        },
        "transaction_metadata": {
            "payment_channel": "OTHER"
        },
        "network_metadata": {
            "product_id": "VISA_TRADITIONAL",
            "program_id": ""
        }
    }
}

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
refund.authorization
authorization.clearing
authorization.reversal
authorization.advice
authorization.reversal.issuerexpiration
refund.authorization.reversal
refund.authorization.clearing
refund
pindebit
pindebit.authorization.clearing
pindebit.refund

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

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 ledger entry belonging to the INTEREST group is created on the account. You can configure interest calculation during credit product creation. For more, see Creating a credit product in Credit Products in the Marqeta Dashboard.

Interest details

When retrieving an interest ledger entry, interest details are the fields that are returned in the detail_object, including interest charge calculation data. For field descriptions, see the Retrieve account ledger entry response fields. The following code sample shows a ledger entry’s detail_object containing interest details:

JSON

{
    "detail_object": {
        "token": "detail_token_96749",
        "account_token": "my_account_token_12",
        "statement_token": "statement_token_75b",
        "statement_opening_date": "2021-07-01T04:00:00.000Z",
        "statement_closing_date": "2021-08-01T03:59:59.999Z",
        "statement_balance": 208.93,
        "average_daily_balance": 181.67,
        "goto_apr": 14.99,
        "daily_periodic_rate": 0.00041068,
        "days_in_billing_cycle": 31,
        "interest_amount": 2.31,
        "currency_code": "USD",
        "created_date": "2021-08-01T07:00:19.755Z",
        "updated_date": "2021-08-01T07:00:19.755Z"
    }
}

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

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Fees

When the conditions that cause a fee to be applied on a credit account are met, a ledger entry belonging to the FEES 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.
An annual fee is applied when a periodic fee with an annual frequency is configured on a credit program.
A monthly fee is applied when a periodic fee with an monthly frequency is configured on a credit program.

When creating a credit product, you can select the fees that you want to include on the product. Then, when creating a credit account based on that product, you can define the selected fees’ schedule, method, value, and effective date. You cannot define fees that you did not select during product creation, and only defined fees can be entries on the credit account ledger, provided the conditions to apply the fee are met. For more on including fees during credit product and account creation, see Creating a credit product in Credit Products in the Marqeta Dashboard and Create account in the Credit Accounts API reference.

Fee details

When retrieving a fee ledger entry, fee details are the fields that are returned in the detail_object. For field descriptions, see the Retrieve account ledger entry response fields. The following code sample shows a ledger entry’s detail_object containing fee details:

JSON

{
    "detail_object": {
        "token": "detail_token_11221",
        "account_token": "my_account_token_12",
        "type": "LATE_PAYMENT_FEE",
        "method": "FLAT",
        "value": 25.0000,
        "currency_code": "USD",
        "amount": 15.00,
        "applied_to_amount": null,
        "description": "Late Payment Fee",
        "created": "2021-07-01T07:00:24.239Z"
    }
}

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.annual
account.fee.latepayment
account.fee.minimum.interest
account.fee.monthly
account.fee.returnpayment

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Rewards

When the conditions that cause a reward to be applied on a credit account are met, a ledger entry belonging to the REWARD 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.

You can create a reward using the /credit/accounts/{account_token}/rewards endpoint. For the endpoint reference, see Account Rewards.

Reward details

When retrieving a reward ledger entry, reward details are the fields that are returned in the detail_object. For field descriptions, see the Create account reward response fields. The following code sample shows a ledger entry’s detail_object containing reward details:

JSON

{
    "detail_object": {
        "token": "detail_token_76001",
        "account_token": "my_account_token_12",
        "type": "CASH_BACK",
        "description": "$20 reward",
        "currency_code": "USD",
        "amount": 20.00,
        "applied_to_amount": null,
        "method": null,
        "value": null,
        "note": "string",
        "updated_time": "2021-09-03T22:53:57.895Z",
        "created_time": "2021-09-03T22:53:57.895Z"

    }
}

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

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Payments

When an account holder makes a payment toward their credit account balance, a ledger entry belonging to the PAYMENT group is created on the account. You can create a payment using the /credit/accounts/{account_token}/payments endpoint. For the endpoint reference, see Payments. For the guide, see the About Credit Account Payments.

Payment details

When retrieving a payment ledger entry, payment details are the fields that are returned in the detail_object. For field descriptions, see the Retrieve account payment response fields. The following code sample shows a ledger entry’s detail_object containing payment details:

JSON

{
    "detail_object": {
        "token": "detail_token_2551",
        "account_token": "my_account_token_12",
        "method": "CHECK",
        "payment_source_token": null,
        "amount": 25.00,
        "currency_code": "USD",
        "status": "COMPLETED",
        "description": "minimum payment",
        "hold_days": 5,
        "hold_end_time": "2021-09-16T23:01:18.316Z",
        "is_manually_released": false,
        "on_hold": true,
        "created_time": "2021-09-09T23:01:18.316Z",
        "updated_time": "2021-09-09T23:01:18.347Z",
        "transitions": [
            {
                "token": "my_transition_token1234",
                "account_token": "my_account_token_12",
                "payment_token": "my_payment_25",
                "status": "COMPLETED",
                "refund_details": null,
                "created_time": "2021-09-09T23:01:18.323Z"
            }
        ]
    }
}

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

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial. For more on payments, see About Credit Account Payments.

Adjustments

When the amount of an existing ledger entry or the account balance is adjusted, a ledger entry belonging to the ADJUSTMENT group is created on the credit account. There are many reasons to adjust a ledger entry or account balance, including provisional credits for disputes, returned or canceled payments, waived fees, account write-offs, and more. For more on provisional credits and adjustments for disputes, see About Credit Account Disputes. You can adjust the amount of a ledger entry or account balance using the /credit/accounts/{account_token}/adjustments endpoint. To adjust a ledger entry amount, pass the ledger entry’s token in the original_ledger_entry_token field. To adjust an account balance, do not pass original_ledger_entry_token and pass a negative value in amount, which is the adjustment amount. For the endpoint reference, see Adjustments.

Adjustment details

When retrieving an adjustment ledger entry, adjustment details are the fields that are returned in the detail_object. For field descriptions, see the Retrieve account adjustment response fields. The following code sample shows a ledger entry’s detail_object containing adjustment details:

JSON

{
    "detail_object": {
        "token": "detail_token_45362",
        "account_token": "my_account_token_12",
        "type": "INTEREST",
        "original_ledger_entry_token": null,
        "external_adjustment_id": null,
        "detail_token": null,
        "adjustment_detail_object": null,
        "related_detail_token": null,
        "related_detail_object": null,
        "amount": -100.00,
        "currency_code": "USD",
        "description": "interest adjustment",
        "note": null,
        "reason": "OTHER"
    }
}

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

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Balance refunds

When an account holder’s credit account balance is negative and a balance refund is issued to bring the balance to, or closer to, 0, a ledger entry belonging to the BALANCE_REFUND group is created on the credit account. You can create a balance refund using the /credit/accounts/{account_token}/creditbalancerefunds endpoint. For the endpoint reference, see Balance Refunds.

Balance refund details

When retrieving a balance refund ledger entry, balance refund details are the fields that are returned in the detail_object. For field descriptions, see the Create balance refund response fields. The following code sample shows a ledger entry’s detail_object containing balance refund details:

JSON

{
    "detail_object": {
        "token": "detail_token_77804",
        "account_token": "my_account_token_12",
        "status": "COMPLETED",
        "method": "CHECK",
        "amount": 0,
        "description": "credit balance refund",
        "created_time": "2021-07-14T20:17:28Z",
        "updated_time": "2021-07-14T20:17:28Z"
    }
}

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.balance.refund

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Original credit transactions (OCT)

When the card network pushes an OCT payment that disburses funds to a credit card, a ledger entry belonging to the ORIGINAL_CREDIT group is created on the credit account.

OCT details

When retrieving an OCT ledger entry, OCT details are the fields returned in the detail_object. These fields come from the card network and are conditionally returned based on the ledger entry’s type. For more, see the original_credit object in Transactions. The following code sample shows a ledger entry’s detail_object containing OCT details:

JSON

{
  "detail_object": {
    "type": "original.credit.auth_plus_capture",
    "state": "COMPLETION",
    "token": "ledger_entry_token77104c",
    "user_token": "user_token4d090",
    "acting_user_token": "user_token4d090",
    "card_token": "card_token8445",
    "original_credit": {
      "transaction_type": "disbursement"
    },
    "gpa": {
      "currency_code": "USD",
      "ledger_balance": 10,
      "available_balance": 10,
      "credit_balance": 0,
      "pending_credits": 0,
      "impacted_amount": 10,
      "balances": {
        "USD": {
          "currency_code": "USD",
          "ledger_balance": 10,
          "available_balance": 10,
          "credit_balance": 0,
          "pending_credits": 0,
          "impacted_amount": 10
        }
      }
    },
    "duration": 199,
    "created_time": "2020-07-08T23:47:04Z",
    "user_transaction_time": "2020-07-08T23:47:04Z",
    "request_amount": 10,
    "amount": 10,
    "currency_code": "USD",
    "approval_code": "206645",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "merchant": {
      "name": "John Doe Merchant Inc.",
      "active": true,
      "contact": "John D. Doe",
      "contact_email": "jdoe@domain.com",
      "longitude": 0,
      "latitude": 0,
      "address1": "180 Grand Avenue",
      "address2": "Suite 2303",
      "city": "Oakland",
      "state": "CA",
      "zip": "94612",
      "country": "USA",
      "token": "merchant_token623dd37",
      "partial_auth_flag": true,
      "created_time": "2020-02-14T00:57:02Z",
      "last_modified_time": "2020-02-14T00:57:02Z"
    },
    "store": {
      "name": "Aegis Fleet Services",
      "active": false,
      "longitude": 0,
      "latitude": 0,
      "address1": "111 Main St",
      "city": "Berkeley",
      "state": "CA",
      "zip": "94702",
      "token": "store_token17500",
      "partial_auth_flag": true,
      "mid": "11111",
      "merchant_token": "merchant_token623dd37",
      "partial_approval_capable": true,
      "keyed_auth_cvv_enforced": false,
      "created_time": "2020-02-14T01:18:38Z",
      "last_modified_time": "2020-02-14T01:18:38Z"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
      "institution_id_code": "05779900106",
      "retrieval_reference_number": "726213433770",
      "system_trace_audit_number": "881236"
    },
    "fees": [
      {
        "type": "ISSUER_LOAD_SURCHARGE_FEE",
        "amount": 0
      }
    ],
    "user": {
      "metadata": {}
    },
    "card": {
      "last_four": "3201",
      "metadata": {}
    },
    "issuer_received_time": "2020-07-08T23:47:04.577Z",
    "issuer_payment_node": "715de90f8dd6eeb2d87251dd691d7de2",
    "card_acceptor": {
      "mid": "11111",
      "mcc": "00",
      "country_code": "USA"
    },
    "pos": {
      "terminal_id": "TR100000",
      "partial_approval_capable": false,
      "purchase_amount_only": false,
      "is_recurring": false
    }
  },
    "raw_iso8583": {
      "0": "2210",
      "2": "1111119311153201",
      "3": "260000",
      "4": 10,
      "5": 10,
      "7": "0708234704",
      "11": "881236",
      "12": "114704",
      "13": "0708",
      "14": "2307",
      "15": "0708",
      "17": "0708",
      "22": "10000000020000000100000001000000",
      "26": "00",
      "32": "05779900106",
      "33": "13747132476",
      "37": "726213433770",
      "38": "206645",
      "39": "0000",
      "41": "TR100000",
      "42": "11111",
      "43": {
        "7": "840"
      },
      "44": {
        "1": "Approved or completed successfully",
        "3": "00",
        "4": "Approved or completed successfully"
      },
      "48": "OCT        07012020",
      "50": "840",
      "54": "00028402C00000000100000018402C000000001000",
      "58": "00000000022",
      "59": "0000000",
      "63": "VISA",
      "112": {
        "101": "10.00",
        "102": "10.00",
        "103": "840"
      },
      "113": {
        "2": "106",
        "32": "VISANET",
        "35": "API",
        "42": "DISBURSEMENT",
        "46": "true"
      },
      "123": "123 Main St."
    }
}

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

For more on events, including event descriptions, see Credit ledger entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Guides

​Ledger entry statuses

​Ledger entry groups

​Ledger entry details

​Purchases

​Purchase details

​Purchase events

​Interest

​Interest details

​Interest event

​Fees

​Fee details

​Fee events

​Rewards

​Reward details

​Reward events

​Payments

​Payment details

​Payment events

​Adjustments

​Adjustment details

​Adjustment events

​Balance refunds

​Balance refund details

​Balance refund event

​Original credit transactions (OCT)

​OCT details

​OCT events

Ledger entry statuses

Ledger entry groups

Ledger entry details

Purchases

Purchase details

Purchase events

Interest

Interest details

Interest event

Fees

Fee details

Fee events

Rewards

Reward details

Reward events

Payments

Payment details

Payment events

Adjustments

Adjustment details

Adjustment events

Balance refunds

Balance refund details

Balance refund event

Original credit transactions (OCT)

OCT details

OCT events