Python SDK (Beta)

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.

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:

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.

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:

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

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

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:

The SDK generates a MarqetaError exception for unsuccessful requests:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.