Store API v1.0.0 Requests

Store API v1.0.0

Documentation has moved

The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:

https://developers.koshelek.app/en/

Add Store

HTTP method: POST

URL: /api/v1/configuration/brand/store

Description

Use this request to introduce your store (one or more) to Koshelek Pay.

Request parameters

Request body

Request body is a JSON object of the following structure:

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
stores	Array[Object]	Yes	Contains store information to be added (see below: Array: stores).

Array: stores

This array contains store information for store(s) being added. Every store in this array is represented by an object of the following strucure:

Field	Type	Mandatory	Description
storeNumber	String	Yes	Store ID as assigned by merchant (UUID).
legalId	String	Yes	Merchant's legal name ID in Koshelek Pay (UUID).
city	String	Yes	Merchant's actual city.
address	String	Yes	Merchant's actual address.
phone	String	Yes	Merchant's phone number.
countryCode	String	No	Merchant's country of residence (ISO 3166 Alpha-2).
countrySubDivisionCode	String	No	Merchant's region of residence (ISO 3166-2:RU).
mcc	String	No	Merchant Category Code.
zip	String	Yes	ZIP code.
paymentMethods	Array[Enum]	No	Koshelek Pay payment method available in store. Possible values: SBP DOLYAME If empty: the value is inherited from merchant brand's global settings.
sbpMerchantId	String	No	Store ID to SBP.
status	Enum	No	Current store status. Possible values: ACTIVE (default) INACTIVE

Request body example

{
  "brandId": "1a01ab77-2d71-4dc5-8148-1580be9a44c3",
  "stores": [
    {
      "storeNumber": "777",
      "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
      "city": "Москва",
      "address": "Лермонтова 38",
      "phone": "995598928",
      "countryCode": "RU",
      "countrySubDivisionCode": "RU-MOW",
      "mcc": "5661",
      "zip": "125212",
      "paymentMethods": [
        "DOLYAME"
      ]
    },
    {
      "storeNumber": "666",
      "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
      "city": "Санкт-Петербург",
      "address": "Лермонтова 38",
      "phone": "995598928",
      "countryCode": "RU",
      "countrySubDivisionCode": "RU-SPE",
      "mcc": "5661",
      "zip": "125212",
      "paymentMethods": [
        "SBP"
      ],
      "sbpMerchantId": "MA0000421504"
    }
  ]
}

Response parameters

HTTP Status Code: 200

The request is processed. The response body returns values received in the request, along with registration result parameters (storeId, result) — all as a JSON object of the following structure:

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
stores	Array[Object]	Yes	Contains store information being added (see below: Array: stores).
result	Object	Yes	Contains request processing results (see Object result).

Array: stores

This array contains store information received in the request, along with storeId identifier assigned to store by Koshelek Pay.

Field	Type	Mandatory	Description
storeNumber	String	Yes	Store ID as assigned by merchant (UUID).
legalId	String	Yes	Merchant's legal name ID in Koshelek Pay (UUID).
storeId	String	Yes	Merchant ID assigned by Koshelek Pay.
city	String	Yes	Merchant's actual city.
address	String	Yes	Merchant's actual address.
phone	String	Yes	Merchant's phone number.
countryCode	String	Yes if received in request	Merchant's country of residence (ISO 3166 Alpha-2).
countrySubDivisionCode	String	Yes if received in request	Merchant's region of residence (ISO 3166-2:RU).
mcc	String	Yes if received in request	Merchant Category Code.
zip	String	Yes	ZIP Code.
paymentMethods	Array[Enum]	Yes if received in request	Koshelek Pay payment method available in store. Possible values: SBP DOLYAME
sbpMerchantId	String	Yes if received in request	Store ID to SBP.

Response body example

