GPA Orders

Learn how to create and retrieve a GPA order with Marqeta's Core API.

We'll cover the following

Overview

Funds are transferred from a funding source into a user’s GPA through GPA orders, which are either funded by our payment card program or by the user. We can also use GPA orders to transfer funds from a user’s funding source into our program’s funding source.

In this lesson, we’ll learn how to create a GPA order. We’ll also learn to retrieve a specific GPA order with its unique token.

Create a GPA order

We can create a GPA order by making a POST request to the {BASE_URL}/gpaorders endpoint. This allows us to fund a user’s GPA. We must specify the user_token or the business_token in the body of the request to indicate the account we want to fund.

Note: The optional parameter fees allows us to specify all fees associated with a funding transaction. The fee amount will be deducted from the user’s GPA upon the creation of a GPA order. The fee will be deducted at the time of funding.

Request Parameters

Parameter

Type

Category

Description

amount

decimal

required

Amount of funds to be credited to the account

currency_code

string

required

Three-digit ISO 4217 currency code

Examples: USD, GBP, EUR

funding_source_token

string

required

Token of the funding source that we want to use for this order

Length: 1–36 characters

token

string

optional

Unique token of the GPA order

Length: 1–36 characters

Note: If not specified, the system generates one automatically. This value can’t be updated once set.

tags

string

optional

Comma-separated list of tags to describe the order

Length: 1–255 characters

memo

string

optional

Additional descriptive text

Length: 1–99 characters

fees

array

optional

List of funding transaction fees

fees[].memo

string

optional

Additional text to describe the fee transfer

Length: 1–99 characters

fees[].tags

string

optional

Comma-separated list of tags to describe the fee

Maximum length: 255 characters

fees[].token

string

required

Unique token of the fee

Length: 1–36 characters

funding_source_address_token

string

optional

Token of the funding source address we want to use for this order

Length: 1–36 characters

user_token

string

optional

Unique token of the user

Note: We must specify either a user_token or a business_token in the request.

Length: 1–36 characters

business_token

string

optional

Unique token of the business

Note: We must specify either a business_token or a user_token in the request.

Length: 1–36 characters

Lines 4–5: We enter the values for amount and currency_code, which are required parameters.

Line 6: We enter sandbox_program_funding for funding_source_token, since we don’t have any actual funding source.

Line 7: We use our previously stored USER_TOKEN value for the user_token attribute.

Note: You can also enter values for the other optional parameters given in the table above.

Click the “Run” button in the code widget below to see the output.

Press + to interact
url = '{{BASE_URL}}gpaorders'
data = {
    "amount": "",
    "currency_code": "",
    "funding_source_token": "sandbox_program_funding",
    "user_token": "{{USER_TOKEN}}"
}
response = requests.post(url, headers=headers, json=data)
printResponse(response)
printBalances('{{USER_TOKEN}}')

When the code is executed successfully, the output displays the complete GPA order object with all of the requested data fields. It also displays the updated GPA balances for the user. We extract the token value and save it as GPA_ORDER_TOKEN.

In case of failure, an appropriate error message is displayed.

Get GPA order information

We can get information for a GPA order by making a GET request to the {BASE_URL}/gpaorders/{token} endpoint. The path parameter ({token}) refers to the token of the GPA order that we want to retrieve.

Path Parameter

Parameter

Type

Category

Description

token

string

required

Token of the GPA order we want to retrieve

Line 1: We use the GPA_ORDER_TOKEN that we extracted in the previous code for value of token, the required path parameter.

Click the “Run” button in the code widget below to see the output.

Press + to interact
token = '{{GPA_ORDER_TOKEN}}'
url = '{{BASE_URL}}gpaorders/' + token
response = requests.get(url, headers=headers)
printResponse(response)

When the code is executed successfully, the output displays the complete GPA order object that corresponds to the given token with all the requested data fields.

In case of failure, an appropriate error message is displayed.