API 객체

Payment

결제자 측 결제 의도를 나타내는 핵심 객체.

필드	타입	비고
id	string	pi_...
amount	integer	최소 단위
currency	string	USDT, USDC, ETH, SOL
network	string	POLYGON, ETHEREUM, SOLANA
status	enum	pending, processing, succeeded, failed, expired, canceled
pay_address	string	결제자가 송금할 주소
expires_at	timestamp	이 시점 이후 미결제 시 status → expired
settlement	object	아래 Settlement 참조
metadata	object	임의 키/값 (최대 50 키, 값당 500자)

상태 전이

• succeeded → refunded: Refund API 를 통해 발생.
• succeeded → failed: 정산 이후 차지백 또는 온체인 결제 취소.
• pending → canceled: 온체인 송금 전에 호출자가 취소.
• pending → expired: expires_at 이전에 결제가 들어오지 않음.

Checkout Session

호스팅 결제 페이지 세션. cs_....

QR Session

매장·POS QR 코드 기반 결제. qrs_....

Refund

성공한 Payment 의 전액 환불. re_.... v1 은 전액 환불만 지원합니다.

Webhook Event

서버 측 이벤트의 전송 기록. evt_.... 웹훅 → 이벤트 타입 참조.

Webhook Endpoint

가맹점이 등록한 이벤트 수신 URL. we_....

에러 코드

각 에러 응답 은 code 필드를 가집니다. 아래 목록은 error.type 별 코드입니다.

authentication_error (401)

코드	의미
api_key_missing	Authorization 헤더가 없음
api_key_invalid	API 키가 잘못된 형식이거나 폐기됨
api_key_expired	회전된 키이며 더 이상 유효하지 않음

permission_error (403)

코드	의미
publishable_key_not_allowed	시크릿 키가 필요한 엔드포인트(예: 환불, 리스트)에 pk_* 키가 사용됨
livemode_mismatch	테스트 모드 키로 라이브 모드 리소스 접근, 또는 그 반대

invalid_request_error (400)

코드	의미
parameter_missing	필수 파라미터 누락
parameter_invalid	파라미터 타입 또는 형식이 잘못됨
amount_too_small	amount 가 선택된 통화의 최소값보다 작음
network_unsupported	network 가 POLYGON, ETHEREUM, SOLANA 중 하나가 아님
currency_unsupported	currency 가 USDT, USDC, ETH, SOL 중 하나가 아님
currency_network_mismatch	토큰이 선택된 네트워크에 존재하지 않음 (예: POLYGON 의 SOL)
settlement_invalid	settlement.mode 가 잘못되었거나 splits 비율 합계가 100이 아님

not_found_error (404)

코드	의미
resource_not_found	id 가 가리키는 객체가 존재하지 않음 (Payment, Checkout Session, QR Session, Refund, Webhook Endpoint)

idempotency_error (409)

코드	의미
idempotency_key_in_use	Idempotency-Key 가 이전에 다른 요청 본문으로 사용됨
payment_not_cancelable	Payment 가 종결 상태(succeeded, failed, expired, canceled)이며 취소 불가
payment_already_refunded	Payment 가 이미 환불됨

rate_limit_error (429)

코드	의미
rate_limit_exceeded	이 API 키로 초당 100 요청 초과 — 속도 제한 참조

payment_error (402)

코드	의미
insufficient_balance	환불할 토큰의 계정 잔액이 부족해 진행 불가
network_rejected	온체인 트랜잭션 거절됨 (gas, nonce 등)

network_error (502 / 504)

코드	의미
rpc_unavailable	블록체인 RPC 연결 불가. Idempotency-Key 와 함께 재시도하세요.
rpc_timeout	블록체인 RPC 가 데드라인 내 응답하지 않음. 재시도하세요.

api_error (5xx)

코드	의미
internal_error	ParaSta 서버 내부 오류. request_id 와 함께 신고하세요.