Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em inglês
Point-of-sale icon

Automate store management

Use API requests to create, retrieve, and update your stores

The Management API lets you retrieve, create, and update your stores by making API requests. You can also do this manually in your Customer Area, but with API requests, you can automate these processes.

For more information about stores and point-of-sale account structures, see Set up your Adyen account for point of sale.

Before you start making API requests to manage stores, there are a couple of things you need to be aware of:

Store identification

Historically, stores under a merchant account have a human-readable reference, also known as the store code. This reference is unique for the merchant account. However, it is possible that a store reference is not unique on our platform. So we introduced a platform-generated unique store ID for each store.

When you create a store, you can provide a reference for it, and Adyen will automatically assign a unique ID.

For existing stores, the situation can vary. We are currently assigning unique IDs to existing stores, but it will take a while before this is completed. This means that if your existing store doesn't have an ID yet, you can't make a PATCH request to update the store.

Opening and closing stores

Stores can have three statuses that determine how they operate:

  • active: when you create a store, it is automatically set to active. After assigning and boarding payment terminals, the store is immediately open for business.

  • 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. The maximum transaction limits and number of Store-and-Forward transactions for the store are set to zero (0). 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. Then, when you change the store status from inactive to closed, all payment terminals under the store are immediately reassigned to the merchant inventory. This means the terminals need to be assigned to a different store and boarded before they can process transactions again. It is not possible to change the status anymore because a closed store cannot be reopened.

API key and roles

To authenticate your requests to Management API, you need to have an API credential with an API key and the following roles:

  • Management API—Stores read
  • Management API—Stores read and write
  • Management API—Payment methods read
  • Management API—Payment methods read and write

If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.

Retrieve store details

You can make API requests to:

Get a list of stores

  1. To get a list of stores, use one of the following endpoints:

    You can filter the paginated response using the following query parameters:

    • pageNumber: returns the stores listed on the specified page.
    • pageSize: the number of stores to have on a page. The default is 10, the maximum is 100.
    • merchantId: the merchant account ID that a store belongs to. You can only use this query parameter with a GET /stores request.
    • reference: the reference of the store. Because a store reference is only unique within a merchant account, a GET /stores request using the store reference as a query parameter returns all stores with that reference, including those of different merchant accounts.

    Get a list of your stores
     curl https://management-test.adyen.com/v1/stores \
    -H "x-API-key: YOUR_API_KEY" \
  1. In the response, note the id of the store. You can use this value to get the details of a specific store or to update a store.

    The next table shows the store details that the response can include.

    Parameter Description
    address An object that contains:
    • city: The city of the store.
    • country: The country of the store.
    • line1 line2 line3: Up to three lines used for the street name, street number, and other information.
    • postalCode: The postal code of the store.
    • stateOrProvince: The state or province code as defined in ISO 3166-2. For example, IL for Illinois in the United States.
    description The description of the store.
    externalReferenceId Only when using the Zip payment method. The location ID that Zip has assigned to the store.
    id Unique identifier of the store, starting with ST. This value is generated by Adyen.
    _links The URL of the store.
    merchantId The ID of the merchant account that the store belongs to.
    phoneNumber The phone number of the store, including the country code.
    reference The reference for the store. If a reference was not specified when the store was created, the reference is populated with the store id.
    shopperStatement Store name shown on the shopper's bank or credit card statement and on the shopper receipt.
    splitConfiguration Only for Adyen for Platforms merchants. Not supported for Platforms on Adyen Bank. An object that contains:
    • balanceAccountId: The balance account linked to the account holder.
    • splitConfigurationId: The UUID of the split configuration that is set up for the store in the Customer Area.
    status The status of the store.

    List of stores
    {
    "_links": {
      "first": {
          "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=1&pageSize=1"
      },
      "last": {
          "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=2&pageSize=1"
      },
      "next": {
          "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=2&pageSize=1"
      },
      "self": {
          "href": "https://management-test.adyen.com/v1/merchants/YOUR_MERCHANT_ACCOUNT_ID/stores?pageNumber=1&pageSize=1"
      }
    },
    "itemsTotal": 2,
    "pagesTotal": 1,
    "data": [
      {
          "id": "ST322LJ223223K5F4SQNR9XL5",
          "address": {
              "city": "Springfield",
              "country": "US",
              "line1": "200 Main Street",
              "line2": "Building 5A",
              "line3":"Suite 3",
              "postalCode":"20250",
              "stateOrProvince":"NY"
          },
          "description": "City centre store",
          "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
          "phoneNumber": "+1813702551707653",
          "reference": "Springfield Shop",
          "status": "active",
          "_links": {
               "self": {
                  "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL5"
               }
          }
      },
      {
          "id": "ST322LJ223223K5F4SQNR9XL6",
          "address": {
              "city": "North Madison",
              "country": "US",
              "line1": "1492 Townline Road",
              "line2": "Rowland Business Park",
              "postalCode":"20577",
              "stateOrProvince":"NY"
          },
          "description": "West location",
          "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
         "phoneNumber": "+1211992213193020",
         "reference": "Second Madison store",
         "status": "active",
         "_links": {
              "self": {
                 "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6"
              }
         }
     }
    ]
    }'

