> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 토스페이먼츠 상점 준비와 키 저장

> 토스페이먼츠 키를 준비해 콘솔에 저장하고 토스페이먼츠 웹훅을 등록하는 방법을 설명합니다.

> [!NOTE]
>
> 이 기능은 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다.

MeterEngine은 도입사의 토스페이먼츠 상점 키로 고객 카드를 등록하고 결제합니다. 결제 대금은 도입사의 토스페이먼츠 상점으로 들어갑니다. 이 페이지는 키를 준비해 저장하고, 토스페이먼츠가 결제 상태 변경을 MeterEngine에 알리도록 웹훅을 등록하는 순서를 다룹니다.

## 토스페이먼츠 상점 준비

* 토스페이먼츠 개발자센터에 가입하면 전자결제 계약 전에도 테스트 상점 키를 확인할 수 있습니다. 테스트 환경 연동은 이 테스트 키로 시작합니다.
* 실결제로 자동결제를 쓰려면 토스페이먼츠의 추가 리스크 검토와 자동결제 계약이 필요합니다. 토스페이먼츠 정책상 자동결제는 정기 구독형 서비스에만 허용됩니다. 조건은 [토스페이먼츠 자동결제 연동 가이드](https://docs.tosspayments.com/guides/v2/billing/integration)에서 확인하세요.
* 키는 개발자센터의 'API 키' 메뉴에서 확인합니다. MeterEngine에는 자동결제(빌링) 상점(MID)의 **API 개별 연동 키**(클라이언트 키와 시크릿 키 한 쌍)를 넣습니다. 토스페이먼츠는 자동결제처럼 서비스마다 다른 상점에 API 개별 연동 키를 발급하니, 자동결제 상점을 골랐는지 확인하세요. 키 종류는 [토스페이먼츠 API 키 문서](https://docs.tosspayments.com/reference/using-api/api-keys)에 있습니다.

> [!WARNING]
>
> `test_gck_`, `test_gsk_`, `live_gck_`, `live_gsk_`로 시작하는 주문서형, 결제창형 연동 키(결제위젯 키)는 받지 않습니다. 저장하면 `400 invalid_toss_payments_credential`로 거절됩니다.

## 업무 환경마다 받는 키

토스페이먼츠 키는 업무 환경마다 따로 저장합니다. 테스트 환경에 저장한 키는 실제 환경에서 쓰이지 않고, 그 반대도 같습니다. 환경마다 받는 키의 앞부분이 정해져 있습니다.

> [tab] 테스트 환경
>
> | 입력란 | 앞부분 |
> | - | - |
> | 클라이언트 키 | `test_ck_` |
> | 시크릿 키 | `test_sk_` |
>
> 테스트 키로 한 결제는 실제로 결제되지 않으며 카드에서 금액이 빠져나가지 않습니다.

> [tab] 실제 환경
>
> | 입력란 | 앞부분 |
> | - | - |
> | 클라이언트 키 | `live_ck_` |
> | 시크릿 키 | `live_sk_` |
>
> 자동결제 계약을 맺은 상점의 키를 넣습니다. 이 키로 한 결제는 고객 카드에서 실제로 출금됩니다.

키를 저장하기 전에 화면 위 '업무 환경'이 키를 쓸 환경인지 확인하세요. 로그인하면 '기존 데이터'로 열리므로 먼저 '테스트 환경'으로 전환합니다. 업무 환경을 고르는 방법은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)에 있습니다.

## 키 저장

**1. 도입사 설정 화면을 연다**

콘솔 왼쪽 메뉴 '과금과 연동'에서 '도입사 설정'을 엽니다. 키를 저장하려면 admin(전체 관리) 권한이 있는 구성원으로 로그인해야 합니다.

**2. 토스 키 저장을 연다**

'토스페이먼츠 연동' 구역에서 '토스 키 저장'을 누릅니다. 업무 환경이 테스트 환경이면 테스트 키를, 실제 환경이면 실결제 키를 저장하는 창이 열립니다.

**3. 클라이언트 키와 시크릿 키를 넣는다**

개발자센터에서 복사한 키를 '클라이언트 키'와 '시크릿 키'에 넣고 저장합니다.

**4. 저장 결과를 확인한다**

MeterEngine은 저장하기 전에 시크릿 키로 토스페이먼츠에 결제 조회를 한 번 보내 키가 유효한지 확인합니다. 이 확인은 결제를 만들지 않습니다. 저장되면 키 목록에 결제 모드, '관리 상태', '시크릿 키 끝 네 글자', '확인 시각', '저장 시각'이 보입니다.

시크릿 키는 암호화해 저장하고 원문을 다시 보여 주지 않습니다. 목록과 API 응답에는 마지막 네 자(`secret_key_last_four`)만 나옵니다.

### 저장이 거절될 때

| 상태 | code | 뜻과 할 일 |
| - | - | - |
| 400 | `invalid_toss_payments_credential` | 키의 앞부분이 업무 환경과 맞지 않거나, 시크릿 키에 콜론, 공백, ASCII 밖 문자가 있거나, 토스페이먼츠가 시크릿 키를 거절했습니다. 어느 칸이 틀렸는지는 응답의 `errors`에 있습니다. 개발자센터에서 키를 다시 복사하세요. |
| 503 | `toss_payments_unavailable` | 토스페이먼츠 응답으로 키를 확인하지 못했습니다. 키는 저장되지 않았으니 잠시 뒤 다시 저장하세요. |

> [!WARNING]
>
> 클라이언트 키는 앞부분만 검사하고 토스페이먼츠에 확인하지 않습니다. 시크릿 키와 다른 상점의 클라이언트 키를 넣어도 저장됩니다. 두 키를 같은 상점의 'API 키' 메뉴에서 복사하고, 저장한 뒤 테스트 환경에서 카드 등록까지 한 번 해 보세요.

## 키를 바꾸거나 멈출 때

* **교체**: '토스 키 저장'으로 새 키를 저장하면 이전 키를 덮어씁니다. 이전 키는 키 목록 위 '토스 키 관리 상태'에서 '보관됨'이나 '전체'를 고르면 볼 수 있습니다. 새로 만드는 카드 등록 링크는 새 키를 씁니다.
* **보관**: 키 목록의 '토스 키 보관'을 누르면 그 환경의 새 결제와 카드 등록이 멈춥니다. 이미 진행 중인 결제의 결과 확인과 결제 취소에는 보관한 키를 계속 씁니다. 다시 쓰려면 키를 다시 저장합니다.

> [!WARNING]
>
> 키를 교체해도 이미 등록한 고객 카드는 그 카드의 등록 링크를 만들 때 저장되어 있던 키로 계속 결제합니다. 교체 전에 만든 링크로 교체 뒤에 등록한 카드도 이전 키로 결제합니다. 다른 상점의 키로 바꿨다면 새 링크를 만들어 고객에게 카드를 다시 등록받아야 새 상점으로 결제됩니다. 카드 등록 방법은 [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md)에 있습니다.

## 토스페이먼츠 웹훅 등록

토스페이먼츠 웹훅을 등록하면 결제 상태가 바뀔 때 토스페이먼츠가 MeterEngine에 바로 알려 줍니다. 등록하지 않아도 MeterEngine이 결과를 확인하지 못한 결제를 주기적으로 다시 조회하므로 결과는 들어오지만, 등록하면 더 빨리 반영됩니다.

**1. 도입사 id를 확인한다**

웹훅 주소에는 도입사 id(UUID)가 들어갑니다. read 권한 API 키로 `GET /v1/organization`을 부르면 응답의 `id`가 도입사 id입니다. 콘솔 주소창의 `organization_id=` 뒤 값도 같은 값입니다.

```bash curl theme={null}
curl https://meterengine.com/v1/organization \
  -H "Authorization: Bearer me_test_xxxxxxxx"
```

```javascript Node theme={null}
const response = await fetch("https://meterengine.com/v1/organization", {
  headers: { Authorization: "Bearer me_test_xxxxxxxx" },
});
const organization = await response.json();
console.log(organization.id);
```

응답에는 도입사의 `id`, `name`, `status`, `created_at`이 있습니다. 아래 예시에서는 도입사 id가 `7c9e6679-7425-40de-944b-e07fc1f90ae7`이라고 하겠습니다.

**2. 웹훅 주소를 만든다**

주소는 `https://meterengine.com/v1/toss-payments-webhooks/<도입사 id>` 입니다. 위 예시라면 다음과 같습니다.

```text theme={null}
https://meterengine.com/v1/toss-payments-webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7
```

도입사 id는 업무 환경과 관계없이 하나이므로 테스트 결제와 실결제 모두 이 주소 하나로 받습니다.

**3. 토스페이먼츠 개발자센터에 등록한다**

개발자센터의 웹훅 메뉴에서 '웹훅 등록하기'를 누르고, 이름과 위 주소를 넣은 뒤 이벤트로 `PAYMENT_STATUS_CHANGED`를 고릅니다. 토스페이먼츠 웹훅은 상점(MID)마다 따로 설정하므로 MeterEngine에 키를 넣은 상점마다 등록합니다. 메뉴 위치는 [토스페이먼츠 웹훅 가이드](https://docs.tosspayments.com/guides/v2/webhook)에 있습니다.

MeterEngine은 토스페이먼츠가 보낸 본문을 그대로 믿지 않습니다. `PAYMENT_STATUS_CHANGED`일 때만 본문의 주문번호로 결제 시도를 찾고, 그 시도에 쓴 키로 토스페이먼츠에 결제를 다시 조회해 결과 확인 중인 결제와 취소에 반영합니다. 본문을 읽을 수 없거나, 다른 이벤트이거나, 반영할 결제 시도가 없으면 아무것도 바꾸지 않고 200으로 답합니다. 다시 조회한 결과를 확인하지 못하면 500으로 답해 토스페이먼츠가 다시 보내게 합니다.

> [!NOTE]
>
> 이 주소는 토스페이먼츠가 부르는 주소입니다. 도입사 서버에서 직접 부르지 마세요. 도입사가 결제 결과를 받으려면 MeterEngine 통보를 등록합니다. [웹훅 받기 시작하기](https://docs.meterengine.com/webhooks/overview.md)

## 다음 단계

> [card] [테스트 결제와 실결제](https://docs.meterengine.com/payments/test-and-live.md)
>
> 테스트 환경에서 먼저 확인하고 실제 환경으로 옮기기

> [card] [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md)
>
> 고객에게 카드를 등록받기


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.