결제 설정
결제 연결 — 직접 계약한 PG 연결, 테스트 키와 라이브 키, 샌드박스 모드, 간편결제, 결제 도메인, 결제 옵션 순서
셀러가 직접 계약한 PG(토스페이먼츠·포트원)를 연결해 결제를 받습니다. 대금은 PG가 바로 정산합니다.
준비
- 소유자 권한
- PG와 맺은 계약과 테스트 키
연결 순서
상점 플랫폼에서 설정 › 결제로 이동합니다(소유자만).
- [PG 추가] 카드를 누르고 연결할 PG의 **[연결]**을 누릅니다.
- 테스트 키를 입력하고 **[연결]**을 누릅니다.
- PG 카드의 **[상세]**로 들어가 테스트 키 카드의 **[연결 테스트]**를 누릅니다.
- 사용 카드의 결제에 사용을 켭니다. 목록의 PG 카드에서도 켤 수 있습니다.
새로 연결한 PG는 샌드박스 모드, 사용 중지 상태로 저장됩니다. 샌드박스 결제는 실제로 돈이 오가지 않습니다.
실결제는 샌드박스에서 라이브로 전환하기를 따르십시오.
테스트 키와 라이브 키
PG마다 테스트 키와 라이브 키를 따로 등록하고 따로 연결 테스트합니다. 샌드박스 모드가 켜져 있으면 테스트 키, 꺼져 있으면 라이브 키로 결제합니다. 라이브 키를 저장해도 바로 실결제로 바뀌지 않습니다. 비밀 값은 앞 4자리만 보이고, **[수정]**에서 비워 두면 저장된 값을 그대로 씁니다.
토스페이먼츠
API 개별 연동 키를 씁니다. 결제위젯 키(_gck_·_gsk_)는 받지 않습니다.
| 항목 | 구분 | 테스트 키 | 라이브 키 |
|---|---|---|---|
| 클라이언트 키 | 공개 값 | test_ck_로 시작 | live_ck_로 시작 |
| 시크릿 키 | 비밀 값 · 필수 | test_sk_로 시작 | live_sk_로 시작 |
| 웹훅 시크릿 | 비밀 값 · 선택 | 서명 검증용 | 서명 검증용 |
포트원
포트원 관리자 상점 플랫폼에서 Store ID·V2 API Secret을 확인하고 PG사 채널을 추가해 채널 키를 받습니다. 테스트 키에는 테스트 채널, 라이브 키에는 실연동 채널을 넣습니다.
| 항목 | 구분 | 형식 |
|---|---|---|
| Store ID | 공개 값 | store-로 시작 |
| 채널 키 | 공개 값 | channel-key-로 시작. 채널마다 달라야 함 |
| 채널 이름 | 공개 값 · 선택 | 상점 플랫폼에서 채널을 구분하는 이름 |
| 결제수단 | 공개 값 | 카드·계좌이체·가상계좌·휴대폰·간편결제 중 1개 이상 |
| API Secret | 비밀 값 · 필수 | 16자 이상 |
| 웹훅 시크릿 | 비밀 값 · 선택 | whsec_로 시작 |
채널은 20개까지이고, 결제수단마다 먼저 나오는 채널로 결제합니다. 어느 채널도 받지 않는 결제수단은 결제 옵션에 나오지 않습니다. 가상계좌는 두 PG 모두 아직 지원하지 않습니다.
연결 테스트
**[연결 테스트]**는 저장된 키로 PG에 연결되는지 확인하고 결과를 마지막 연결 테스트에 남깁니다. 키를 수정하면 결과가 지워지므로 다시 테스트하십시오. 라이브로 결제 중에 라이브 키를 수정하면 저장 전에 연결 테스트를 하고, 실패하면 저장하지 않습니다.
| 상태 | 의미 |
|---|---|
| 미연결 | 키를 아직 저장하지 않음 |
| 사용 중지 | 연결됐지만 결제에 쓰지 않음 |
| 사용중 | 결제에 쓰는 중 |
| 결제 제외 | 켜져 있지만 새 결제에 쓰이지 않음. 한 환경만 쓰는 결제 참고 |
| 연결 확인 실패 | 지금 결제에 쓰는 키의 마지막 연결 테스트 실패 |
한 환경만 쓰는 결제
사용 중인 PG 중 하나라도 라이브면 상점 결제는 모두 실결제이고 샌드박스 PG는 결제 제외가 됩니다. 두 PG를 함께 쓰려면 둘 다
라이브로 전환하십시오.
| 화면 안내 | 뜻 |
|---|---|
| 지금은 테스트 결제만 받습니다 | 사용 중인 PG가 모두 샌드박스 모드 |
| 샌드박스 PG는 실구매자 결제에 쓰이지 않습니다 | 라이브 PG가 있어 샌드박스 PG가 빠짐 |
| 결제에서 빠진 PG가 있습니다 | 키 누락·실결제 중단·라이브 재전환 필요로 빠진 PG가 있음. PG 상세에서 사유 확인 |
가맹점 교체와 연결 해제
같은 가맹점(토스페이먼츠 클라이언트 키, 포트원 Store ID)으로 수정하면 키를 갱신하고, 가맹점을 바꾸면 이전 키를 보관합니다.
보관한 키(보관된 연결 정보 N건)는 그 가맹점 결제의 취소·환불에만 쓰고 지울 수 없습니다. 예전 가맹점으로 되돌리면 다시 씁니다.
| 작업 | 위치 | 결과 |
|---|---|---|
| 키 삭제 | 키 카드의 [삭제] | 지금 결제에 쓰지 않는 쪽 키만 가능. 삭제한 키는 보관돼 환불에 계속 씀 |
| 연결 해제 | PG 상세 머리의 더보기 › [연결 해제] | 결제 이력이 있어도 가능. 키는 모두 보관 |
| 잠시 중지 | 결제에 사용 끄기 | 이미 받은 결제의 취소·환불은 계속 처리 |
간편결제
PG 카드의 **[상세]**에서 간편결제 카드를 열고 네이버페이·카카오페이·토스페이·페이코를 켭니다. 켠 만큼 결제 옵션이 생기고 그 결제창이 바로 열립니다. PG 계약에 추가한 간편결제만 켜십시오(포트원은 받는 채널도 필요).
결제 도메인
결제를 마친 구매자가 돌아올 쇼핑몰 주소입니다(선택).
- 비워 두면 모든
https주소로 돌아옵니다. 테스트 결제는localhost도 됩니다. - 등록하면 그 도메인으로만 돌아오고, 목록 밖 복귀 주소는
400 RETURN_URL_NOT_ALLOWED입니다. 쇼핑몰 주소가 정해졌다면 등록하십시오.
PG 가맹 정보에 등록할 도메인은 결제 도메인과 다를 수 있습니다(결제창은 sayren 결제 화면에서 열립니다).
결제 옵션 순서
결제 옵션 순서 카드의 순서가 스토어프론트 결제 옵션에 PG가 나오는 순서입니다. **[순서 편집]**에서 PG를 옮기고 **[저장]**합니다. 결제할 PG는 구매자가 고른 옵션이 정하고, 장애가 나도 다른 PG로 자동으로 넘어가지 않습니다.
결제를 받을 수 없는 상태
사용 중인 PG가 없으면 지금은 결제를 받을 수 없습니다 경고가 뜨고, 결제 시작은 409 PAYMENT_NOT_CONFIGURED입니다.
결제 없이도 쇼핑몰은 공개할 수 있습니다. 그때 스토어프론트 GET /store의 checkoutAvailable이 false라 쇼핑몰은 주문 버튼 대신
「지금은 온라인 주문을 받지 않습니다」를 보입니다.
checkoutAvailable | checkoutMode | checkoutUnavailableReason | 조건 |
|---|---|---|---|
true | LIVE | null | 라이브 PG가 있습니다 |
true | TEST | null | 샌드박스 PG만 있고 호스팅 쇼핑몰이 공개 전입니다(테스트 결제) |
false | null | PAYMENT_NOT_CONFIGURED | 사용 중인 PG가 없습니다 |
false | null | PAYMENT_NOT_LIVE | 샌드박스 PG만 있는데 호스팅 쇼핑몰을 공개했습니다 |
결제 시작의 409 PAYMENT_NOT_CONFIGURED는 error.details.reason에 NO_PROVIDER(PG 없음)나 NOT_LIVE(공개한 쇼핑몰의 실결제가 아직 열리지 않음)를 싣습니다.
| 상황 | 결과와 조치 |
|---|---|
| 플랫폼이 실결제를 멈춤 | 라이브 PG가 새 결제에서 빠지고 샌드박스로 대신 결제하지 않음. 다시 열리면 자동 재개. 환불은 계속 처리 |
| PG 카드에 라이브 전환을 다시 해야 해서 결제에서 빠집니다 | 샌드박스 모드를 켰다가 라이브로 다시 전환 |
결제 시작이 503 PAYMENT_PROVIDER_UNAVAILABLE | 고른 PG가 결제창을 준비하지 못함. 연결 테스트로 키·장애 확인 |
반복해서 실패하는 결제수단
같은 PG·결제수단·간편결제사가 PG 설정 문제로 최근 24시간에 3번 이상 실패하면 반복해서 실패하는 결제수단이 있습니다 경고가 뜹니다.
예를 들어 KG이니시스 V105 [NO MPI SET] 전용화면 미설정은 PG 관리자에 그 결제수단의 전용 화면이 설정되지 않았다는 뜻입니다.
- 경고에는 조합, 횟수, 마지막 실패 시각, PG 원문 사유가 나옵니다. PG 관리자에서 해당 결제수단의 전용 화면·채널을 설정하십시오.
- 구매자에게는 「이 결제수단은 지금 사용할 수 없습니다. 다른 결제수단을 선택하십시오」가 보입니다. 결제 옵션에서 자동으로 빠지지는 않습니다.
- 소유자에게 메일로도 알립니다. 같은 상점에는 하루에 한 번까지 보냅니다.
- 설정을 고친 뒤 새 실패가 없으면 24시간 안에 경고가 사라집니다.
API로는 결제 설정 조회 응답의 warnings(provider·method·easyPayProvider·code·count·lastAt·message)입니다.
API
조회는 store:r, 변경은 store:rw이고 상점 플랫폼에 로그인한 OWNER의 토큰만 받습니다. 그 밖의 토큰(ADMIN·STAFF, 액세스 토큰,
CLI·연동 앱)은 403 INSUFFICIENT_ROLE입니다. 양도·역할 변경 뒤에는 토큰을 다시 받으십시오.
| 요청 | 설명 |
|---|---|
GET /store/payment-settings | 결제 도메인과 PG 전체의 연결 상태 |
PUT /store/payment-settings | priority(연결된 PG를 모두 한 번씩)·checkoutOrigins 변경. 보낸 항목만 바뀜 |
PUT /store/payment-providers/tosspayments | 토스페이먼츠 키 등록·수정. environment는 저장할 키(TEST·LIVE) |
PUT /store/payment-providers/portone | 포트원 키 등록·수정 |
PATCH /store/payment-providers/{provider} | enabled·sandboxMode·easyPayProviders 중 하나 이상 |
POST /store/payment-providers/{provider}/verify | 연결 테스트. { "environment": "LIVE" }로 대상 선택, 생략하면 지금 결제에 쓰는 키 |
DELETE /store/payment-providers/{provider}/credentials/{environment} | 지금 결제에 쓰지 않는 쪽 키 삭제(보관) |
DELETE /store/payment-providers/{provider} | 연결 해제. 키는 모두 보관 |
비밀 값은 secrets[].masked로만 옵니다. 수정할 때 비밀 필드를 빼면 유지하고 webhookSecret: null은 웹훅 시크릿을 지웁니다.
| PG 필드 | 내용 |
|---|---|
environment | 그 PG가 지금 결제에 쓰는 쪽 |
credentialSets.TEST · credentialSets.LIVE | 두 키의 상태 |
liveGate | 라이브 전환 조건. 샌드박스에서 라이브로 전환하기 참고 |
retiredCredentialCount | 보관한 연결 정보 개수 |
routingExclusion | 후보에서 빠진 사유. 후보면 null |
설정 응답의 candidates는 지금 결제에 쓰는 PG(우선순위순)이고, 비어 있으면 결제할 수 없습니다. 설정 응답의 environment는
그 결제의 환경(TEST·LIVE, 후보가 없으면 null)입니다.
routingExclusion | 사유 |
|---|---|
NOT_CONNECTED | 연결하지 않음 |
DISABLED | 사용 중지 |
CREDENTIAL_MISSING | 지금 결제에 쓸 키가 없음 |
SANDBOX_IN_LIVE_STORE | 다른 PG가 라이브라 샌드박스 PG를 쓰지 않음 |
PLATFORM_BLOCKED | 플랫폼이 실결제를 멈춤 |
MODE_MISMATCH | 전환 뒤 플랫폼 결제 처리 방식이 바뀜. 샌드박스 모드를 켰다가 라이브로 다시 전환 |
사유는 늘어날 수 있으므로 모르는 값은 후보가 아닌 것으로 다루십시오. 현재 목록은 Store SDK의 PAYMENT_ROUTING_EXCLUSION_CODES입니다.
| 코드 | 상황 |
|---|---|
400 VALIDATION_FAILED | 요청 형식 오류. 결제위젯 키면 fieldErrors에 credentials.clientKey·credentials.secretKey |
400 INVALID_CREDENTIALS | 키 형식이 틀렸거나 environment와 맞지 않음 |
400 PAYMENT_PROVIDER_INCOMPLETE | 처음 등록하는데 시크릿 키나 API Secret이 없음 |
400 INVALID_PRIORITY | priority에 연결된 PG가 빠졌거나 중복됨 |
404 PAYMENT_PROVIDER_NOT_FOUND | 연결되지 않은 PG |
404 PAYMENT_CREDENTIAL_NOT_FOUND | 삭제하려는 키가 없음 |
409 PAYMENT_PROVIDER_INCOMPLETE | 사용을 켜려는데 지금 결제에 쓸 키가 없거나 모자람 |
409 PAYMENT_PROVIDER_VERIFICATION_FAILED | 라이브 결제 중 라이브 키 저장 전 연결 테스트 실패 |
409 PAYMENT_CREDENTIAL_ACTIVE | 지금 결제에 쓰는 키를 삭제하려 함 |
409 LIVE_GATE_NOT_MET | 라이브 전환 조건 미충족 |
409 LIVE_PAYMENTS_DISABLED | 플랫폼이 아직 실결제를 허용하지 않음 |
409 PAYMENT_CREDENTIAL_CHANGED · 409 PAYMENT_PROVIDER_CHANGED | 다른 요청이 키나 스위치를 먼저 바꿈. 다시 조회한 뒤 재시도 |
TypeScript에서는 Store SDK의 paymentSettings를 씁니다. SDK는 보내기 전에 본문을 검증하므로
결제위젯 키는 ZodError로 먼저 막힙니다.