개요
Hosted Payment는 판매자의 API 키를 노출하지 않고, 구매자에게 안전하게 결제 페이지를 제공하는 기능입니다.
판매자 서버가 https://pay.apiacc.com/request로 결제를 생성하면, apiacc는 구매자에게 전달할 수 있는 짧은 만료 시간의 결제 페이지 URL(checkout_url)을 반환합니다. 구매자는 이 페이지에서 계좌이체 또는 PIN 결제 중 하나를 선택해 직접 결제를 진행합니다.
API 키가 노출되지 않는 구조
- 결제 생성 요청에는 판매자의
ak_live_키가 필요하지만, 구매자에게는 절대 전달되지 않습니다. - 구매자가 접근하는 공개 페이지와 API는
checkout_url에 포함된 무작위 공개 토큰(pub_xxx)만으로 동작하며, 인증 헤더가 필요 없습니다. - 공개 토큰은 해당 결제 세션 하나에만 유효하며, 결제 상태가 확정되면 더 이상 사용할 수 없습니다.
ref 기반 멱등성
ref는 API 키 단위로 멱등하게 동작합니다. 같은 ref로 다시 요청하면 기존 결제가 반환되며, 새 결제가 생성되지 않습니다. 단, 같은 ref를 다른 amount로 재요청하면 ref_conflict 오류가 반환됩니다.
결제 수단 구성
구매자에게 노출되는 결제 수단은 판매자가 사전에 설정을 완료한 항목만 표시됩니다.
| 필드 | 타입 | 필수 | 제한 | 예시 |
|---|---|---|---|---|
bank_transfer계좌이체 결제를 사용하려면 은행명, 계좌번호, 예금주 정보가 미리 등록되어 있어야 합니다. | 결제 수단 | 필수 | — | 은행명, 계좌번호, 예금주 |
cultureland_pinPIN 결제를 사용하려면 Cultureland 계정(ID, KeepLoginConfig)이 PIN API 설정에 등록되어 있어야 합니다. | 결제 수단 | 필수 | — | Cultureland ID |
결제 상태
| 필드 | 타입 | 필수 | 제한 | 예시 |
|---|---|---|---|---|
pending결제 수단이 아직 선택되지 않은 초기 상태입니다. | 진행 중 | 선택 | — | — |
processing계좌이체 대기 또는 PIN 배치가 처리 중인 상태입니다. | 진행 중 | 선택 | — | — |
partial일부 금액만 충족되어 추가 PIN 제출을 기다리는 상태입니다. | 진행 중 | 선택 | — | — |
approved결제 금액이 모두 충족되어 확정된 상태입니다. | 최종 | 선택 | — | — |
rejected결제가 거절되어 더 이상 진행할 수 없는 상태입니다. | 최종 | 선택 | — | — |
expired만료 시각이 지나 결제 세션이 종료된 상태입니다. | 최종 | 선택 | — | — |
review_required처리 결과가 불명확하여 수동 확인이 필요한 상태입니다. 자동으로 재시도되지 않습니다. | 최종 | 선택 | — | — |
최종 상태
approved, rejected, expired, review_required는 더 이상 상태가 바뀌지 않는 최종 상태입니다. 결제 완료 여부는 approved 상태만 확인하세요.완료 알림
구매자의 결제가 처음으로 approved가 되는 순간, apiacc는 판매자에게 payment.approved Webhook 이벤트를 전송합니다. Hosted Payment 계좌이체가 거절되면 payment.rejected 이벤트가 전송될 수 있습니다. 이 알림을 받으려면 판매자 계정에 platform이 default인 Webhook이 먼저 등록되어 있어야 합니다. 결제 완료 처리는 payment.approved만 성공으로 판단하세요. 실시간 진행 상황을 화면에 표시하려면 결제 이벤트 스트림 문서를 참고하세요.