openapi: 3.1.0
info:
title: Marqeta Core API
description: >-
The Marqeta Core API is a RESTful interface that enables developers to build
and manage card payment programs programmatically. It provides endpoints for
creating and managing users (cardholders) and businesses, issuing physical and
virtual payment cards, defining spending controls via authorization controls
and velocity controls, processing and retrieving transactions, managing
funding sources, and configuring webhooks for real-time event notifications.
The API supports use cases including prepaid cards, expense management, earned
wage access, buy now pay later programs, and credit card issuance. Authentication
uses HTTP Basic Auth with an application token as the username and an access
token as the password. All requests and responses use JSON over HTTPS.
version: '3.0.38'
contact:
name: Marqeta Support
url: https://www.marqeta.com/company/contact
email: [email protected]
termsOfService: https://www.marqeta.com/api-terms
externalDocs:
description: Marqeta Core API Documentation
url: https://www.marqeta.com/docs/core-api/introduction
servers:
- url: https://sandbox-api.marqeta.com/v3
description: Sandbox Server
- url: https://api.marqeta.com/v3
description: Production Server
tags:
- name: Account Holder Funding Sources
description: >-
Manage ACH bank account funding sources attached to individual cardholders
and businesses for loading funds.
- name: Authorization Controls
description: >-
Create and manage authorization controls that restrict where and how
cards can be used, including merchant category and geographic limits.
- name: Balances
description: >-
Retrieve general purpose account (GPA) balance information for users,
businesses, and cards.
- name: Businesses
description: >-
Create and manage business account holders on the Marqeta platform.
Businesses can hold cards and funding balances just like individual users.
- name: Card Products
description: >-
Define card product templates that control card behavior, spending
controls, fulfillment options, and association with funding sources.
- name: Card Transitions
description: >-
Manage state transitions for payment cards, including activation,
suspension, termination, and lost or stolen status.
- name: Cards
description: >-
Issue and manage physical and virtual payment cards. Cards are derived
from card products and inherit their spending controls and configurations.
- name: GPA Orders
description: >-
Create and retrieve general purpose account (GPA) funding orders to
load money onto cardholder accounts.
- name: KYC Verification
description: >-
Submit and retrieve Know Your Customer (KYC) verification results for
users and businesses on the platform.
- name: Program Funding Sources
description: >-
Manage program-level funding sources used to load funds into the program
reserve account.
- name: Program Reserve
description: >-
Retrieve and manage the program reserve account balance and transactions
used for funding cardholder GPAs.
- name: Transactions
description: >-
Retrieve and search transaction records for card activity including
authorizations, clearing, declines, and GPA orders.
- name: User Transitions
description: >-
Manage state transitions for user accounts, including activation,
suspension, and closure of cardholder accounts.
- name: Users
description: >-
Create and manage cardholders (users) on the Marqeta platform. Users
represent the individuals who will be issued payment cards and hold
funding balances.
- name: Velocity Controls
description: >-
Define velocity controls that limit spending amounts and transaction
counts over configurable time windows.
- name: Webhooks
description: >-
Create, retrieve, update, and delete webhook configurations that deliver
real-time event notifications to your endpoint.
security:
- basicAuth: []
paths:
/users:
get:
operationId: listUsers
summary: List users
description: >-
Returns a paginated list of all users (cardholders) associated with
your program. Supports filtering by first name, last name, email,
phone, SSN, corporate card holder status, and passport number.
tags:
- Users
parameters:
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of users.
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createUser
summary: Create a user
description: >-
Creates a new user (cardholder) on the Marqeta platform. The user
can then be issued payment cards and have funds loaded onto their
general purpose account. Required fields include first name, last name,
and email or phone. Optional KYC identity fields may be required
depending on your program configuration.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
responses:
'201':
description: User created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{token}:
get:
operationId: getUser
summary: Retrieve a user
description: >-
Returns the details of a specific user identified by their token.
Includes personal information, account status, KYC verification
status, and metadata.
tags:
- Users
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: User details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
summary: Update a user
description: >-
Updates an existing user record with new personal information,
address, contact details, or metadata. Only fields provided in
the request body are updated; omitted fields retain their current values.
tags:
- Users
parameters:
- $ref: '#/components/parameters/token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
responses:
'200':
description: User updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/usertransitions:
post:
operationId: createUserTransition
summary: Create a user transition
description: >-
Transitions a user account to a new state. Valid transitions include
activating, suspending, unsuspending, or closing a user account.
The reason code and reason description fields provide context for
the state change and are included in audit logs.
tags:
- User Transitions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserTransitionRequest'
responses:
'201':
description: User transition created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserTransitionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/usertransitions/user/{user_token}:
get:
operationId: listUserTransitions
summary: List user transitions
description: >-
Returns a paginated list of all state transitions for a specific user,
ordered from most recent to oldest. Use this endpoint to audit the
complete state history of a cardholder account.
tags:
- User Transitions
parameters:
- name: user_token
in: path
required: true
description: Unique identifier of the user.
schema:
type: string
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of user transitions.
content:
application/json:
schema:
$ref: '#/components/schemas/UserTransitionListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/cards:
get:
operationId: listCards
summary: List cards for a user
description: >-
Returns a paginated list of cards associated with a specific user
or business token. Use the user_token or business_token query
parameter to filter results to a particular account holder.
tags:
- Cards
parameters:
- name: user_token
in: query
description: Filter cards by user token.
schema:
type: string
- name: business_token
in: query
description: Filter cards by business token.
schema:
type: string
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of cards.
content:
application/json:
schema:
$ref: '#/components/schemas/CardListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCard
summary: Create a card
description: >-
Issues a new payment card to a user or business based on a card
product configuration. The card product token determines the card
type, network, and behavior. Cards can be virtual or physical,
and physical cards require a fulfillment address.
tags:
- Cards
parameters:
- name: show_cvv_number
in: query
description: >-
If true, the response includes the card CVV2 value. This is only
returned once at card creation.
schema:
type: boolean
- name: show_pan
in: query
description: >-
If true, the response includes the full 16-digit PAN. This is only
returned once at card creation.
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardRequest'
responses:
'201':
description: Card issued successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/cards/{token}:
get:
operationId: getCard
summary: Retrieve a card
description: >-
Returns the details of a specific card identified by its token,
including the card product association, account holder, state,
expiration, and last four digits of the PAN.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: Card details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCard
summary: Update a card
description: >-
Updates metadata or configuration fields on an existing card.
Card state changes should be performed using the card transitions
endpoint rather than this endpoint.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardUpdateRequest'
responses:
'200':
description: Card updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/cardtransitions:
post:
operationId: createCardTransition
summary: Create a card transition
description: >-
Transitions a card to a new state such as ACTIVE, SUSPENDED,
TERMINATED, or LOST/STOLEN. Every card begins in UNACTIVATED state
and must be explicitly activated. The channel and reason code fields
are required and indicate how and why the transition occurred.
tags:
- Card Transitions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardTransitionRequest'
responses:
'201':
description: Card transition created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardTransitionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/cardtransitions/card/{card_token}:
get:
operationId: listCardTransitions
summary: List card transitions
description: >-
Returns a paginated list of all state transitions for a specific card,
ordered from most recent to oldest. Use this endpoint to review the
complete lifecycle history of a payment card.
tags:
- Card Transitions
parameters:
- name: card_token
in: path
required: true
description: Unique identifier of the card.
schema:
type: string
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of card transitions.
content:
application/json:
schema:
$ref: '#/components/schemas/CardTransitionListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/cardproducts:
get:
operationId: listCardProducts
summary: List card products
description: >-
Returns a paginated list of all card products configured for your
program. Card products define the behavior, network affiliation,
spending controls, and fulfillment options for cards derived from them.
tags:
- Card Products
parameters:
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of card products.
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCardProduct
summary: Create a card product
description: >-
Creates a new card product that serves as a template for issuing
payment cards. The card product defines the card network, card type
(physical or virtual), fulfillment options, funding source, and
applicable controls.
tags:
- Card Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductRequest'
responses:
'201':
description: Card product created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/cardproducts/{token}:
get:
operationId: getCardProduct
summary: Retrieve a card product
description: >-
Returns the complete configuration of a specific card product,
including network settings, spending controls, fulfillment
configuration, and associated funding source.
tags:
- Card Products
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: Card product details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCardProduct
summary: Update a card product
description: >-
Updates the configuration of an existing card product. Changes
to a card product apply to newly issued cards; existing cards
retain the configuration at the time of issuance unless
explicitly updated.
tags:
- Card Products
parameters:
- $ref: '#/components/parameters/token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductRequest'
responses:
'200':
description: Card product updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CardProductResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/transactions:
get:
operationId: listTransactions
summary: List transactions
description: >-
Returns a paginated list of transactions filtered by various criteria
including user token, business token, card token, type, state, and
date range. Transactions include authorizations, clearing events,
declines, balance inquiries, and GPA orders.
tags:
- Transactions
parameters:
- name: user_token
in: query
description: Filter transactions by user token.
schema:
type: string
- name: business_token
in: query
description: Filter transactions by business token.
schema:
type: string
- name: card_token
in: query
description: Filter transactions by card token.
schema:
type: string
- name: type
in: query
description: Filter transactions by type (e.g., authorization, clearing).
schema:
type: string
- name: state
in: query
description: Filter transactions by state (e.g., PENDING, COMPLETION).
schema:
type: string
- name: start_date
in: query
description: Return transactions on or after this date (format YYYY-MM-DD).
schema:
type: string
format: date
- name: end_date
in: query
description: Return transactions on or before this date (format YYYY-MM-DD).
schema:
type: string
format: date
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/transactions/{token}:
get:
operationId: getTransaction
summary: Retrieve a transaction
description: >-
Returns the full details of a specific transaction identified by
its token, including amount, merchant information, card details,
response codes, and any related transactions.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: Transaction details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/balances/{token}:
get:
operationId: getBalance
summary: Retrieve GPA balance
description: >-
Returns the general purpose account (GPA) balance for a user or
business identified by their token. The response includes available
balance, cached balance, credit balance, pending credits, and
impacted amount.
tags:
- Balances
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: GPA balance retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/gpaorders:
get:
operationId: listGpaOrders
summary: List GPA orders
description: >-
Returns a paginated list of GPA funding orders. GPA orders represent
fund loads to cardholder general purpose accounts from a funding
source such as a program ACH or program reserve.
tags:
- GPA Orders
parameters:
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
description: A paginated list of GPA orders.
content:
application/json:
schema:
$ref: '#/components/schemas/GpaOrderListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createGpaOrder
summary: Create a GPA order
description: >-
Creates a GPA funding order to load money onto a cardholder's
general purpose account. The funding source must be a program-level
ACH account or the program reserve. Specify the user token or
business token of the account to fund.
tags:
- GPA Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GpaOrderRequest'
responses:
'201':
description: GPA order created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GpaOrderResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/gpaorders/{token}:
get:
operationId: getGpaOrder
summary: Retrieve a GPA order
description: >-
Returns the details of a specific GPA funding order including the
amount loaded, the funding source used, the target account holder,
and the current state of the transaction.
tags:
- GPA Orders
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: GPA order retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GpaOrderResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/authcontrols:
get:
operationId: listAuthControls
summary: List authorization controls
description: >-
Returns a paginated list of authorization controls associated with
your program. Authorization controls restrict where cards can be
used based on merchant category codes, geographic regions, or
specific merchant identifiers.
tags:
- Authorization Controls
parameters:
- name: card_product_token
in: query
description: Filter authorization controls by card product token.
schema:
type: string
- name: user_token
in: query
description: Filter authorization controls by user token.
schema:
type: string
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: A paginated list of authorization controls.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createAuthControl
summary: Create an authorization control
description: >-
Creates a new authorization control for a card product or individual
user. Authorization controls can allow or deny transactions based on
MCC groups, merchant groups, merchant identifiers, or geographic
restrictions. Controls can be permanent or time-limited.
tags:
- Authorization Controls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlRequest'
responses:
'201':
description: Authorization control created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/authcontrols/{token}:
get:
operationId: getAuthControl
summary: Retrieve an authorization control
description: >-
Returns the full configuration of a specific authorization control
including its association, MCC or merchant group, geographic limits,
and active date range.
tags:
- Authorization Controls
parameters:
- $ref: '#/components/parameters/token'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: Authorization control retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateAuthControl
summary: Update an authorization control
description: >-
Updates the configuration of an existing authorization control.
You can modify the MCC group, merchant group, geographic restriction,
and active date range of the control.
tags:
- Authorization Controls
parameters:
- $ref: '#/components/parameters/token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlRequest'
responses:
'200':
description: Authorization control updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthControlResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/velocitycontrols:
get:
operationId: listVelocityControls
summary: List velocity controls
description: >-
Returns a paginated list of velocity controls for your program.
Velocity controls limit the amount and number of transactions a
cardholder can make within configurable time windows such as daily,
weekly, monthly, or lifetime.
tags:
- Velocity Controls
parameters:
- name: card_product_token
in: query
description: Filter velocity controls by card product token.
schema:
type: string
- name: user_token
in: query
description: Filter velocity controls by user token.
schema:
type: string
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/start_index'
- $ref: '#/components/parameters/fields'
responses:
'200':
description: A paginated list of velocity controls.
content:
application/json:
schema:
$ref: '#/components/schemas/VelocityControlListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createVelocityControl
summary: Create a velocity control
description: >-
Creates a new velocity control for a card product or individual user.
Velocity controls define spending limits by amount and transaction
count over a defined time window. Multiple controls can be applied
and all must pass for a transaction to be approved.
tags:
- Velocity Controls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VelocityControlRequest'
responses:
'201':
description: Velocity control create
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/marqeta/refs/heads/main/openapi/marqeta-core-api-openapi.yml