# 구매자 아이디 (payerId)

`payerId`는 point3가 제공하는 가맹점 자체 페이에 등록한 구매자를 식별하는 값입니다. 구매자가 계좌를 등록하면 발급되며, 같은 구매자는 항상 같은 값으로 식별됩니다.

1. **가맹점에서 결제하기**: point3 결제를 시작합니다.
2. **휴대폰에서 계좌 등록**: 가맹점 자체 페이에 계좌를 등록합니다.
3. **구매자 아이디 발급**: 등록한 구매자를 payerId로 식별합니다.

- 같은 구매자는 다시 결제해도 같은 payerId로 식별됩니다.
- 가맹점은 이 값을 회원 정보에 저장해 다음 결제에 사용합니다.

| 값 | 형식 | 사용하는 곳 |
| --- | --- | --- |
| 구매자 아이디 | `payer:...` | 가맹점 화면: 다음 결제의 결제창을 열 때 전달 |

가맹점 서버의 회원 정보에 `payerId`를 저장해 두었다가 다음 결제에 전달하면, 구매자는 일부 인증 단계를 건너뛰고 더 빠르게 결제할 수 있습니다. `payerId`는 point3가 발급하는 값이므로 가맹점이 직접 만들거나 형식을 바꿀 수 없습니다.

## payerId를 받는 곳

| 흐름 | 받는 곳 | 위치 |
| --- | --- | --- |
| JavaScript SDK 결제 | `successUrl`의 `payerId` 쿼리 파라미터 | 가맹점 화면 |
| 등록 전용 위젯 | `successUrl`의 `payerId` 쿼리 파라미터 | 가맹점 화면 |
| 결제 세션 조회 API | 응답의 `payerId` | 가맹점 서버 |

## 화면에서 받은 값과 서버에서 조회한 값

가맹점 화면에서 받은 `payerId`는 바로 저장하고 사용할 수 있습니다. 다만 브라우저를 거쳐 전달되는 값이므로, 결제에서는 결제 세션 조회 응답의 `payerId`로 한 번 더 확인하세요.

결제 세션 조회 API는 가맹점 서버가 API 키로 point3에 직접 요청하므로 조작될 수 없습니다. 결제 세션 조회 응답의 `payerId`가 가장 정확한 값입니다.

```http
GET https://api.point3.io/payment/v3/session/{sessionId}
```

```json title="결제 세션 조회 응답 (일부)"
{
  "id": "pymt_sess-019f0000-0000-7000-9000-000000000000",
  "status": "captured",
  "payerId": "payer:00000000000000000000000000"
}
```

<Callout type="info" title="결제 승인 응답에는 payerId가 없습니다">
  결제 승인 API 응답에는 `payerId`가 포함되지 않습니다. 결제 결과를 확인할 때 결제 세션 조회 API를 함께 호출하고, 응답의
  `payerId`를 사용하세요.
</Callout>

## 저장하기

### 결제

1. 가맹점 화면에서 받은 `payerId`를 가맹점 서버에 전달합니다.
2. 결제 승인 후 결제 세션을 조회해 응답의 `payerId`가 화면에서 받은 값과 같은지 확인합니다.
3. 결제 세션 조회 응답의 `payerId`를 해당 회원의 값으로 저장합니다.

정상적인 결제에서는 두 값이 같습니다. 값이 다르다면 화면에서 받은 값이 조작된 것이므로, 결제 세션 조회 응답의 `payerId`를 사용하세요.

`payerId`는 가맹점 서버의 회원 정보에 저장하고, 다음 결제에서는 로그인한 회원에게 저장된 값을 서버가 전달하세요. 브라우저 저장소나 앱 내부 저장소에 두는 것은 보안 상의 이유로 권장하지 않습니다.

### 등록 전용 위젯

등록 전용 위젯은 결제 세션 없이 진행되므로, 결제처럼 서버에서 결제 세션을 조회해 `payerId`를 확인할 방법이 없습니다. 등록을 마치면 화면에서 받은 `payerId`를 가맹점 서버에 전달하고, 회원 정보에 저장된 값이 없을 때 저장하세요.

이미 결제 세션 조회를 통해 저장된 값이 있다면, 해당 값을 신뢰하고 화면에서 받은 값으로 덮어쓰지 마세요. 결제 세션 조회로 확인한 값은 가맹점 서버가 point3에서 직접 받은 값이지만, 화면에서 받은 값은 브라우저를 거쳐 전달되므로 조작될 수 있습니다.

## 다음 결제에 전달하기

**첫 결제**: 결제창 열기 → 구매자 계좌 등록 → payerId 수신 → 회원 정보에 저장

**다음 결제**: payerId로 결제창 열기 → 일부 인증 단계 생략 → 같은 payerId 수신 → 회원 정보 갱신

저장된 `payerId`가 있으면 다음 결제에 전달합니다. 결제 세션 조회로 확인한 값이 있으면 그 값을 우선 사용하세요.

| 연동 방식 | 전달하는 곳 | 저장된 값이 없을 때 |
| --- | --- | --- |
| JavaScript SDK | `widgets({ customerKey })`의 `customerKey` | `ANONYMOUS` 사용 |

```js title="JavaScript"
const widgets = point3.widgets({ customerKey: savedPayerId || Point3.ANONYMOUS })
```

```ts title="TypeScript"
const customerKey: string = savedPayerId ?? Point3.ANONYMOUS
const widgets = point3.widgets({ customerKey })
```

자세한 사용법은 [SDK 결제창 연동](/sdk-payment-window#point3widgets)을 참고하세요. 앱에서도 가맹점 서버가 회원 정보의 `payerId`를 전달합니다.

로그인한 회원이라면 가맹점 서버가 저장한 `payerId`로 [위임 인증](/delegated-authentication)을 생성해 결제창의 문자 인증까지 생략할 수 있습니다.

## 주의사항

- 결제 승인 API에는 `payerId`를 전달하지 않습니다.
- 구매자가 point3에서 탈퇴하면 결제창이 `PAYER_DEACTIVATED` 코드로 종료됩니다. [에러 코드](/error-codes#javascript-sdk-결제)를 참고하세요.