App API

토스플레이스 앱(애플리케이션; App)은 프론트(결제단말기) 및 토스 POS의 기능을 확장하는 연동 도구예요. 토스플레이스 앱은 매장에서 이루어지는 주문, 결제 등의 활동을 추적하고 관리하거나, 이 과정에서 발생하는 이벤트를 바탕으로 외부 시스템과 연동할 수 있어요.

Events

토스플레이스 앱이 매장에 설치되는 등, 앱 관련 사건이 발생할 때 전달되는 웹훅 이벤트예요.

내 앱이 어떤 매장에 설치되었는지 확인하려면, 이 이벤트를 수신하여 매장 ID를 확인해야 해요. 앱은 설치된 매장에서만 Open API를 통해 매장의 정보에 접근하거나, 웹훅 이벤트를 수신할 수 있어요.

매장에 앱 설치됨 (app.installation.created.v1)

Property	Value
Event Type	app.installation.created.v1
Description	매장에 앱이 설치되었어요. 이제부터 해당 매장의 정보를 Open API로 조회할 수 있고, 매장에서 이루어지는 활동을 웹훅 이벤트로 수신할 수 있어요.

이벤트 Payload

Name	Type	Required	Description	Example
merchant	Merchant	✅	매장 정보

이벤트 Body 예시

{
    "id": "000000000000000000000000",
    "type": "app.installation.created.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "merchant": {
            "id": 42,
            "name": "플레이스 베이커리",
            "businessNumber": "0000000000",
            "ownerName": "김토스",
            "displayName": "플레이스 베이커리",
            "address": "서울특별시 서초구 강남대로 459 (서초동)",
            "latitude": 37.5031925,
            "longitude": 127.0247527,
            "operatingHours": [
                {
                    "dayOfWeek": "MONDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "TUESDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "WEDNESDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "THURSDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "FRIDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                },
                {
                    "dayOfWeek": "SATURDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                },
                {
                    "dayOfWeek": "SUNDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
            ]
        }
    }
}

매장에서 앱 설치 해제됨 (app.installation.deleted.v1)

Property	Value
Event Type	app.installation.deleted.v1
Description	매장에서 앱이 설치 해제되었어요. 이제부터 해당 매장의 정보를 Open API로 조회할 수 없고, 매장에서 이루어지는 활동을 웹훅 이벤트로 수신할 수 없어요.

이벤트 Payload

Name	Type	Required	Description	Example
merchantId	Long	✅	매장 ID	42

이벤트 Body 예시

{
    "id": "000000000000000000000000",
    "type": "app.installation.deleted.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "merchantId": 42
    }
}