API 레퍼런스

결제 생성

POST /api/requestPayment — 결제 건을 만들고 고객 결제 페이지 링크(REDIRECT_URL)를 발급합니다.

HTTP

POST {BASE_URL}/api/requestPayment
Content-Type: application/json

요청

필드	필수	형식	설명
`TRANS_SEQNO`	✅	문자열 ≤64	거래 고유번호. 귀사 채번, 같은 플랫폼·가맹점에서 유일
`PLATFORM_CODE`	✅	문자열	플랫폼 코드
`STORE_CODE`	✅	문자열	정산 가맹점 코드
`TRANS_AT`	✅	`^\d{14}$`	요청 시각 KST `yyyyMMddHHmmss`
`APPROVAL_AMOUNT`	✅	`^\d{1,12}$`	결제금액(원). 문자열
`MOBILE_NO`	✅	`^\d{10,11}$`	고객 휴대폰. 숫자만
`PAY_USER_NAME`	✅	문자열	결제자명
`REQUEST_REASON`	✅	문자열	결제 사유(주문명). 결제 페이지에 표시
`INFO_MESSAGE`	–	문자열	결제 페이지 안내 문구
`CONFIRM_URL`	✅	`https://…` ≤100자	결제 완료 콜백 URL. HTTPS만. 100자를 넘으면 `5001`로 거절됩니다
`RETURN_DISPLAY_YN`	–	`Y`/`N`	`Y`면 결제 완료 후 `RETURN_URL`로 고객 브라우저를 이동
`RETURN_URL`	–	문자열 ≤100	이동할 귀사 페이지. 쿼리로 `RESULT_CODE`·`RESULT_MSG`·`TRANS_SEQNO`·`APPROVAL_AMOUNT`·`TEMP_VALUE`가 붙습니다(귀사 주소의 기존 쿼리는 유지). 표시용이며 승인 확정은 조회 API로
`TEMP_VALUE`	–	문자열	귀사 임의값. 콜백·리턴에 그대로 돌아옵니다(주문 ID 등)
`USER_ID`	–	문자열	귀사 회원 식별자(참고용)
`orderType`	–	`BILL`(기본)/`SHOP`	주문 유형. 결제 페이지 UI와 콜백 `ORDER_TYPE` 분기
`ITEMS`	–	배열	품목. `SHOP`이면 결제 페이지에 표로 표시
`API_SIGN`	✅	64자 hex	서명

ITEMS[]

필드	필수	설명
`name`	✅	항목명 ≤20자
`unitPrice`	✅	단가(원, 정수). 할인 전
`qty`	–	수량. 기본 1
`discountAmount`	–	할인 값. `discountUnit`이 `AMOUNT`면 금액, `RATE`면 %
`discountUnit`	–	`AMOUNT`(기본) / `RATE`
`taxType`	–	`TAX_ON` / `TAX_FREE`. 없으면 가맹점 기본값
`vatRateBps`	–	부가세율 bps(1000 = 10%). 없으면 가맹점 기본값
`publisher` · `imageUrl`	–	`SHOP` 전용 표시 정보(≤60자 / ≤500자)

ITEMS가 있으면 APPROVAL_AMOUNT는 품목 합계와 같아야 하며 부가세·면세 금액은 품목 기준으로 계산됩니다.

요청 예시

JSON

{
  "TRANS_SEQNO": "svc20260921120000123",
  "PLATFORM_CODE": "PC0000000000000001",
  "STORE_CODE": "SD0000000000000001",
  "TRANS_AT": "20260921120000",
  "APPROVAL_AMOUNT": "128000",
  "MOBILE_NO": "01012345678",
  "PAY_USER_NAME": "홍길동",
  "REQUEST_REASON": "9월 이용료",
  "INFO_MESSAGE": "결제 후 즉시 이용권이 열립니다.",
  "CONFIRM_URL": "https://api.example.com/caripay/callback/svc20260921120000123",
  "RETURN_DISPLAY_YN": "Y",
  "RETURN_URL": "https://example.com/orders/complete",
  "TEMP_VALUE": "order-8812",
  "orderType": "BILL",
  "API_SIGN": "3f1c…(64자)"
}

응답

JSON

{
  "result_code": 0,
  "result_msg": "성공",
  "result_data": {
    "RESULT_CODE": "0000",
    "RESULT_MSG": "",
    "REDIRECT_URL": "https://chewingpay.com/payments?txId=12_34_svc20260921120000123&accessToken=…"
  }
}

필드	설명
`RESULT_CODE`	`"0000"`만 성공
`REDIRECT_URL`	고객 결제 페이지. 그대로 사용(리다이렉트·문자·알림톡·QR). 조립·수정하지 마세요

오류

`RESULT_CODE`	원인
`3001`	서명 불일치 — 필드 순서·`TRANS_AT`·`API_KEY` 확인
`4001`	같은 `TRANS_SEQNO`로 이미 생성됨
`4005`	`PLATFORM_CODE`·`STORE_CODE` 오류 또는 조합 불일치
검증 오류	필수값 누락·형식 오류. `result_msg`에 `필드명: 사유`

거래 상태

생성 직후 상태는 STORE_REQUEST(결제 대기)입니다. 결제 링크에는 별도 만료가 없습니다. 기한이 지난 청구는 삭제로 닫으세요.

문서에 없는 내용이나 오류는 bellight@goatheaven.com 또는 지원 문의로 알려주세요.