/
10 minute read
January 6, 2023

About Credit Accounts

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 supports consumer accounts, which are accounts held by individuals. Credit accounts are originated when an applicant accepts the terms of their approved application.

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 a credit account is associated with other resources.

  • The relationship between a credit account, credit card, and user.

  • The characteristics of a credit account, such as its status, balance and credit, key days, fee and reward configurations, and more.

Associated resources

Credit accounts are associated with the following resources on Marqeta’s credit platform:

Name Description

Bundles

The configurations of the policies that make up a bundle determine the characteristics and attributes of accounts associated with the bundle, which is represented by the bundle_token. For more on policies and bundles, see Managing Credit Programs in the Marqeta Dashboard.

Applications

A credit account originates when Marqeta approves an application and the applicant accepts the approved application. The characteristics and attributes on an application are based off its associated bundle. Applications are represented by the application_token.

Credit products (to be deprecated - see more)

The configurations of a credit product on your external platform determine characteristics and attributes of associated credit accounts. Credit products are represented by the credit_product_token.

Account holder

The primary user responsible for the credit account is the account holder, who is represented by the user_token.

Credit cards

Cardholders can use credit cards to access the available balance on a credit account to make purchases. Credit cards are represented by the cards resource.

The characteristics of a credit account answer the following questions about associated users and cards:

  • Who is the account holder, the user responsible for the credit account?

  • How much credit is available for the card to access?

A note about credit products

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

Relationship 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 statuses

A credit account can have one of the following statuses.

Status Description and behavior

UNACTIVATED

The account is awaiting activation by the account holder.

ACTIVE

The account is active. The account holder and any authorized users can access the credit line.

SUSPENDED

The account is temporarily inactive. Its credit line cannot be accessed.

TERMINATED

The account is closed and permanently inactive. Its credit line cannot be accessed.

New purchases cannot be made.

Only updates to the late payment fee, returned payment fee, or APR can be made using the /credit/accounts/{account_token} endpoint.

Credits, such as refunds or original credit transactions (OCTs), may be allowed depending on whether the original transaction was made before the account status transitioned to this one.

New statements are only generated if the account is carrying a balance.

CHARGE_OFF

The account has an outstanding balance and is permanently inactive. Its credit line cannot be accessed.

New purchases cannot be made.

Updates to the account cannot be made.

Credits, such as refunds or original credit transactions (OCTs), may be allowed depending on whether the original transaction was made before the account status transitioned to this one.

New statements are not generated.

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 program using the /credit/rewardprograms/{token} endpoint.

Status transitions

The following diagram outlines the possible transitions between statuses.

Possible transitions between account states

Is this helpful?

Yes
No

Balances and credit

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 spend.

  • Credit limit – The maximum balance an account can carry, and the balance currency.

Key days

The values for key days for an account are derived 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:

Name Description

Late payment

A late payment fee is charged when the cardholder misses a payment on an account in an ACTIVE or SUSPENDED status, or TERMINATED if the terminated account carries a balance.

Returned payment

A returned payment fee is charged when the cardholder makes a bounced payment on an account in an ACTIVE or SUSPENDED status, or TERMINATED if the terminated account carries a balance.

Periodic

A periodic fee is a recurring fee that is assessed for accounts in an ACTIVE or SUSPENDED status. If an account transitions to a status other than ACTIVE or SUSPENDED, its existing periodic fee schedules are terminated. Currently, only annual and monthly periodic fees are supported.

Fee values are defined at the account level and must be a positive amount. There are no other limits on fee values.

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 acknowledgement 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.

Note
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.

Account usage

You can define how a credit account is used and what the types of balances are permitted on the account. Each usage type contains usage-based fees and rewards, such as FX fees, that are linked to the purchase balance.

Tutorial

This tutorial guides you through the process of onboarding a credit account by walking through how to create an 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
Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

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.

Join our developer newsletter