/
10 minute read
April 29, 2023

Python SDK (Beta)

Hidden
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

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

To install the SDK, go to the marqeta-python repository on GitHub. See the README for requirements, dependencies, and installation.

Contribute to the SDK

The SDK is open source. Feel free to contribute on GitHub.

Python SDK basics

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

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:

Python
Copied

Is this helpful?

Yes
No

When specifying your base url, include the /v3 version prefix.

Accessing resources

Access resource collections of the Core API as properties of the client object. For example, to access the /users endpoint:

Python
Copied

Is this helpful?

Yes
No

Nested resource collections are properties of the parent collection. For example, to access the /directdeposits/transitions/{token} endpoint:

Python
Copied

Is this helpful?

Yes
No

Listing objects

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:

Python
Copied

Is this helpful?

Yes
No

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:

Python
Copied

Is this helpful?

Yes
No

To retrieve a single page, call the page() method and specify values for start_index and count:

Python
Copied

Is this helpful?

Yes
No

You can specify a sort field for the results by passing a params dictionary:

Python
Copied

Is this helpful?

Yes
No

For details, see Sorting and pagination.

Specifying additional query parameters

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:

Python
Copied

Is this helpful?

Yes
No

Finding a specific objects

To find a specific object, call the find() method on a resource collection, passing in the object’s token:

Python
Copied

Is this helpful?

Yes
No

Creating objects

To create an object, call the create() method of a resource collection, passing in data as a Python dict:

Python
Copied

Is this helpful?

Yes
No

Updating objects

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:

Python
Copied

Is this helpful?

Yes
No

Handling errors

The SDK generates a MarqetaError exception for unsuccessful requests:

Python
Copied

Is this helpful?

Yes
No

The exception’s code value in the JSON response contains the error returned by the Core API. For more information, see Errors.

Resources

The Marqeta Python Library supports the following endpoints:

Endpoint Python object

client.account_holder_groups

client.auth_controls

client.auth_controls.exempt_mids

client.auto_reloads

client.balances

client.bulk_issuances

client.businesses

client.businesses(business_token).transitions

client.card_products

client.cards

client.cards(token).transitions

client.commando_modes

N/A

client.commando_modes(token).transitions

client.digital_wallet_tokens

client.digital_wallet_tokens(token).transitions

client.direct_deposits

client.direct_deposits(token).transitions

client.direct_deposits.accounts

client.funding_sources.addresses

client.funding_sources.ach

client.funding_sources.payment_card

client.funding_sources.program_gateway

client.funding_sources.program

client.gpa_orders

client.gpa_orders.unloads

client.kyc

client.mcc_groups

client.offer_orders

client.program_transfers

client.program_transfers.types

client.push_to_cards

client.push_to_cards.disburse

client.push_to_cards.payment_card

client.transactions

client.transactions(token).related

client.users

client.users(token).transitions

client.velocity_controls

client.webhooks

Using the Python SDK

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

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.

Python
Copied

Is this helpful?

Yes
No

Auth controls

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.

Python
Copied

Is this helpful?

Yes
No

Manage exempt MIDs

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.

Python
Copied

Is this helpful?

Yes
No

Auto reloads

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.

Python
Copied

Is this helpful?

Yes
No

Balances

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.

Python
Copied

Is this helpful?

Yes
No

Bulk issuances

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.

Python
Copied

Is this helpful?

Yes
No

Businesses

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.

Python
Copied

Is this helpful?

Yes
No

Business transitions

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.

Python
Copied

Is this helpful?

Yes
No

Card products

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.

Python
Copied

Is this helpful?

Yes
No

Cards

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.

Python
Copied

Is this helpful?

Yes
No

Card transitions

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.

Python
Copied

Is this helpful?

Yes
No

Commando modes

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.

Python
Copied

Is this helpful?

Yes
No

Commando mode transitions

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.

Python
Copied

Is this helpful?

Yes
No

Digital wallet tokens

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.

Python
Copied

Is this helpful?

Yes
No

Digital wallet token transitions

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.

Python
Copied

Is this helpful?

Yes
No

Direct deposits

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.

Python
Copied

Is this helpful?

Yes
No

Direct deposit transitions

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.

Python
Copied

Is this helpful?

Yes
No

Direct deposit accounts

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.

Python
Copied

Is this helpful?

Yes
No

Funding source addresses

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.

Python
Copied

Is this helpful?

Yes
No

ACH funding sources

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.

Python
Copied

Is this helpful?

Yes
No

Payment card funding sources

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.

Python
Copied

Is this helpful?

Yes
No

Program gateway funding sources

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.

Python
Copied

Is this helpful?

Yes
No

Program funding sources

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.

Python
Copied

Is this helpful?

Yes
No

GPA orders

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.

Python
Copied

Is this helpful?

Yes
No

GPA returns

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.

Python
Copied

Is this helpful?

Yes
No

KYC

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.

Python
Copied

Is this helpful?

Yes
No

MCC groups

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.

Python
Copied

Is this helpful?

Yes
No

Program transfers

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.

Python
Copied

Is this helpful?

Yes
No

Program transfer types

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.

Python
Copied

Is this helpful?

Yes
No

Push-to-cards

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.

Python
Copied

Is this helpful?

Yes
No

Push-to-card disbursements

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.

Python
Copied

Is this helpful?

Yes
No

Push-to-card payment cards

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.

Python
Copied

Is this helpful?

Yes
No

Transactions

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.

Python
Copied

Is this helpful?

Yes
No

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.

Python
Copied

Is this helpful?

Yes
No

Users

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.

Python
Copied

Is this helpful?

Yes
No

User transitions

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.

Python
Copied

Is this helpful?

Yes
No

Velocity controls

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.

Python
Copied

Is this helpful?

Yes
No

Webhooks

Use the webhooks object to manage webhooks. For details, including input parameters, see the /webhooks endpoint in the Core API Reference. The following code examples show basic usage of the webhooks methods.

Python
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter