Part Two: Working With the Marqeta Core API
In Part One of this series, we did a deep dive into the Marqeta platform, covering all of the major models and components that you need to know for building a payment app. You can always go back to review those core concepts if they’re unclear. Here in Part Two, however, it’s time to start working with our hands. We’re going to walk through common use cases for the Core API.
The Core API is a RESTful API that uses HTTP GET, PUT, and POST methods to interact with the Marqeta platform. We’ll start with a crash course on authentication, and then we’ll step through the process of working with the various models we covered in Part One.
To follow along with the examples, you’ll need:
- A Marqeta developer account for access to a sandbox environment. You can sign up here if you don’t already have one.
- An HTTP API client (like Postman or Insomnia).
If you don’t want to use an HTTP API client, you can use one of our favorite features of Marqeta’s Core API docs: the Core API Explorer. The Core API Explorer widgets are embedded throughout our docs and you can sign in to use them directly from your developer account.
Understanding Core API Authentication
Marqeta Core API authentication uses HTTP Basic Authentication with the standard authorization header to authenticate requests. Your developer dashboard includes the API keys you’ll need as we go. Your Application token is ALWAYS required as a username. Your Admin access token is used as a password for admin-level requests.
For example, using curl, HTTP authentication for an admin-level request looks like this:
curl -i \
-X POST \
-H 'Content-Type: application/json' \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE
With curl, the --user argument—which is a string made up of your application token, followed by a colon, and then your admin access token—undergoes base64 encoding. The resulting base64-encoded string is used as the request’s basic auth header. If you use an HTTP API client, you can add the base64-encoded basic auth header directly.
Because creating users requires admin-level access, you’ll see a practical example in the Hello, World code in your developer dashboard.
Unauthenticated requests ONLY require your application token.
Some requests require a user access token as a password. User access tokens are obtained via an HTTP POST to the /users/auth/login API endpoint and are valid until the user logs out of the session or the session times out.
Here’s an example of using curl to request a user access token for a user with an email of “sally.public@example.com”, a password of “$uper$ecret”, and a user_token of “sallytoken”.
curl -X POST "https://sandbox-api.marqeta.com/v3/users/auth/login" \
-H "accept: application/json"
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE
-d "{ \"email\":\"sally.public@example.com\",
\"password\":\"$uper$ecret\",
\"user_token\":\"sallystoken\"
}"
Similarly, some requests require a single-use token as a password for an individual request. A single-use token can be generated by an HTTP post to the users/auth/onetime endpoint. Here’s the example curl for the same user:
curl -X POST "https://sandbox-api.marqeta.com/v3/users/auth/onetime" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE
-d "{ \"email\":\"sally.public@example.com\",
\"password\":\"$uper$ecret\",
\"user_token\":\"sallystoken\"
}"
Our examples include placeholder tokens for authentication, so remember to insert your own sandbox API keys as you follow along.
Core API walkthrough
In this section, we’re going to walk through the Marqeta Core API and work with the different models we discussed above. To help you get a feel for how a payment app might work with parent-child relationships, we’ll walk through an example that uses a standard (prefunded) funding model. We’ll walk through the following steps:
- Create a business account holder.
- Create two users who are children of that business. One user will use the parent’s account for funding, while the other will not.
Create a program funding source that we’ll use to add funds to the GPA for the business and the two users.
Create a card product with standard funding, and then create a card for each of our two users.
-
Simulate a transaction for each of our two users, then examine the impact on GPA balances for the users and the business.
Create parent business account
To create our business, we’ll send a POST request to the /businesses endpoint.
In this and other “create resource” requests, we’re going to explicitly assign values for the tokens associated with each resource. If we don’t explicitly assign the token value, the platform will automatically generate a UUID as the token. By assigning a token value, our subsequent API calls will be easier to read.
For our business, we’ll set its token value to business-01. The curl request looks like this:
curl -X POST "https://sandbox-api.marqeta.com/v3/businesses" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"business-01\"}"
In a live setting, you would likely have many more fields with business information to add to the request. If you have KYC requirements, those fields will be required. For our purposes here, though, we don’t need any of that additional data.
Create child users
When creating our first child user, demo-user-01, we will associate a parent_token (business-01) and set uses_parent_account to true.
curl -X POST "https://sandbox-api.marqeta.com/v3/users" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"demo-user-01\", \
\"parent_token\":\"business-01\", \
\"uses_parent_account\":true}"
Our second child user, demo-user-02, will be similar, except with uses_parent_account set to false.
curl -X POST "https://sandbox-api.marqeta.com/v3/users" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"demo-user-02\", \
\"parent_token\":\"business-01\", \
\"uses_parent_account\":false}"
Create program funding source
Next, we’ll create a program funding source that essentially represents a bank account. We’ll use this bank account to add funds to each of our account holder’s GPAs.
curl -X POST "https://sandbox-api.marqeta.com/v3/fundingsources/program" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"program-funding-source-01\", \
\"name\":\"Bank Account\"}"
Add funds to account holder GPAs
A GPA order loads funds into an account holder’s GPA. We’ll use our new program funding source to add $500 to the GPA for our business and $25 to each of our users.
curl -X POST "https://sandbox-api.marqeta.com/v3/gpaorders" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"business_token\":\"business-01\", \
\"funding_source_token\":\"program-funding-source-01\", \
\"amount\":500.00, \
\"currency_code\":\"USD\"}"
We make similar GPA order requests for our two users, loading $25 into each GPA.
curl -X POST "https://sandbox-api.marqeta.com/v3/gpaorders" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"user_token\":\"demo-user-01\", \
\"funding_source_token\":\"program-funding-source-01\", \
\"amount\":25.00, \
\"currency_code\":\"USD\"}"
curl -X POST "https://sandbox-api.marqeta.com/v3/gpaorders" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"user_token\":\"demo-user-02\", \
\"funding_source_token\":\"program-funding-source-01\", \
\"amount\":25.00, \
\"currency_code\":\"USD\"}"
We can check the balance for an account holder by sending a GET request to the /balances/{token} endpoint. For example, the following request retrieves the balance for our business:
curl -X POST "https://sandbox-api.marqeta.com/v3/balances/business-01" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE
{
"gpa" : {
"currency_code" : "USD",
"ledger_balance" : 500.00,
"available_balance" : 500.00,
"credit_balance" : 0.00,
"pending_credits" : 0.00,
...
}
}
If we were to perform similar requests for our two users, we would see $25.00 balances for each of them.
Create card product
Next, we’ll create a card product with the token card-product-01, from which we’ll be able to create our cards. Since we will be using standard funding, our card product will not be associated with any funding source.
Because the data payload for this request is slightly long, we’ve stored it remotely as a Gist. The following commands fetch that payload and then apply it as our request body.
curl -L https://bit.ly/mq-cardproduct-01 | \
curl -X POST "https://sandbox-api.marqeta.com/v3/cardproducts" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
--data-binary @-
Create Card
Now that we have our card product, we’ll create a card for demo-user-01 and demo-user-02.
curl -X POST "https://sandbox-api.marqeta.com/v3/cards" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"demo-user-01-card\", \
\"user_token\":\"demo-user-01\", \
\"card_product_token\":\"card-product-01\"}"curl -X POST "https://sandbox-api.marqeta.com/v3/cards" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"token\":\"demo-user-01-card\", \
\"user_token\":\"demo-user-01\", \
\"card_product_token\":\"card-product-01\"}"
Both users have cards. It’s time to simulate some transactions!
Simulate transactions and check balances
Here’s where everything comes together. We use the /simulate/authorization endpoint to simulate authorizations against the cards we’ve created.
Let’s start by authorizing a $10 transaction for demo-user-01.
curl -X POST "https://sandbox-api.marqeta.com/v3/simulate/authorization" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"card_token\":\"demo-user-01-card\", \
\"amount\":10.00, \
\"mid\":\"merchant-identifier-12345\"}"
After this authorization goes through, what impact should this have on the GPA for demo-user-01? How about for business-01? Let’s check their balances and see.
When we check the GPA balance for demo-user-01, this is the result we get:
{
"gpa" : {
"currency_code" : "USD",
"ledger_balance" : 25.00,
"available_balance" : 25.00,
"credit_balance" : 0.00,
"pending_credits" : 0.00,
...
}
}
The user’s balance is still $25, even with the recent $10 transaction. That makes sense, as we recall that this child user uses his parent account for funding. When we check the GPA balance for business-01, this is what we see:
{
"gpa" : {
"currency_code" : "USD",
"ledger_balance" : 500.00,
"available_balance" : 490.00,
"credit_balance" : 0.00,
"pending_credits" : 0.00,
...
}
}
The GPA balance for the business is short by $10, just as we would have expected. Next, let’s authorize a $10 transaction on the card for demo-user-02.
curl -X POST "https://sandbox-api.marqeta.com/v3/simulate/authorization" \
-H "Content-Type: application/json" \
--user APP_TOKEN_GOES_HERE:ADMIN_TOKEN_GOES_HERE \
-d "{\"card_token\":\"demo-user-02-card\", \
\"amount\":10.00, \
\"mid\":\"merchant-identifier-12345\"}"
After this transaction, we check the GPA balance for demo-user-02, and we see this result:
{
"gpa" : {
"currency_code" : "USD",
"ledger_balance" : 25.00,
"available_balance" : 15.00,
"credit_balance" : 0.00,
"pending_credits" : 0.00,
...
}
}
Just as we would have expected, the GPA balance for demo-user-02 is less by $10. This makes sense because he is not using his parent’s account for funding. If we were to check the GPA balance for business-01, we would see that it is unchanged.
Additional cases left for the reader
If you’ve been following along so far, you can try to simulate a few more transactions to see how the GPA balances of the various account holders is affected:
- Authorize a $100 transaction for the card belonging to demo-user-01. Even though his GPA only has a balance of $25, the transaction should go through because the parent account still has sufficient funds ($490).
- Authorize a $100 transaction for the card belonging to demo-user-02. Because he is not using his parent’s account for funding, you’ll find that this authorization was only partially authorized for $15, which was all that this user had left in his GPA. The configuration to enable_partial_auth_approval is made at the card product level, and defaults to true.
- Authorize another transaction (any amount) for the card belonging to demo-user-02. With no funds left in his GPA, even partial authorization cannot be approved. The result is a declined authorization for insufficient funds.
- Authorize a $1000 transaction for the card belonging to demo-user-01. This will also result in a partial authorization, effectively wiping out the parent’s (business-01) GPA balance. Note that the GPA balance for demo-user-01 will remain untouched.
- Authorize another transaction (any amount) for the card belonging to demo-user-01. Because the GPA for business-01 no longer has funds, the authorization will be declined.
Final thoughts: Tying it all together and building on the basics
In this walkthrough, we’ve seen three different practical examples that demonstrate how account holders use cards according to the standard (prefunded) funding model to carry out transactions on the Marqeta platform. We’ve also seen how different parent-child relationships impact how funds move and transaction approvals flow.
From here, you can begin building scalable apps with practical benefits. As you progress, here are three core concepts that can help you build on the basics to create more robust payment solutions:
- Marqeta SDKs: SDKs for the Marqeta platform can help you jumpstart your development efforts in your programming language of choice. Today, there is a Ruby SDK and a beta Python SDK. Additionally, because the platform was built using an open API, you can use tools like Swagger to create client libraries in other languages.
- Digital wallets and tokenization: By tokenizing sensitive card data (CV2 number, expiration date, and so on) you can enable your users to conduct transactions more securely. Digital wallets are devices that store and use the tokenized cards with a mobile phone that supports Apple Pay or Google Pay. To learn more about digital wallets and tokenization on the Marqeta platform, check out this developer guide.
- Webhooks: HTTP POST requests to external systems (webhooks) enable you to programmatically interface with other platforms when events (for example, the swipe of a card) occur on Marqeta. Webhooks enable a variety of custom integrations and automation that can improve your payment apps. To get started with webhooks, check out the About Webhooks page.
You’re now well equipped with an excellent foundation to begin building payment apps with Marqeta’s Core API. Be sure to get started in the developer sandbox, then work your way forward toward building powerful, cutting-edge payment solutions. You’re on your way!
Join our developer newsletter to hear about the latest updates.
