Skip to main content
A credit account is a revolving line of credit that enables cardholders to borrow funds and have their purchases charged to the account to be repaid later. Marqeta’s credit platform currently supports consumer accounts, which are accounts held by individuals. On Marqeta’s credit platform, credit accounts are represented by the accounts resource. For the complete endpoint reference, see Credit Accounts. At the end of this guide, you should understand:
  • How an account is associated with other resources on Marqeta’s credit platform.
  • How an account is originated.
  • The lifecycle of an account and what each status represents.
  • The account factors that affect how much a cardholder can spend.
  • The config and usages objects.
  • Account management and servicing features, such as journal entries, statements, payments, disputes, and more.

Associated resources

Credit accounts are associated with the following resources on Marqeta’s credit platform. For a summary of all credit resources and how they relate to each other, see Summary of Credit Resources. For account management resources such as transitions, cards, journal entries, and rewards, see Account management features in this guide. For account servicing features such as statements, payments, delinquency, adjustments, disputes, and balance refunds, see Account servicing features in this guide.

Deprecation of credit products

This guide refers to the credit products feature, which is being deprecated and replaced by credit product policies, which is a part of the bundles feature. For more on policies and bundles in a credit program, see Credit Programs in the Marqeta Dashboard.

Relationships rules

The following rules apply to account-card relationships:
  • A credit account can be accessed by multiple credit cards.
  • A credit card can access only one credit account.
The following rules apply to card-cardholder user relationships:
  • A card can be held by only one user, known as a cardholder.
  • A cardholder can hold multiple cards.
The following rule applies to account-account holder user relationships:
  • An account can be held by only one user, known as the account holder.
  • A user can be the account holder on multiple accounts.

Account origination

Credit accounts are originated when an applicant accepts the terms of their approved application. Prior to that, you, Marqeta, and the issuing bank (the parties involved vary depending on your credit program) perform a series of steps that include offering an account to a prospective account holder, collecting applicant data and acknowledgments of pre-term files, and more. Your credit program must have an active bundle that is created and activated on the Marqeta Dashboard. For more, see Credit Programs in the Marqeta Dashboard. Once your credit program has an active bundle, prospective account holders can apply for a credit account associated with a bundle and receive a decision on their application. If the application is approved and the applicant accepts, Marqeta originates a new credit account on Marqeta’s credit platform.

Account origination process

The credit account origination process involves a series of steps that you, Marqeta, and the issuing bank perform using the Applications endpoints on Marqeta’s credit platform.
  • You offer a credit account based on an associated bundle to a prospective account holder.
  • The prospective account holder starts an application on your platform.
  • You display pre-terms files on the bundle to the applicant.
  • You collect applicant information and file acknowledgments and send them to Marqeta.
  • Marqeta sends the application data to the issuing bank.
  • The issuing bank renders a decision on the application.
  • You display post-terms files to the applicant that vary depending on whether the application is approved or rejected.
  • If approved, the applicant accepts or declines the credit account offered.
  • If the applicant accepts, Marqeta creates a new credit account on Marqeta’s credit platform with the applicant as the account holder.

The account lifecycle

A credit account can have one of the following statuses. Payments and rewards are always allowed, regardless of account status. If you want to block rewards and you are a bank, then do not use the /credit/accounts/{account_token}/rewards endpoint to create an account reward. If you want to block rewards and you are a brand contributor, then deactivate your reward account using the /credit/rewards/accounts/{reward_account_token} endpoint.

Status transitions

The following diagram outlines the possible transitions between account statuses.
Possible transitions between account states

Account substatuses

Use this endpoint to apply and remove a substatus for a credit account. Applying a substatus causes immediate downstream changes to the account. You can apply more than one active substatus to an account at the same time.
Note
If you are a Managed by Marqeta customer, please contact your Marqeta representative if you want to apply or remove a substatus from an account.
You can apply one of the following states to a substatus.

Account holder substatuses

Use this endpoint to apply and remove a substatus for a credit account holder or user.
Note
If you are a Managed by Marqeta customer, please contact your Marqeta representative if you want to apply or remove a substatus from an account holder.
When a substatus is applied to a user, all accounts where the user is the account holder will be impacted. Users can have multiple substatuses applied and active at one time, but there can be only one bankruptcy substatus active at one time. SCRA and DECEASED substatuses can be in one of the following states: BANKRUPTCY substatuses must follow the sequence of events described in the flow diagram following this table. If the substatus’ latest state is inactivated, then the substatus reverts to its previous state.
Sequence of events for bankruptcy

Cardholder’s spending power

The purchase balance, available balance, and credit limit determine how much a cardholder can spend.
  • Purchase balance - The current balance of the credit account.
  • Available credit - The amount of credit currently available to use.
  • Credit limit - The maximum balance an account can carry.

