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
Copy section link
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 |
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 |
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 |
Account holder |
The primary user responsible for the credit account is the account holder, who is represented by the |
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 |
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
Copy section link
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
Copy section link
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
Copy section link
A credit account can have one of the following statuses.
| Status | Description and behavior |
|---|---|
|
The account is awaiting activation by the account holder. |
|
The account is active. The account holder and any authorized users can access the credit line. |
|
The account is temporarily inactive. Its credit line cannot be accessed. |
|
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 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. |
|
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.
Balances and credit
Copy section link
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
Copy section link
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
Copy section link
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 a penalty fee that is charged when the cardholder misses a payment on an account in an |
Returned payment |
A returned payment fee is a penalty fee that is charged when the cardholder makes a bounced payment on an account in an |
Periodic |
A periodic fee is a recurring fee that is assessed for accounts in an |
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 additonal 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 acknowledgement of the disclosure.You can waive any fee when creating or updating an account by setting the fee value to 0.
Fee schedules
Copy section link
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
Copy section link
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
Copy section link
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
Copy section link
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
Copy section link
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) andexternal_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
configobject — Include the following fields:-
billing_cycle_day— Set to the value of1. -
payment_due_day— Set to the value of31. -
The
feesarray — For eachfeesobject, include the following fields:-
type— Set the value to the fee type, eitherLATE_PAYMENT_FEE,RETURNED_PAYMENT_FEE,ANNUAL_FEEorMONTHLY_FEE. -
The
schedulearray — For eachscheduleobject, include the following fields:-
method— Set the value toFLAT. -
value— Set the value to the fee amount.
-
-
-
-
The
usagesarray — For eachusagesobject, include the following fields:-
type— Set the value toPURCHASE. -
The
aprsarray — For eachaprsobject, include the following fields:-
type— Set to the value ofGO_TO. -
The
schedulearray — For eachscheduleobject, set thevaluefield to the APR value,1-100.
-
-
The following code block shows a sample account as it would appear in a POST request:
Step three: Create a credit card
Copy section link
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 thetokenvalue of the user defined in step one.
Tip
This links the credit card to the account. To further configure the newly created card, send aPUT 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:
Step four: Update a credit account (Optional)
Copy section link
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:
Step five: Update account status (Optional)
Copy section link
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.