> ## 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.

# 테스트 결제와 실결제

> 테스트 환경의 테스트 결제와 실제 환경의 실결제가 어떻게 나뉘고, 테스트 환경에서 무엇을 확인한 뒤 실제 환경으로 옮기는지 설명합니다.

MeterEngine은 지금 미리 보기 단계라 테스트 환경에서 연동을 검증하는 용도로 씁니다. 자세한 내용은 [MeterEngine 소개](https://docs.meterengine.com/index.md)에 있습니다.

## 업무 환경이 결제 모드를 정한다

테스트 환경과 실제 환경에서는 결제 모드가 업무 환경에 고정되어 있습니다. 도입사가 바꿀 수 없고, 바꿀 필요도 없습니다.

| 업무 환경 | 결제 모드 | 받는 토스페이먼츠 키 | 결제 결과 |
| - | - | - | - |
| 테스트 환경 | 테스트 결제 (`test`) | `test_ck_`, `test_sk_` | 실제로 결제되지 않으며 카드에서 출금되지 않습니다 |
| 실제 환경 | 실결제 (`live`) | `live_ck_`, `live_sk_` | 고객 카드에서 실제로 출금됩니다 |

지금 업무 환경의 결제 모드는 '도입사 설정' 화면의 '현재 결제 모드'에 보이고, read 권한 API 키로 `GET /v1/payment-setting`을 불러도 확인할 수 있습니다. 테스트 환경과 실제 환경에서는 응답의 `updated_at`이 늘 `null`입니다.

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

```json 응답 200 theme={null}
{
  "mode": "test",
  "updated_at": null
}
```

토스페이먼츠 키, 고객 카드, 결제 시도, 결제 취소는 모두 업무 환경마다 따로입니다. 테스트 환경에서 등록한 카드로 실제 환경의 인보이스를 결제할 수 없습니다.

테스트 환경도 보낸 이벤트와 확정한 인보이스는 되돌릴 수 없습니다. 테스트 환경이 무엇을 분리하고 무엇은 실제로 일어나는지는 [업무 환경](https://docs.meterengine.com/concepts/environments.md)에 있습니다.

## 테스트 환경에서 확인할 것

**1. 테스트 키를 저장한다**

업무 환경을 '테스트 환경'으로 두고 토스페이먼츠 테스트 키(`test_ck_`, `test_sk_`)를 저장합니다. [토스페이먼츠 상점 준비와 키 저장](https://docs.meterengine.com/payments/toss-setup.md)

**2. 테스트 카드를 등록한다**

시험용 고객에게 카드 등록 링크를 만들어 직접 열어 봅니다. 토스페이먼츠 테스트 환경에서는 본인인증 문자가 오지 않으니 인증번호 칸에 `000000`을 넣습니다. 카드 번호는 앞 여섯 자리(BIN)만 유효하면 등록됩니다. 실제 환경에서는 카드 번호 전체가 유효해야 합니다. [고객 카드 등록 링크](https://docs.meterengine.com/payments/card-registration.md)

**3. 결제를 요청한다**

확정한 인보이스로 결제를 요청하고 `status`가 `done`인지 봅니다. [첫 결제 요청과 결과 확인](https://docs.meterengine.com/payments/charging.md)

**4. 실패를 재현한다**

아래 테스트 헤더로 결제 실패를 일부러 만들어 실패 처리와 통보 수신을 확인합니다.

### 결제 실패 재현하기

테스트 환경에서 결제 실패를 재현하려면 결제 요청에 `TossPayments-Test-Code` 헤더로 토스페이먼츠 오류 코드를 넣습니다(예: `INVALID_REJECT_CARD`). MeterEngine은 값을 그대로 토스페이먼츠에 넘기므로, 실제 거절과 같은 경로로 실패와 자동 재시도 흐름을 미리 확인할 수 있습니다. 넣을 수 있는 오류 코드는 [토스페이먼츠 오류 코드 문서](https://docs.tosspayments.com/reference/error-codes)에서 고릅니다.

```bash curl theme={null}
curl -X POST https://meterengine.com/v1/invoices/9b1d7f3a-2c4e-4a6b-8d0f-1e3a5c7b9d2f/payment-attempts \
  -H "Authorization: Bearer me_test_xxxxxxxx" \
  -H "TossPayments-Test-Code: INVALID_REJECT_CARD"
```

```javascript Node theme={null}
const invoiceId = "9b1d7f3a-2c4e-4a6b-8d0f-1e3a5c7b9d2f";
const response = await fetch(
  `https://meterengine.com/v1/invoices/${invoiceId}/payment-attempts`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer me_test_xxxxxxxx",
      "TossPayments-Test-Code": "INVALID_REJECT_CARD",
    },
  },
);
const attempt = await response.json();
console.log(response.status, attempt.status, attempt.failure_code);
```

거절되면 응답은 `201`이고 `status`가 `failed`, `failure_code`가 넣은 오류 코드, `failure_message`가 토스페이먼츠의 거절 문구입니다. 빈 값을 보내면 헤더를 보내지 않은 것으로 봅니다. 이 헤더는 그 요청 한 번에만 쓰이고, 자동 재시도와 고객 화면에서 다시 하는 결제에는 실리지 않습니다.

> [!NOTE]
>
> `INVALID_REJECT_CARD`처럼 카드 자체의 오류는 고객이 카드를 다시 등록하기 전에는 MeterEngine이 자동으로 다시 시도하지 않는 실패입니다. 자동 재시도를 확인하려면 다시 시도하는 실패 코드를 넣으세요. 어떤 실패를 다시 시도하는지는 [결제 실패와 재시도](https://docs.meterengine.com/payments/retries.md)에 있습니다.

> [!WARNING]
>
> 실제 환경에서 `TossPayments-Test-Code` 헤더를 보내면 MeterEngine이 `400 toss_payments_test_code_in_live_mode`로 거절하고 결제 시도를 만들지 않습니다. 실제 환경으로 옮길 때 연동 코드에서 이 헤더를 빼세요.

## 실제 환경으로 옮기기

테스트 환경의 데이터는 실제 환경으로 복사되지 않습니다. 실제 환경에서 아래를 처음부터 다시 준비합니다.

**1. 토스페이먼츠 자동결제 계약을 맺는다**

실결제 자동결제는 토스페이먼츠의 리스크 검토와 계약 뒤에 쓸 수 있습니다. [토스페이먼츠 상점 준비와 키 저장](https://docs.meterengine.com/payments/toss-setup.md)

**2. 업무 환경을 실제 환경으로 바꾼다**

화면 위 '업무 환경'에서 '실제 환경'을 고르고 '전환'을 누릅니다.

**3. 미터, 단가, 고객을 다시 만든다**

고객, 미터, 단가는 업무 환경마다 따로 만들어야 합니다. [업무 환경](https://docs.meterengine.com/concepts/environments.md)

**4. 실제 환경 API 키와 통보를 준비한다**

실제 환경에서 API 키를 발급하면 `me_live_`로 시작하는 키가 나옵니다. MeterEngine 통보 수신 주소도 실제 환경에 다시 등록합니다. [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md), [웹훅 받기 시작하기](https://docs.meterengine.com/webhooks/overview.md)

**5. 실결제 토스페이먼츠 키를 저장한다**

계약한 상점의 `live_ck_`, `live_sk_` 키를 저장합니다. 토스페이먼츠 웹훅 주소는 테스트 환경과 같은 주소를 쓰고, 실결제 상점(MID)에도 등록되어 있는지 확인합니다.

**6. 고객에게 카드를 다시 등록받는다**

실제 환경의 고객마다 카드 등록 링크를 새로 만들어 전달합니다. 테스트 환경에서 등록한 카드는 실제 환경에서 쓰이지 않습니다.

## API 키의 모드와 결제 모드

결제 요청과 카드 등록 링크 만들기는 API 키의 모드와 업무 환경의 결제 모드가 다르면 `409 payment_mode_mismatch`로 거절됩니다. 테스트 환경에서 발급한 키는 테스트 결제, 실제 환경에서 발급한 키는 실결제에 고정되어 있어 두 환경에서는 이 오류가 나지 않습니다. 이 오류가 나면 '기존 데이터'에서 발급한 키를 쓰고 있는지 확인하세요.

> [accordion] 기존 데이터 환경의 결제 모드
>
> 업무 환경이 '기존 데이터'일 때만 '도입사 설정' 화면에서 결제 모드를 바꿀 수 있습니다('결제 모드 변경'). 실결제로 바꾸려면 실결제 토스페이먼츠 키를 먼저 저장해야 하고, 없으면 `409 toss_payments_credential_missing`으로 거절됩니다. 새로 연동한다면 테스트 환경과 실제 환경을 쓰세요. 두 환경은 결제 모드가 고정이라 바꿀 필요가 없습니다.


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