Introduction to the Marqeta API for Python Developers

[Ricardo]

If you’re a Python developer hoping to build on the Marqeta platform for the first time, you’re in the right place. 

Marqeta’s Core API provides you with a powerful toolset for managing your company’s payment card program. Marqeta’s Python SDK streamlines the usage of this API into a straightforward Python native client for use in any Python application you’d like to build.

In this article, we’re going to get our hands dirty with the Python SDK and the Core API. After reviewing this guide for getting started, you’ll be well on your way toward building Marqeta-powered payment card programs and solutions.

Setup

To get started with the Marqeta Python SDK, be sure to install Python 3.7+ on your local machine. You may want to use virtualenv or pyenv to ensure you have your workspace for Marqeta isolated from your other work, but it’s not necessary. 

Make sure you’ve installed the marqeta-python library by following the guide in the README on GitHub.

You’ll also need to have a Marqeta developer account setup. For the purposes of this guide, we’ll be working in the sandbox environment, so be sure to configure that as well. 

When you configure your sandbox environment for the first time, you’ll end up with two tokens that you’ll need to use the Python SDK. Your application token is effectively a username for your use of the API client. Together with your admin access token, these two pieces of information allow access to your sandbox and should be securely managed. These credentials should never be committed to a repository alongside source code, but rather should be provided by means of runtime environment variables or a secrets manager.

For ease of demonstration, we’ll put both tokens straight in the script that we’ll prepare to use the API, but you should use a different method for storing these tokens in a real application. Note also that neither of these tokens is a user token. User tokens are specific to users in your Marqeta account, and we’ll talk about them later.

The following script should get you set up with a functional client:

from marqeta import Client

base_url = "https://sandbox-api.marqeta.com/v3/"
application_token = "MY_APPLICATION_TOKEN"
access_token = "MY_ACCESS_TOKEN"
timeout = 60 # seconds

client = Client(base_url, application_token, access_token, timeout)

 

First contact: basic querying for resources

Now that you have configured a client, you can access Marqeta’s Core API in your Python application. To get started, we’ll perform some simple GET requests in Python. We’ll create and modify resources later.

The Marqeta Python SDK provides access to many different resources available in the Core API. For now, we’ll take a look at some of the things you can do with the user's resource. If you simply want to get all users in your account, this is pretty simple.

client.users.list(limit=None)

If you’ve fetched a user, you can use the user’s token to look at all cards issued for that user.

client.cards.list_for_user(token)

This method corresponds to the Core API’s GET /cards/user/{token} endpoint and will list all cards for the user token provided. Another common resource would be all card products in your account. This corresponds to a GET request to /cardproducts.

client.card_products.list()

Another function of the SDK is to find a specific item, rather than list all resources of a certain type. Let’s say you knew the token of a program’s funding source. You could pick that specific program funding source out of your account with the following line of Python:

client.funding_sources.program.find(token)

This would be the same as running a GET /fundingsources/program/{token}, but the client would make sure to serialize this into a Python object for you to use in your application.

Advanced techniques for accessing resources

The ability to access the Core API in Python is pretty valuable, but there’s more. You can easily access the additional advanced functionality of the API from the Python SDK.

To begin with, the list function can be used with other filters besides pagination, to limit the number of objects returned from the API. In fact, the list function supports all query parameters for sorting and pagination. As an example, this line would provide a descending list of users sorted by lastModifiedTime:

client.users.list(params={'sort_by': '-lastModifiedTime'})

The Python SDK also fully supports pagination. Simply provide a limit and you’ll get that number of items returned per page, instead of the default for each resource.

client.businesses.list(limit=5)

The SDK also provides a stream() method which fetches pages as needed—rather than all at once—thereby reducing the amount of data that needs to be stored in memory.

for user in client.users.stream():
    print(user["token"])

Creating and updating objects

All of this read-only interaction can be very helpful, but if you want to build a fully-fledged Python application, then you’ll need to be able to create and modify resources. Fortunately, this is rather straightforward as well.

Let’s say we want to create a new user in our account. We’d start by defining a Python dictionary and calling create on the resource we want to create.

data = {
    'first_name': 'Ada'
}
user = client.users.create(data)

Now let’s create an address for a funding source for our new user.

data = {
    'user_token': user.token,
    'first_name': 'Computing',
    'last_name': 'Company',
    'address_1': '555 Microchip Way',
    'city': 'San Francisco',
    'state': 'CA',
    'postal_code': '94112',
    'country': 'USA'
}
fs_address = client.funding_sources.addresses.create(data)

As you can see, an address requires much more data than a user record, but the required fields are all listed in the documentation for each resource.

Let’s also set up a card product in our account using the Python SDK.

data = {
    'name': 'My Card Product',
    'start_date': '2021-10-13'
}
card_product = client.card_products.create(data)

We’ve almost set up enough information to create a card, but first, we need to give our user an address. We’ll perform an update by denoting the fields we want to update and then calling save with the user token and fields passed in.

updated_data = {
    'address1': fs_address.address_1,
    'city': fs_address.city,
    'state': fs_address.state,
    'postal_code': fs_address.postal_code,
    'country': fs_address.country
}
updated_user = client.users.save(user.token, updated_data)

Now, with a fully defined user, we can create a card resource.

data = {
    'user_token': user.token,
    'card_product_token': card_product.token
}
card = client.cards.create(data)

Let’s say we wanted to later change the name of our card product. This is also straightforward. Just define the fields to update and save them on the card product:

updated_data = {
    'name': 'Cool Card'
}
updated_card_product = client.card_products.save(card_product.token, updated_data)

Miscellaneous key points

The SDK also provides a useful MarqetaError object for unsuccessful requests. Here’s a quick demo of how you might use it:

from marqeta.errors import MarqetaError

try:
    user = client.users.find('not a valid token')
except MarqetaError as error:
    print(error)

The MarqetaError object will return one of the error codes as defined for the Core API. The resulting output from the above call will look like this:

marqeta.errors.MarqetaError: Cardholder not found
Error Code:404004

One other item worth noting is that you can retrieve the GPA balance for a user or business, simulated transactions in the sandbox environment must be created via direct API calls or through the Core API Explorer—simulated transactions are not supported by the Python SDK.

We would check the balance like this:

balance = client.balances.find_for_user_or_business(user.token)

If you inspect the object, this balance should come up as zero.

Next, you can go through steps 2 and 3 of the Core API Quick Start to simulate a transaction. After that, you should be able to check this user’s balance again and see it has changed to $10.

For convenience, the example code snippets above have been combined into a single Python script, which can be referenced here.

Conclusion

Marqeta’s platform for managing and issuing payment cards is very powerful. Using their Python SDK can make that power a lot more manageable. If you’ve got a great idea for an application, then open a developer account and get started today. The SDK is open source, so be sure to contribute to the project on GitHub or interact with other developers in the Marqeta community!