연동 가이드

구매자 아이디 (payerId)

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

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

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

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

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

payerId를 받는 곳

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

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

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

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

코드
GET https://api.point3.io/payment/v3/session/{sessionId}

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

결제 승인 응답에는 payerId가 없습니다

결제 승인 API 응답에는 payerId가 포함되지 않습니다. 결제 결과를 확인할 때 결제 세션 조회 API를 함께 호출하고, 응답의 payerId를 사용하세요.

저장하기

결제

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

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

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

등록 전용 위젯

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

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

다음 결제에 전달하기

첫 결제

결제창 열기

구매자 계좌 등록

payerId 수신

회원 정보에 저장

저장한 payerId를 다음 결제에 전달

다음 결제

payerId로 결제창 열기

일부 인증 단계 생략

같은 payerId 수신

회원 정보 갱신

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

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

const widgets = point3.widgets({ customerKey: savedPayerId || Point3.ANONYMOUS })

자세한 사용법은 SDK 결제창 연동을 참고하세요. 앱에서도 가맹점 서버가 회원 정보의 payerId를 전달합니다.

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

주의사항

결제 승인 API에는 payerId를 전달하지 않습니다.
구매자가 point3에서 탈퇴하면 결제창이 PAYER_DEACTIVATED 코드로 종료됩니다. 에러 코드를 참고하세요.

마지막 수정: 2026년 10월 27일

결제 흐름과 상태 위임 인증