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"
        }
    }
}

매장에서 앱 설치 해제됨 (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
    }
}