PIN 결제
구매자가 입력한 문화상품권 PIN을 제출하여 결제 금액을 충전합니다.
POST
https://pay.apiacc.com/pay/{token}/pins결제를 cultureland_pin으로 잠그고, 제출된 PIN을 순서대로 처리하는 배치를 시작합니다.
경로 파라미터
| 필드 | 타입 | 필수 | 제한 | 예시 |
|---|---|---|---|---|
token결제 생성 응답의 checkout_url에 포함된 공개 토큰입니다. | string | 필수 | — | "pub_xxx" |
요청 본문
| 필드 | 타입 | 필수 | 제한 | 예시 |
|---|---|---|---|---|
pins제출할 문화상품권 PIN 번호 목록입니다. 같은 요청 안에서 중복된 PIN은 허용되지 않습니다. | string[] | 필수 | 1~10개 | ["3110-0123-4567-8901"] |
curl -X POST "https://pay.apiacc.com/pay/pub_xxx/pins" \
-H "Content-Type: application/json" \
--max-time 10 \
-d '{
"pins": [
"3110-0123-4567-8901",
"3110-9876-5432-1098"
]
}'응답
202PIN 배치 접수 성공
{
"payment": {
"id": "pay_xxx",
"amount": 10000,
"status": "processing",
"method": "cultureland_pin"
},
"batch_id": "batch_xxx",
"accepted_count": 2,
"status": "processing"
}처리 방식
- PIN은 한 번에 하나씩 순서대로 처리됩니다. 여러 PIN을 동시에 병렬로 처리하지 않습니다.
- 누적 충전 금액이 결제 금액에 도달하면 처리를 즉시 중단합니다. 남은 PIN은 처리되지 않고 그대로 남습니다.
- 이미 처리 중인 배치가 있는 상태에서 다시 요청하면
payment_processing오류가 반환됩니다. 배치가 끝난 뒤 다시 제출하세요.
review_required로 이어지는 경우
Cultureland 응답이 타임아웃되거나 처리 중 연결이 끊겨 실제 충전 여부가 불명확한 경우, 해당 PIN은 자동으로 재시도되지 않고 결제 상태가
review_required로 전환됩니다. 이 상태는 수동 확인이 필요하며, 결제 세션 조회로 최신 pin_charges 내역을 확인하세요.주요 오류
| 상태 | error | 설명 |
|---|---|---|
| 404 | payment_not_found | — |
| 409 | payment_complete | 이미 최종 상태로 확정된 결제입니다. |
| 409 | payment_processing | 이전 PIN 배치가 아직 처리 중입니다. |
| 409 | payment_expired | — |
| 409 | payment_review_required | — |
| 409 | payment_method_locked | 이미 다른 결제 수단으로 확정되어 PIN 결제로 전환할 수 없습니다. |
| 409 | pin_settings_required | 판매자가 Cultureland PIN 결제 수단을 아직 설정하지 않았습니다. |
| 400 | invalid_pins | pins 배열이 비어 있거나 10개를 초과했습니다. |
| 400 | invalid_pin | PIN 형식이 올바르지 않습니다. |
| 400 | duplicate_pin | 같은 요청에 동일한 PIN이 두 번 이상 포함되었습니다. |
| 409 | pin_already_submitted | 이미 이전 요청에서 제출되어 처리되었거나 처리 중인 PIN입니다. |
| 429 | rate_limit_exceeded | — |