Manage stores

Learn how to manage stores for your users.

Stores are linked to the legal entity of your user through business lines. Stores ensure that payments are processed in a compliant manner and each processed transaction has an accurate payer statement.

For every payment processed through your user's store, you can split the funds between the balance accounts in your platform, including your liable balance account. You can split funds manually for each payment, or you can add a split configuration profile to your user's store to automatically split all payments processed through that store.

This page contains instructions for common store operations, including how to:

Create a new store
View store details
Update store information

Store identification

When you create a store, Adyen automatically assigns a unique ID to the store. You can also optionally provide a store reference for your reports. The store ID is unique to the entire Adyen platform, while the reference is only unique to your merchant account. To update the store, you need to know the store ID.

Store statuses

Stores can have three statuses that determine how they operate:

Active: When you create a store, it is automatically set to active. The store can then immediately process payments.
Inactive: When you change the store status from active to inactive, the store is blocked from accepting new transactions, but capturing outstanding transactions is still possible. When you change the store status back to active, this restriction is removed.
Closed: Before you can close a store, you must first change the store status to inactive. It is not possible to change the status anymore because a closed store cannot be reopened.

Create a new store

During the initial onboarding process, you need to create a store for the user. Later, you might also need to create an additional store if the user wants to:

Add a new store location or website.
Operate in a new industry or offer additional services.

You can create a store using the Customer Area or the Management API.

Contact your Adyen representative to enable this feature in your Customer Area.

Before you begin, ensure you have the Merchant POS Terminal Management Admin role.

To create a store in your Customer Area:

In the navigation menu, select the merchant account linked to your balance platform.
Go to Accounts & balances > Account holders.
In the account holder table, select an Account holder ID to open the Account holder details page.
On the Account holder details page, select Stores, then Add store.
Review the country/region of the new store. You can only create a new store in a country/region that is already associated with the account holder. To open a store in a different country/region, you must create a new account holder.
Provide information about the primary line of business for this store. You can either select from the industry codes that are already associated with this account holder or add a new one. To avoid duplicate entries, ensure that you create a unique business line for each combination of industry code and sales channel.
Review the website URL and the sales channels associated with the industry code you specified.
Select the sales channel that indicates the type of payments of this store.
- For all sales channels, provide the reference of the store (also known as the store code) and a shopper statement.
- For the eCommerce sales channel, include a phone number that shoppers can use to contact the store. Adyen automatically sets the store description as "Ecommerce store for [Legal entity name]".
- For the pos sales channel, include both the store's address and a phone number.
Provide the reference of the store (also known as the store code) and the shopper statement. If you choose to process in-person payments, you should also provide the address of the store.
Provide the reference of the store (also known as the store code) and the shopper statement.
(Optional) Select a split configuration profile to link to the store.
Review the default payment methods created based on the country/region of the account holder. You can add or remove the available payment methods by selecting Edit payment methods.
Review the entered information, then select Add store to submit the request to Adyen.

View store details

After creating a store, you can view the resource at any time using the Customer Area or the Management API.

Before you begin, ensure you have the Balance platform base role.

To view store details in the Customer Area:

Select a merchant account that is connected to their platform.
Go to Accounts & balances > Account holders.
On the Account holders page, select an Account holder ID.
Select Stores.
Select a store from the list to see the store details.

The Stores tab shows all the relevant details regarding stores, such as: Balance account, Merchant account ID, Sales channels, Store ID. You can choose the store details on the page by selecting the settings icon .

Update a store

When the details of your user's store change, you need to update the store using the Management API.

Before you begin, you must:

Have access to API credentials for the Management API.
Have the Management API-Stores read and write role assigned to your API credential.

To update a store, you need to know its unique store ID. In your request, include only the parameters you want to update. The same applies if the parameter is inside an object.

For example, to change the postal code and remove the third address line from the store address, the address object should include the postalCode parameter with the new value, and the line3 parameter with an empty value.

To update a store:

Make sure that you know the id of the store. To find this value, get a list of stores.

To update the store, use the following endpoints:

PATCH /stores/{storeId}
PATCH /merchants/{merchantId}/stores/{storeId}

In the request body, include any of the following parameters:

Parameter	Description
address	Can contain string values for the following parameters: `city`: The city of the store. `line1` `line2` `line3`: Up to three lines can be used for the street name, street number, and other information. `postalCode`: The postal code of the store. Must be in the same postal code format as the country of the store. `stateOrProvince`: Required only for the United States. The state or province of the store as defined in ISO 3166-2. For example, IL for Illinois in the United States. It is not possible to update the country of the store.
description	Your description of the store.
businessLineIds	An array that contains unique identifiers of business lines. Must be part of the same legal entity as the merchant account. Business lines can only be added, not removed from a store.
splitConfiguration	An object containing the information required to automatically split transactions that are routed through this store. This object consists of: splitConfigurationId: the unique identifier of the split configuration that you want to add to the store. balanceAccountId: The unique identifier of the balance account to which the split amount must be booked, depending on the defined splitLogic.
status	The status of the store. You can change the status from active to inactive or from inactive to active or closed. After a store is closed, you cannot change the status anymore.

This example shows how you update a store's street address and postal code, identifying the store by ID. The first two lines of the address are changed and the third line is removed by including an empty value:

Update a store's address

 curl https://management-test.adyen.com/v3/stores/ST322LJ223223K5F4SQNR9XL5 \
-H 'content-type: application/json' \
-H 'x-api-key: ADYEN_API_KEY' \
-X PATCH \
-d '{
   "address":{
      "line1": "1776 West Pinewood Avenue",
      "line2": "Heartland Building",
      "line3": "",
      "postalCode":"20251"
   }
}'

Note that the response includes the full store details.

Store address updated

 {
    "id": "ST322LJ223223K5F4SQNR9XL5",
    "address":{
        "country": "US",
        "line1": "1776 West Pinewood Avenue",
        "line2": "Heartland Building",
        "city": "Springfield",
        "stateOrProvince": "NY",
        "postalCode":"20251"
    },
    "description": "City Centre store",
    "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
    "phoneNumber": "+13121112222",
    "reference": "Spring_store_2",
    "status": "active",
    "_links": {
        "self": {
            "href": "https://management-test.adyen.com/latest/stores/ST322LJ223223K5F4SQNR9XL5"
        }
    }
}'

Next steps

required

Payment methods

Add payment methods to your users' stores.

Route payments to a store

Learn how to process a payment through your users' stores.