Get the details of a specific store

  1. Make sure you know the id or the reference of the store. To find these values, get a list of stores.

  2. To get the details of a single store, use the following endpoints:

    You can also use the store reference as a query parameter. Because the reference is only unique within a merchant account, if you use the /stores endpoint you get all stores with that reference, including those of different merchant accounts.

    To get the details of a store under a merchant account using the store reference, make a GET request to /merchants/{merchantId}/stores?reference={reference}.

    This example shows how to get information about a store using the store ID in the path.

    Get the details of a specific store
     curl https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6 \
    -H "x-API-key: YOUR_API_KEY" \
    -X GET \
  1. Note that the response returns the same details as when you get a list of stores, but only for the specified store.

    Response showing the store details
     {
     "id": "ST322LJ223223K5F4SQNR9XL6",
     "address": {
         "city": "North Madison",
         "country": "US",
         "line1": "1492 Townline Road",
         "line2": "Rowland Business Park",
         "postalCode":"20577",
         "stateOrProvince":"NY"
     },
     "description": "West location",
     "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
     "phoneNumber": "+1211992213193020",
     "reference": "Second Madison store",
     "status": "active",
     "_links": {
         "self": {
             "href": "https://management-test.adyen.com/v1/stores/ST322LJ223223K5F4SQNR9XL6"
         }
     }
    }'

Create a store

To add a store:

  1. Make sure you know the merchant account ID that the store will be associated with.
    For a list of merchant account IDs accessible with your API key, make a GET request to /merchants.

  2. Make a POST request to /stores, specifying:

    Parameter Required Description
    address -white_check_mark- An object that contains:
    • city: the city of the store.
    • country: the country of the store.
    • line1 line2 line3: up to three lines can be used for the street name, street number, and other information. Only the first line is mandatory.
    • postalCode: the postal code of the store.
    • stateOrProvince: Required for Australia, Brazil, Canada, India, Mexico, New Zealand, United States. The state or province of the store as defined in ISO 3166-2. For example, ON for Ontario, Canada.
    description -white_check_mark- A description for the store.
    externalReferenceId Only when using the Zip payment method. The location ID that Zip has assigned to your store.
    merchantId -white_check_mark- Your merchant account ID.
    phoneNumber -white_check_mark- The complete phone number of the store, beginning with + and the country code.
    reference A reference to recognize the store by. Allowed characters: Lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (_).
    If you do not provide a reference in your POST request, it is populated with the Adyen-generated id.
    shopperStatement -white_check_mark- The store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals.
    splitConfiguration Only for Adyen for Platforms merchants. Required if the store has a split configuration. This object consists of:
    • balanceAccountId: the balance account linked to the account holder.
    • splitConfigurationId: the UUID of the split configuration that is set up for the store in the Customer Area.

    You can also make a POST request to /merchants/{merchantId}/stores using the same parameters. In that case you do not need to include your merchant account ID in the request body.

    This example request shows how you create a store:

    Create a store
       curl https://management-test.adyen.com/v1/stores \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
    -X POST \
    -d '
    {
       "merchantId":"YOUR_MERCHANT_ACCOUNT_ID",
       "description":"City centre store",
       "shopperStatement": "Springfield Shop",
       "phoneNumber":"1813702551707653",
       "reference":"Spring_store_2",
       "address":{
           "country": "US",
           "line1": "200 Main Street",
           "line2": "Building 5A",
           "line3":"Suite 3",
           "city": "Springfield",
           "stateOrProvince": "NY",
           "postalCode":"20250"
       }
    }'
  1. In the response, note that this includes the Adyen-generated id for your new store. You can use this as a path parameter to update the store.

    Store created
       {
       "id": "ST322LJ223223K5F4SQNR9XL5",
       "address":{
           "country": "US",
           "line1": "200 Main Street",
           "line2": "Building 5A",
           "line3":"Suite 3",
           "city": "Springfield",
           "stateOrProvince": "NY",
           "postalCode":"20250"
       },
       "description": "City centre store",
       "merchantId": "YOUR_MERCHANT_ACCOUNT_ID",
       "phoneNumber": "1813702551707653",
       "reference": "Spring_store_2",
       "shopperStatement": "Springfield Shop",
       "status": "active",
       "_links": {
           "self": {
               "href": "https://management-test.adyen.com/latest/stores/ST322LJ223223K5F4SQNR9XL5"
           }
       }
    }'
  1. Add payment methods to the store.

Manage payment methods

A newly created store doesn't have any payment methods yet. You need to add payment methods one at a time. Every payment method that you add, gets an ID that is unique for the combination of that payment method and store. Using this ID, you can update the settings of that payment method in the corresponding store.

