결제 생성
판매자 서버에서 구매자에게 전달할 호스팅 결제 페이지를 생성합니다.
POST
https://pay.apiacc.com/request새로운 Hosted Payment 세션을 생성하고, 구매자에게 전달할 checkout_url을 반환합니다.
키 사용 범위
이 요청은 판매자 서버에서만 호출해야 합니다. 응답에 포함된
checkout_url만 구매자에게 전달하고, ak_live_ API 키는 절대 클라이언트나 구매자에게 노출하지 마세요.요청 본문
| 필드 | 타입 | 필수 | 제한 | 예시 |
|---|---|---|---|---|
refAPI 키 단위로 멱등하게 동작하는 고유 참조 번호입니다. | string | 필수 | — | "order_1234" |
name구매자 표시 이름입니다. 계좌이체 선택 시 입금자명으로 사용됩니다. | string | 필수 | — | "홍길동" |
content결제 페이지에 표시할 상품/주문 설명입니다. | string | 필수 | — | "게임 캐시 충전" |
amount결제 요청 금액입니다. KRW 정수입니다. | integer | 필수 | — | 10000 |
curl -X POST "https://pay.apiacc.com/request" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Content-Type: application/json" \
--max-time 10 \
-d '{
"ref": "order_1234",
"name": "홍길동",
"content": "게임 캐시 충전",
"amount": 10000
}'응답
201결제 생성 성공
{
"payment": {
"id": "pay_xxx",
"ref": "order_1234",
"name": "홍길동",
"content": "게임 캐시 충전",
"amount": 10000,
"status": "pending",
"method": null,
"expires_at": "2026-08-15T12:10:00Z"
},
"checkout_url": "https://pay.apiacc.com/pay/pub_xxx",
"idempotent_replay": false
}같은 ref로 이미 생성된 결제가 있으면 idempotent_replay가 true인 채로 기존 결제와 checkout_url이 그대로 반환됩니다.
멱등 응답 예시
{
"payment": {
"id": "pay_xxx",
"ref": "order_1234",
"status": "pending"
},
"checkout_url": "https://pay.apiacc.com/pay/pub_xxx",
"idempotent_replay": true
}주요 오류
| 상태 | error | 설명 |
|---|---|---|
| 400 | invalid_ref | — |
| 400 | invalid_name | — |
| 400 | invalid_content | — |
| 400 | invalid_amount | — |
| 409 | payment_method_not_configured | 결제 수단이 하나도 설정되지 않아 결제 페이지를 생성할 수 없습니다. |
| 409 | ref_conflict | 동일한 ref가 다른 amount로 이미 사용 중입니다. |
| 429 | rate_limit_exceeded | — |