Python SDK (Beta)
Note
This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.The Marqeta Software Developer Kit (SDK) for Python provides easy access to the Marqeta Core API from your Python application. The Python SDK is built on top of the Core API, providing wrappers for the REST API endpoints.
What you can do with the Python SDK
Copy section link
You can use the SDK library to perform common programming tasks, including:
-
Build apps using your access tokens for your sandbox environment.
-
Use Python methods for easier, secure authentication.
-
Create, retrieve, and update objects and collections.
-
Access resource collections as properties of a client object.
-
Search for specific objects.
-
Call Python methods to interact with the Core API endpoints.
-
Handle errors.
How to get the SDK
Copy section link
To install the SDK, go to the marqeta-python repository on GitHub. See the README for requirements, dependencies, and installation.
Contribute to the SDK
Copy section link
The SDK is open source. Feel free to contribute on GitHub.
Python SDK basics
Copy section link
This section describes the basics of how to use the SDK, including configuration and basic operations. For a list of objects, see Resources. For usage specifics for each object, see Using the Python SDK.
Configuring the client
Copy section link
Create an account on marqeta.com to retrieve your application token and access token for your public sandbox environment.
Note that the base_url
in the example below is for the public sandbox.
For production or a private sandbox environment, you will need to update the base_url
.
To configure your client object:
When specifying your base url, include the /v3
version prefix.
Accessing resources
Copy section link
Access resource collections of the Core API as properties of the client object.
For example, to access the /users
endpoint:
Nested resource collections are properties of the parent collection.
For example, to access the /directdeposits/transitions/{token}
endpoint:
Listing objects
Copy section link
Depending on your use case, there are several ways to retrieve collections of objects.
The Python library handles pagination for you, unless you request a specific page of data.
To retrieve every object in a collection, call list(limit=None)
on the resource:
If a value is specified for limit
, objects up to that number are returned.
For most cases the default value of limit
is None
; however, for client.users.list()
and client.card_products.list()
the default values are 1000 and 25 respectively.
The stream()
method returns a generator that efficiently downloads subsequent pages as needed, rather than download all objects into memory at once:
To retrieve a single page, call the page()
method and specify values for start_index
and count
:
You can specify a sort field for the results by passing a params dictionary:
For details, see Sorting and pagination.
Specifying additional query parameters
Copy section link
Most methods support additional query parameters as a params
dictionary.
The keys and values are the same as those described for each endpoint in the Core API Reference:
Finding a specific objects
Copy section link
To find a specific object, call the find()
method on a resource collection, passing in the object’s token:
Creating objects
Copy section link
To create an object, call the create()
method of a resource collection, passing in data as a Python dict:
Updating objects
Copy section link
To update an object, call the save()
method of a resource collection, passing in the object’s token and a dictionary containing the fields to update:
Resources
Copy section link
The Marqeta Python Library supports the following endpoints:
Endpoint | Python object |
---|---|
N/A |
|
Using the Python SDK
Copy section link
The following sections show the basic method usage for each of the Python objects. For details on the REST API, including input and return values, see the Core API Reference.
Account holder groups
Copy section link
Use the account_holder_groups
object to manage groups of multiple account holders.
For details on account holder groups, including available parameters, see /accountholdergroups in the Core API Reference.
The following code examples show basic usage of the account_holder_groups
methods.
Auth controls
Copy section link
Use the auth_controls
object to manage authorization controls, which are spend controls that limit where users can transact.
For details, including available parameters, see /authcontrols in the Core API Reference.
The following code examples show basic usage of the auth_controls
methods.
Manage exempt MIDs
Copy section link
Use the auth_controls.exempt_mids
object to manage exemptions of Merchant Identifier numbers (MIDs) from authorization controls.
Transactions originating from an exempt MID ignore otherwise applicable authorization controls.
For details, including input parameters, see the /authcontrols/exemptmids endpoint in the Core API Reference.
The following code examples show basic usage of the auth_controls.exempt_mids
methods.
Auto reloads
Copy section link
Use the auto_reloads
object to automatically load a specified amount of funding into a GPA account when the balance falls below a defined threshold.
Transactions originating from an exempt MID ignore otherwise applicable authorization controls.
For details, including input parameters, see the /autoreloads endpoint in the Core API Reference.
The following code examples show basic usage of the auto_reloads
methods.
Balances
Copy section link
Use the balances
object to retrieve a specifc balance.
For details, including available parameters, see the /balances endpoint in the Core API Reference.
The following code examples show basic usage of the balances
methods.
Bulk issuances
Copy section link
Use the bulk_issuances
object to manage bulk card orders.
For details, including input parameters, see the /bulkissuances endpoint in the Core API Reference.
The following code examples show basic usage of the bulk_issuances
methods.
Businesses
Copy section link
Use the businesses
object to manage businesses on the Marqeta platform.
For details, including input parameters, see the /businesses endpoint in the Core API Reference.
The following code examples show basic usage of the businesses
methods.
Business transitions
Copy section link
Use the businesses(business_token).transitions
object to manage business transitions.
For details, including input parameters, see the /businesstransitions endpoint in the Core API Reference.
The following code examples show basic usage of the businesses(business_token).transitions
methods.
Card products
Copy section link
Use the /card_products
object to manage the behavior and functionality of one or more physical or virtual cards.
For details, including input parameter, see /cardproducts in the Core API Reference.
The following code examples show basic usage of the card_products
methods.
Cards
Copy section link
Use the /cards
object to manage the behavior and functionality of one or more physical or virtual cards.
For details, including input descriptions, see /cards in the Core API Reference.
The following code examples show basic usage of the cards
methods.
Card transitions
Copy section link
Use the cards(token).transitions
object to manage card transitions.
For details, including input parameters, see the /cardtransitions endpoint in the Core API Reference.
The following code examples show basic usage of the cards(token).transitions
methods.
Commando modes
Copy section link
Use the commando_modes
object to manage the Commando Modes fallback measure that ensures Gateway JIT-funded cards continue to function in the event your system fails.
For details, including input parameters, see the /commandomodes endpoint in the Core API Reference.
The following code examples show basic usage of the commando_modes
methods.
Commando mode transitions
Copy section link
Use the commando_modes(token)
object to manage Commando Mode transitions.
For details, including input parameters, see the Commando Mode documentation in the Core API Reference.
The following code examples show basic usage of the commando_modes(token)
methods.
Digital wallet tokens
Copy section link
Use the digital_wallet_tokens
object to manage digital wallet tokens.
For details, including input parameters, see the /digitalwallettokens/{token} endpoint in the Core API Reference.
The following code examples show basic usage of the digital_wallet_tokens
methods.
Digital wallet token transitions
Copy section link
Use the digital_wallet_tokens(token).transitions
object to manage digital wallet token transitions.
For details, including input parameters, see the /digitalwallettokentransitions endpoint in the Core API Reference.
The following code examples show basic usage of the digital_wallet_tokens(token).transitions
methods.
Direct deposits
Copy section link
Use the direct_deposits
object to manage direct deposits.
For details, including input parameters, see the /directdeposits endpoint in the Core API Reference.
The following code examples show basic usage of the direct_deposits
methods.
Direct deposit transitions
Copy section link
Use the direct_deposits(token).transitions
object to manage direct deposit transitions.
For details, including input parameters, see the /directdeposits/transitions endpoint in the Core API Reference.
The following code examples show basic usage of the direct_deposits(token).transitions
methods.
Direct deposit accounts
Copy section link
Use the direct_deposits.accounts
object to manage direct deposit accounts.
For details, including input parameters, see the /directdeposits/accounts endpoint in the Core API Reference.
The following code examples show basic usage of the direct_deposits.accounts
methods.
Funding source addresses
Copy section link
Use the funding_sources.addresses
object to manage funding source addresses.
For details, including input parameters, see the /fundingsources/addresses endpoint in the Core API Reference.
The following code examples show basic usage of the funding_sources.addresses
methods.
ACH funding sources
Copy section link
Use the funding_sources.ach
object to manage funding source addresses.
For details, including input parameters, see the /fundingsources/ach endpoint in the Core API Reference.
The following code examples show basic usage of the funding_sources.ach
methods.
Payment card funding sources
Copy section link
Use the funding_sources.payment_card
object to manage funding sources for payment cards.
For details, including input parameters, see the /fundingsources/paymentcard endpoint in the Core API Reference.
The following code examples show basic usage of the funding_sources.payment_card
methods.
Program gateway funding sources
Copy section link
Use the funding_sources.program_gateway
object to manage program gateway funding sources.
For details, including input parameters, see the /fundingsources/programgateway endpoint in the Core API Reference.
The following code examples show basic usage of the funding_sources.program_gateway
methods.
Program funding sources
Copy section link
Use the funding_sources.program
object to manage program funding sources.
For details, including input parameters, see the /fundingsources/program endpoint in the Core API Reference.
The following code examples show basic usage of the funding_sources.program
methods.
GPA orders
Copy section link
Use the gpa_orders
object to manage GPA orders.
For details, including input parameters, see the /gpaorders endpoint in the Core API Reference.
The following code examples show basic usage of the gpa_orders
methods.
GPA returns
Copy section link
Use the gpa_orders.unloads
object to manage GPA orders.
For details, including input parameters, see the /gpaorders/unloads endpoint in the Core API Reference.
The following code examples show basic usage of the gpa_orders.unloads
methods.
KYC
Copy section link
Use the kyc
object to manage KYC.
For details, including input parameters, see the /kyc endpoint in the Core API Reference.
The following code examples show basic usage of the kyc
methods.
MCC groups
Copy section link
Use the mcc_groups
object to manage MCC groups.
For details, including input parameters, see the /mccgroups endpoint in the Core API Reference.
The following code examples show basic usage of the mcc_groups
methods.
Program transfers
Copy section link
Use the program_transfers
objects to manage program transfers.
For details, including input parameters, see the /programtransfers endpoint in the Core API Reference.
The following code examples show basic usage of the program_transfers
methods.
Program transfer types
Copy section link
Use the program_transfers.types
object to manage program transfer types.
For details, including input parameters, see the /programtransfers/types endpoint in the Core API Reference.
The following code examples show basic usage of the program_transfers.types
methods.
Push-to-cards
Copy section link
Use the push_to_cards
object to manage Push-to-Card payment cards.
For details, including input parameters, see the /pushtocards endpoint in the Core API Reference.
The following code examples show basic usage of the push_to_cards
methods.
Push-to-card disbursements
Copy section link
Use the push_to_cards.disburse
object to manage Push-to-Card disbursements.
For details, including input parameters, see the /pushtocards/disburse endpoint in the Core API Reference.
The following code examples show basic usage of the push_to_cards.disburse
methods.
Push-to-card payment cards
Copy section link
Use the push_to_cards.payment_card
object to manage Push-to-Card disbursements.
For details, including input parameters, see the /pushtocards/paymentcard endpoint in the Core API Reference.
The following code examples show basic usage of the push_to_cards.payment_card
methods.
Transactions
Copy section link
Use the transactions
object to manage transactions.
For details, including input parameters, see the /transactions endpoint in the Core API Reference.
The following code examples show basic usage of the transactions
methods.
Related transactions
Copy section link
Use the transactions(token).related
object to manage related transactions.
For details, including input parameters, see the /transactions/{token}/related endpoint in the Core API Reference.
The following code examples show basic usage of the transactions(token).related
methods.
Users
Copy section link
Use the users
object to manage users.
For details, including input parameters, see the /users endpoint in the Core API Reference.
The following code examples show basic usage of the users
methods.
User transitions
Copy section link
Use the users(token).transitions
object to manage user transitions.
For details, including input parameters, see the /usertransitions endpoint in the Core API Reference.
The following code examples show basic usage of the users(token).transitions
methods.
Velocity controls
Copy section link
Use the velocity_controls
object to manage velocity controls.
For details, including input parameters, see the /velocitycontrols endpoint in the Core API Reference.
The following code examples show basic usage of the velocity_controls
methods.