The config object

In the config object, you can configure an account’s billing cycle day, payment due day, fees, fee schedules, and more.

Important days

The values for important days on an account are inherited from the credit product policy in its associated bundle, or its associated credit product (to be deprecated – see more).
  • The billing cycle day is the day of month a new billing cycle begins. At the end of a billing cycle, you bill the account holder for any unpaid purchases and fees incurred during the billing cycle.
  • The payment due day is the day of month that payment for the previous billing cycle is due.

Fees

The fees configured on the policies in the account’s associated bundle, or associated credit product (to be deprecated – see more), can be defined on the account. For example, if a late payment fee is configured on the fee policy in its associated bundle, or associated credit product (to be deprecated – see more), then you can set the amount of the late payment fee on the account.
Note
If a fee was not configured on the policies in the account’s associated bundle, or associated credit product (to be deprecated – see more), then it will not be available on the account.
You can configure the following fees: Fee values are defined at the account level and must be a positive amount. There are no other limits on fee values. Only one penalty fee can be charged per billing cycle. For example, if an account holder makes two payments that bounce in the same billing cycle, only the first returned payment will incur the returned payment fee. If the same account holder then misses a payment in the same billing cycle, an additional late payment fee will not be charged.
Important
If you are setting the periodic fee value to a value that is not listed in the Terms Schedule, you must send a Change in Terms disclosure to affected account holders and collect their acknowledgment of the disclosure.
You can waive any fee when creating or updating an account by setting the fee value to 0.

Fee schedules

You can configure multiple fee schedules when creating or updating an account by adding multiple schedule objects to the config.fees object. If a fee schedule is in effect and you add a second fee schedule with a future effective_date, the second schedule’s value overrides that of the first when the second schedule’s effective date is reached. This method can be used to set the length of a fee waiver, for example. You can update a fee schedule by sending a PUT request to the /credit/accounts/{account_token} endpoint. If you are updating the value of a periodic fee and want the new value to be in effect the next time the fee is charged, the day of new effective_date must be prior to or on the same day that the fee is currently scheduled to be charged. For example, if a scheduled monthly $10 fee is charged on the 10th of every month and on March 9, you update the fee value to $15 effective March 11, the $15 won’t be charged until April 10. The cut-off time to update a fee schedule is midnight, 00:00 UTC. To ensure a new fee value goes into effect on a chosen date, specify that date as the effective_date before 00:00 UTC on the day prior. For example, if you want a fee to go into effect on April 2, 2024, specify 2024-04-02 as the effective date before 23:59:59 UTC on April 1, 2024.
Tip
If you miss the 00:00 UTC cut-off time, you can use the Adjustments endpoint to adjust any accidental fees that were applied to an account.

The usages object

In the usages object, you can define how a credit account is used and the types of balances permitted on the account. (NOTE: Currently, only PURCHASE balance is available.) Each usage type contains usage-based fees and rewards, such as FX fees, that are linked to the purchase balance.

Account management features

The Marqeta credit platform offers the following resources for account management.

Account servicing features

The Marqeta credit platform offers the following resources for account servicing.

Tutorial - Originate a credit account

This tutorial walks you through the steps needed to originate a credit account. For the complete account origination process, see Account origination in this guide.

Prerequisites

  • An active credit bundle - Before you begin, your credit program must have an active bundle that is created and activated on the Marqeta Dashboard.

Step 1 – Display pre-terms to your applicant

Pre-terms are files containing terms and conditions and disclosures that must be displayed to an applicant before their application is submitted. You can retrieve files from the bundle associated with the account being offered. The following files are pre-terms:
  • e-Disclosure – Acknowledges that the applicant agrees to receive disclosures electronically.
  • Privacy Policy – Explains how the information on an application is collected, handled, and processed.
  • Rewards Disclosure Pre-terms – Discloses detailed information on the rewards program for the account before the application is submitted.
  • Summary of Credit Terms (SOCT) – Outlines the interest rates, interest charges, and fees associated with the account.
To retrieve pre-terms:
1
Send a GET request to the /credit/applications/files endpoint with the bundle_token included.
2
Several files are returned in the response. Display only the pre-terms to the applicant:
  • E_DISCLOSURE
  • PRIVACY_POLICY
  • REWARDS_DISCLOSURE_PRE_TERMS
  • SOCT
3
In the response, copy the tracking_token for each file displayed. This token tracks the acknowledgment that the applicant has seen the file.

Step 2 – Create an application