Add a payment method

  1. To decide what payment method to add:

    • See the list of payment methods that you can add using Management API.

      Some payment methods (like iDEAL) only apply to web shops and are not supported on payment terminals.

    • For a list of payment methods that are already enabled for your store, make a GET request to /merchants/{merchantId}/stores/paymentMethodSettings with your store ID as a query parameter.
      For example, .../paymentMethodSettings?storeID=ST322LJ223223K5F4SQNR9XL5.

  2. To add a payment method to your store, make a POST request to /merchants/{merchantId}/stores/paymentMethodSettings with your store ID in the request body (not as a query parameter). Specify:

    Parameter Required Description
    type -white_check_mark- Payment method type . Note that some payment methods require an additional object with payment method details.
    storeId -white_check_mark- The id of the store that you get when creating a store .
    countries The list of countries to enable with the payment method. If sent empty, then all countries supported by the payment method will be enabled.
    currencies The list of currencies to enable with the payment method. If sent empty, then all currencies supported by the payment method will be enabled.

    The following example adds American Express.

    Add payment method
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/paymentMethodSettings \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
    -X POST \
    -d '
    {
       "type": "amex",
       "storeId":"ST322LJ223223K5F4SQNR9XL5",
       "currencies": [
            "USD"
       ],
       "countries": []
    }'
  3. In the response, note that this includes the id of the payment method. This ID is specific for the combination of payment method and store. You can use this as a path parameter to update the settings of the payment method.

    Response
    {
        "id": "PM3227C223224K5DSP4NSDKPK",
        "type": "amex",
        "storeId": "ST322LJ223223K5F4SQNR9XL5",
        "countries": [],
        "currencies": [
            "USD"
        ]
    }
  4. To check if the added payment method is enabled, make a GET request to /merchants/{merchantId}/stores/paymentMethodSettings with your store ID as a query parameter.

    Get payment methods for a store
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/paymentMethodSettings?storeID=ST322LJ223223K5F4SQNR9XL5 \
    -H "x-API-key: YOUR_API_KEY" \
    -X GET \
    Response
    {
        ...,
        "data": [
            {
                "PaymentMethod": {
                    "id": "PM3227C223224K5DSP4NSDKPK",
                    "type": "amex",
                    "storeId": "ST322LJ223223K5F4SQNR9XL5",
                    "enabled": true,
                    "countries": [],
                    "currencies": []
                }
            }
        ]
    }

Update a payment method

After adding a payment method to a store, you can change its settings. For example, to update the supported countries or currencies, or to disable the payment method.

To update a payment method:

  1. Make sure you know the id of the payment method for the applicable store. To find this value, make a GET request to /merchants/{merchantId}/stores/paymentMethodSettings.

  2. Make a PATCH request to , specifying:

    Parameter Required Description
    countries The list of countries to enable with the payment method. If sent empty, then all countries are supported by the payment method.
    currencies The list of currencies to enable with the payment method. If sent empty, then all currencies are supported by the payment method.
    enabled Indicates whether the payment method is enabled (true) or disabled (false).

    Because the payment method ID in the path is unique for the store where the payment method is set up, there is no need to specify a store.

    The next example updates American Express with payments in Canadian dollars:

    Update payment method settings
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/paymentMethodSettings/PM3227C223224K5DSP4NSDKPK \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -X PATCH \
    -d '{
        "currencies": [
           "CAD",
           "USD"
        ]
    }'
  3. In the response, note that this contains the storeId of the store that the payment method was updated for.

    Response
    {
        "id": "PM3227C223224K5DSP4NSDKPK",
        "type": "amex",
        "storeId": "ST322LJ223223K5F4SQNR9XL5",
        "enabled": true,
        "countries": [],
        "currencies": [
            "CAD",
            "USD"
        ]
    }

Update a store

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:

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

  2. To update the store, use the following endpoints:

    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 for Australia, Brazil, Canada, India, Mexico, New Zealand, United States. The state or province of the store as defined in ISO 3166-2. For example, ON for Ontario, Canada.
    It is not possible to update the country of the store.
    description Your description of the store.
    externalReferenceId Only when using the Zip payment method. The location ID that Zip has assigned to your store.
    splitConfiguration An object that contains:
    • balanceAccountId: The balance account linked to the account holder.
    • splitConfigurationId: The UUID of the split configuration that is set up for the store in the Customer Area.
    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 can't 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/v1/stores/ST322LJ223223K5F4SQNR9XL5 \
    -H "Content-Type: application/json" \
    -H "x-API-key: YOUR_API_KEY" \
    -X PATCH \
    -d '
    {
      "address":{
         "line1": "1776 West Pinewood Avenue",
         "line2": "Heartland Building",
         "line3": "",
         "postalCode":"20251"
      }
    }'
  1. 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": "+1813702551707653",
     "reference": "Spring_store_2",
     "status": "active",
     "_links": {
         "self": {
             "href": "https://management-test.adyen.com/latest/stores/ST322LJ223223K5F4SQNR9XL5"
         }
     }
    }'

See also