Create Merchant

Action: POST
Endpoint: /merchants

To create a merchant, send a POST request to the /merchants endpoint and include the merchant details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

As a result of creating a merchant, the system creates a default campaign resource. This campaign resource will have the same name as the merchant and a token value generated by the system. You can issue a GET /campaign/{merchant_name} to retrieve the default campaign.

Body Field Details

Name Type Required? Description Allowable Values
token string No The unique identifier of the merchant.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
name string Yes The name of the merchant.

This name is also used to name the default campaign that is created as a result of the POST /merchants call.
40 char max
active boolean No Indicates whether the merchant is active.

An active merchant is one who is in business and supported by Marqeta. Inactive merchants no longer accept payments through the Marqeta system.
true | false

Default: true
contact string No The name of the merchant contact. 40 char max
contact_email string No The email address of the merchant contact. 40 char max
address1 string No Merchant address. 255 char max
address2 string No Merchant address. 255 char max
city string No Merchant city. 40 char max
state string No Merchant state. 255 char max
province string No Merchant province. 20 char max
zip string No Merchant zip code. 10 char max
phone string No Merchant phone. 40 char max
country string No Merchant country. 40 char max
longitude number No GPS longitude coordinate for merchant location. 10 char max
latitude number No GPS latitude coordinate for merchant location. 10 char max
partial_auth_flag boolean No If true, allows cardholder to split payment between payment card and other payment method, such as cash or credit card. For example, if the charge is $50 but there is only $30 on the payment card, then the cardholder can pay the balance in cash or credit card. If false, entire transaction must use a single payment card (entire $50 must be covered by payment card). true | false

Default: true

Sample Request Body

{
"name": "My Merchant",
"active": "true",
"contact": "John Doe",
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}

Sample Response Body

{
"name": "My Merchant",
"active": true,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


Retrieve Merchant

Action: GET
Endpoint: /merchants/{token}

To retrieve a specific merchant, issue a GET request to the /merchants/{token} endpoint. Include the merchant token path parameter to specify the merchant to return.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant to retrieve. Existing merchant token.

Issue GET to /merchants to retrieve merchant tokens.

Sample Response Body

{
"name": "My Merchant",
"active": true,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


Update Merchant

Action: PUT
Endpoint: /merchants/{token}

To update a merchant, issue a PUT request to /merchants/{token}. Use the token path parameter to specify the merchant to update. Include the merchant details to update in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant to update. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Body Field Details

Name Type Required? Description Allowable Values
name string No The name of the merchant. 40 char max
active boolean No Indicates whether the merchant is active.

An active merchant is one who is in business and supported by Marqeta. Inactive merchants no longer accept payments through the Marqeta system.
true | false

Default: true
contact string No The name of the merchant contact. 40 char max
contact_email string No The email address of the merchant contact. 40 char max
address1 string No Merchant address. 255 char max
address2 string No Merchant address. 255 char max
city string No Merchant city. 40 char max
state string No Merchant state. 255 char max
province string No Merchant province. 20 char max
zip string No Merchant zip code. 10 char max
phone string No Merchant phone. 40 char max
country string No Merchant country. 40 char max
longitude number No GPS longitude coordinate for merchant location. 10 char max
latitude number No GPS latitude coordinate for merchant location. 10 char max
partial_auth_flag boolean No If true, allows cardholder to split payment between payment card and other payment method, such as cash or credit card. For example, if the charge is $50 but there is only $30 on the payment card, then the cardholder can pay the balance in cash or credit card. If false, entire transaction must use a single payment card (entire $50 must be covered by payment card). true | false

Default: true

Sample Request Body

{
"active": "false"
}

Sample Response Body

{
"name": "My Merchant",
"active": false,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}


List Merchants

Action: GET
Endpoint: /merchants

To list merchants, issue a GET request to the /merchants endpoint.

This endpoint supports field filtering and pagination.

Sample Response Body

{
"count": 1,
"start_index": 0,
"end_index": 1,
"is_more": yes,
"data": [
{
"name": "My Merchant",
"active": false,
"contact": "John Doe",
"longitude": 0,
"latitude": 0,
"address1": "600 Pants Ave",
"city": "Detroit",
"state": "MI",
"zip": "12345",
"phone": "1236547890",
"token": "my_merchant"
}
]
}


Retrieve Merchant Balance

Action: GET
Endpoint: /merchants/{token}/balance

To return the aggregate balance across all cardholders for a merchant, issue a GET request to the /merchants/{token}/balance endpoint. Include the merchant's token path parameter to indicate which merchant's balance to return. Use the optional start_date and end_date query parameters to return the balance over a date range.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant whose balance you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Query Parameters

Name Type Required? Description Allowable Values
start_date string No The beginning of the date range. yyyy-MM-dd
end_date string No The end of the date range. yyyy-MM-dd

Sample Response Body

{
"token": "my_merchant",
"committed": 0,
"triggered": 0,
"balance": 0,
"customers_balance": 0,
"customers_spent": 0
}


List Merchant Stores

Action: GET
Endpoint: /merchants/{token}/stores

To return the stores associated with a merchant, issue a GET request to the /merchants/{token}/stores endpoint. Include the merchant's token path parameter to indicate which merchant's stores to request.

This endpoint supports field filtering and pagination.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the merchant whose stores you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve merchant tokens.

Sample Response Body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"name": "My Store",
"longitude": 0,
"latitude": 0,
"token": "my_store1",
"partial_auth_capable": false,
"keyed_auth_cvv_enforced": false
},
{
"name": "My Store2",
"longitude": 0,
"latitude": 0,
"token": "my_store2",
"partial_auth_capable": false,
"keyed_auth_cvv_enforced": false
}
]
}