After displaying pre-terms to your applicant, collect applicant data and create an application. To create an application, send a POST request to the /credit/applications endpoint with at least the following fields included:
  • token – Set the value to the unique identifier of the application.
  • user_token – Set the value to the unique identifier of the applicant.
  • bundle_token – Set the value to the unique identifier of the bundle associated with the application.
  • soct_tracking_token – Paste the tracking token of the SOCT copied from the previous step.
  • privacy_policy_tracking_token – Paste the tracking token of the Privacy Policy copied from the previous step.
  • e_disclosure_tracking_token – Paste the tracking token of the e-Disclosure copied from the previous step.
  • rewards_disclosure_pre_terms_tracking_token – Paste the tracking token of the Rewards Disclosure Pre-terms copied from the previous step.
  • residence_type – Set to OWN, RENT, or OTHER, depending on the applicant’s residence situation.
  • monthly_mortgage_or_rent – Set the value to the monthly amount of the applicant’s mortgage or rent.
  • total_annual_income – Set the value to the total amount of the applicant’s annual income.
  • primary_income_source – Set to EMPLOYED, UNEMPLOYED, SELF_EMPLOYED, or OTHER, depending on the applicant’s primary income source.
  • any_non_taxable_income – Set to true or false, depending on if the applicant has a non-taxable income source.
Initially, the response shows the application in a CREATED state. As the application transitions into other states, Marqeta sends webhook notifications containing application data. If a decision on the application has been rendered, the decision_model object contains the data that influenced the decision. For more on the event types that trigger a notification, see Credit application transition events. For more on webhooks, see About Webhooks. You can retrieve application data at any time by sending a GET request to the /credit/applications/{application_token} endpoint. For more, see Retrieve application. A credit account is originated when the applicant accepts an approved application, which transitions the application state from APPROVED to ACCEPTED.

Tutorial - Create a credit account

Note
This tutorial guides you through the process of onboarding a credit account if you are creating a credit account from a credit product (to be deprecated – see more). In all other cases, credit accounts are originated after completing the application process.
This tutorial walks you through creating a credit account and card.

Step one: Obtain a user token

Obtain an existing user token by sending a GET request to /users. For details, see the Users API reference.

Step two: Create a credit account

Create the credit account and customize its attributes and behaviors. Send a POST request to the /credit/accounts endpoint with at least the following fields included:
  • token — Set the value to a unique identifier of the account.
  • name — Set the value to the name of the account.
  • bundle_token - Set to the value of the associated bundle. OR credit_product_token (to be deprecated – see more) and external_offer_id — Set to the value of the associated credit product token and external offer id.
  • account_holder_token — Set to the value of the associated account holder’s token.
  • credit_limit — Set to the value of the maximum balance the account can carry.
  • The config object — Include the following fields:
    • billing_cycle_day — Set to the value of 1.
    • payment_due_day — Set to the value of 31.
    • The fees array — For each fees object, include the following fields:
      • type — Set the value to the fee type, either LATE_PAYMENT_FEE, RETURNED_PAYMENT_FEE, ANNUAL_FEE, or MONTHLY_FEE.
      • The schedule array — For each schedule object, include the following fields:
        • method — Set the value to FLAT.
        • value — Set the value to the fee amount.
  • The usages array — For each usages object, include the following fields:
    • type — Set the value to PURCHASE.
    • The aprs array — For each aprs object, include the following fields:
      • type — Set to the value of GO_TO.
      • The schedule array — For each schedule object, set the value field to the APR value, 1-100.
The following code block shows a sample account as it would appear in a POST request:
JSON

Step three: Create a credit card

Create a credit card to use to make purchases using the account’s available balance. Send a POST request to the /credit/accounts/{account_token}/cards endpoint with at least the following fields included:
  • token — Set the value to a unique identifier of the credit card.
  • card_product_token — Set to the value of the associated card product’s token.
  • user_token — Set to the token value of the user defined in step one.
Tip
This links the credit card to the account. To further configure the newly created card, send a PUT request to the /cards endpoint. For more, see Update card.
The following code block shows a sample credit card as it would appear in a POST request:
JSON

Step four: Update a credit account (Optional)

You can update an account’s fees and APRs’ type and schedule. You can use schedules to update usage APRs and config fees. You must pass the effective_date, which can be either back-dated or future-dated. Each update to schedules replaces a prior schedule in effect on the credit account. Send a PUT request to the /credit/accounts/{token} endpoint with the fields you want to change in the config object or usages objects set to the values you want. You can change the following fields:
  • config.fees.type
    • config.fees.schedule.method
    • config.fees.schedule.value
    • config.fees.schedule.effective_date
  • usages.type
    • usages.aprs.type
    • usages.aprs.schedule.value
    • usages.aprs.schedule.effective_date
The following code block shows a sample credit account update as it would appear in a PUT request:
JSON

Step five: Update account status (Optional)

Send a POST request to the credit/accounts/{account_token}/accounttransitions endpoint with the status field set to ACTIVE, SUSPENDED, TERMINATED, or CHARGE_OFF. For more on account statuses, see Status earlier on this page.