{
  "brandId": "1a01ab77-2d71-4dc5-8148-1580be9a44c3",
  "stores": [
    {
      "store": {
        "storeId": "c3257989-2f57-48e5-9e20-94732ed6c4de",
        "storeNumber": "777",
        "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
        "city": "Батумск",
        "address": "Лермонтова 38",
        "phone": "995598928",
        "countryCode": "RU",
        "countrySubDivisionCode": "77",
        "mcc": "5661",
        "zip": "125212",
        "status": "ACTIVE",
        "paymentMethods": [
          "DOLYAME"
        ]
      },
      "result": {
        "storeId": "c3257989-2f57-48e5-9e20-94732ed6c4de",
        "status": "ACTIVE",
        "codes": [
          {
            "code": "000",
            "details": "Запрос выполнен успешно"
          }
        ]
      }
    },
    {
      "store": null,
      "result": {
        "storeId": null,
        "status": "ERROR",
        "codes": [
          {
            "code": "003",
            "details": "ЮЛ/ИП с таким legalId не существует "
          }
        ]
      }
    }
  ]
}n

Get Store Information

HTTP method: GET

URL: /api/v1/configuration/brand/store

Description

Use this request to obtain information about store (one or more) added previously via Store API.

This request is only applicable to store IDs associated with your brandId.

The response is either:

• Store information (or explanation why it's unavailable).

• Error code and description (in case of error).

Request parameters

Query parameters

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
storeIds	String	No	A list of storeId-s for which the information is being requested.

You can check validity and availability of your brand in Koshelek Pay. To do so, make this request with empty storeIds query string: if your brand is valid and available, you'll get HTTP: 200 response with empty stores list.

Request body

None.

Request example

/api/v1/configuration/brand/store?brandId=1a01ab77-2d71-4dc5-8148-1580be9a44c3&storeIds=2deadedc-df08-4693-9706-ee1d2c65ccb2&storeIds=ce83862c-714a-48bb-9ecb-6235aa856cac&storeIds=47c8c1f9-4b4a-48a4-aacb-52946f1a7731

Response parameters

HTTP Status Code: 200

The request is processed. Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
stores	Array[Object]	Yes	Contains store information (see above: Array: stores).

Request body example

{
  "brandId": "1a01ab77-2d71-4dc5-8148-1580be9a44c3",
  "stores": [
    {
      "store": {
        "storeId": "2deadedc-df08-4693-9706-ee1d2c65ccb2",
        "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
        "city": "Москва",
        "address": "Москва, Головинское ш., 5, БЦ «Водный»",
        "phone": "88002001063",
        "countryCode": "RU",
        "countrySubDivisionCode": "77",
        "mcc": "5661",
        "zip": "125212",
        "status": "ACTIVE",
        "paymentMethods": [
          " SBP",
          "DOLYAME"
        ]
      },
      "result": {
        "storeId": "2deadedc-df08-4693-9706-ee1d2c65ccb2",
        "status": "ACTIVE",
        "codes": [
          {
            "code": "000",
            "details": "Запрос выполнен успешно"
          }
        ]
      }
    },
    {
      "store": {
        "storeId": "ce83862c-714a-48bb-9ecb-6235aa856cac",
        "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
        "city": "Москва",
        "address": "Москва, Джавахарлала Неру площадь, д. 1",
        "phone": "88002001063",
        "countryCode": "RU",
        "countrySubDivisionCode": "77",
        "mcc": "5661",
        "zip": "119311",
        "status": "ACTIVE",
        "paymentMethods": [
          "SBP",
          "DOLYAME"
        ]
      },
      "result": {
        "storeId": "ce83862c-714a-48bb-9ecb-6235aa856cac",
        "status": "ACTIVE",
        "codes": [
          {
            "code": "000",
            "details": "Запрос выполнен успешно"
          }
        ]
      }
    },
    {
      "store": {
        "storeId": "47c8c1f9-4b4a-48a4-aacb-52946f1a7731",
        "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
        "city": "Екатеринбург",
        "address": "Екатеринбург, ул. 8 Марта, стр. 46",
        "phone": "88002001063",
        "countryCode": "RU",
        "countrySubDivisionCode": "66",
        "mcc": "5661",
        "zip": "620014",
        "status": "ACTIVE",
        "paymentMethods": [
          "SBP",
          "DOLYAME"
        ]
      },
      "result": {
        "storeId": "47c8c1f9-4b4a-48a4-aacb-52946f1a7731",
        "status": "ACTIVE",
        "codes": [
          {
            "code": "000",
            "details": "Запрос выполнен успешно"
          }
        ]
      }
    }
  ]
}

Update Store Information

HTTP method: PUT

URL: /api/v1/configuration/brand/store

Description

Use this request to update your store information whenever there is a need to (e.g. to update store phone number or Koshelek Pay availability status).

Before you update your store information, make sure that the store was added via Add Store.

Request parameters

For each store, pass only parameters you want to update, and omit others.

Request body

The request body is a JSON object of the following structure:

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
stores	Array[Object]	Yes	Contains store information to update (see below: Array: stores).

Array:stores

This array contains information for store(s) to be updated. Every store in this array is represented by an object of the following strucure:

Field	Type	Mandatory	Description
storeNumber	String	No	Store ID as assigned by merchant (UUID).
storeId	String	Yes	Merchant ID assigned by Koshelek Pay.
legalId	String	No	Merchant's legal name ID in Koshelek Pay (UUID).
city	String	No	Merchant's actual city.
address	String	No	Merchant's actual address.
phone	String	No	Merchant's phone number.
countryCode	String	No	Merchant's country of residence (ISO 3166 Alpha-2).
countrySubDivisionCode	String	No	Merchant's region of residence (ISO 3166-2:RU).
mcc	String	No	Merchant Category Code.
zip	String	No	ZIP code.
paymentMethods	Array[Enum]	No	Koshelek Pay payment method available in store. Possible values: SBP DOLYAME If empty: the value is inherited from merchant brand's global settings.
sbpMerchantId	String	No	Store ID to SBP.
status	String[Enum]	No	Current store status. Possible values: ACTIVE (default) INACTIVE

Request body example

{
  "brandId": "1a01ab77-2d71-4dc5-8148-1580be9a44c3",
  "stores":
    [
      {
          "storeId": "8fa6e6c1-cf24-42cf-9c23-3dfe1051ca25",
          "status": "INACTIVE"
      }
    ]
}

Response parameters

HTTP Status Code: 200

The request is processed. Response body returns values received in the request, along with request processing result:

Field	Type	Mandatory	Description
brandId	String	Yes	Merchant brand ID (UUID).
stores	Array[Object]	Yes	Contains updated store information (see below: Array: stores).
result	Object	Yes	Contains request processing result (see Object result).

Array:stores

This array contains updated store information for each store:

Field	Type	Mandatory	Description
storeNumber	String	Yes if received in request	Store ID as assigned by merchant (UUID).
legalId	String	Yes	Merchant's legal name ID in Koshelek Pay (UUID).
storeId	String	Yes if received in request	Merchant ID assigned by Koshelek Pay.
city	String	Yes if received in request	Merchant's actual city.
address	String	Yes if received in request	Merchant's actual address.
phone	String	Yes if received in request	Merchant's phone number.
countryCode	String	Yes if received in request	Merchant's country of residence (ISO 3166 Alpha-2).
countrySubDivisionCode	String	Yes if received in request	Merchant's region of residence (ISO 3166-2:RU).
mcc	String	Yes if received in request	Merchant Category Code.
zip	String	Yes if received in request	ZIP code.
paymentMethods	Array[String]	Yes if received in request	Koshelek Pay payment method available in store. Possible values: SBP DOLYAME
sbpMerchantId	String	Yes if received in request	Store ID to SBP.

Response body example

{
  "brandId": "1a01ab77-2d71-4dc5-8148-1580be9a44c3",
  "stores": [
    {
      "store": {
        "storeId": "8fa6e6c1-cf24-42cf-9c23-3dfe1051ca25",
        "storeNumber": "777",
        "legalId": "2f00d067-3d92-48cb-8973-cee7821035da",
        "city": "Батумск",
        "address": "Лермонтова 38",
        "phone": "995598928",
        "countryCode": "RU",
        "countrySubDivisionCode": "77",
        "mcc": "5661",
        "zip": "125212",
        "status": "INACTIVE",
        "paymentMethods": [
          "DOLYAME"
        ]
      },
      "result": {
        "storeId": "8fa6e6c1-cf24-42cf-9c23-3dfe1051ca25",
        "status": "INACTIVE",
        "codes": [
          {
            "code": "000",
            "details": "Запрос выполнен успешно"
          }
        ]
      }
    }
  ]
}