가맹점 API 개요

개요

HissPay는 결제 수납(고객으로부터 수납)과 출금(수취인 계좌로 지급) API를 HTTPS POST + JSON으로 제공합니다. 운영 게이트웨이: https://transaction.hisspay.com, 샌드박스 게이트웨이: https://sandbox-api.hisspay.com.

상품 카탈로그의 통화: AUD, EUR, GBP, INR, JPY, THB, USD, USDT. 카탈로그에 있다고 해서 개통된 것은 아닙니다. 귀사 계정의 상품 코드, 금액 범위, 수수료는 개통 안내에 따릅니다.

연동 준비

연동 전 확인 사항: 가맹점 심사가 완료되어 활성 상태일 것, 가맹점 관리자(mch.hisspay.com → 앱 키)에서 API 앱을 만들고 appId와 appSecret을 받았을 것, 수납·출금 상품을 계약했을 것, 출금을 위해 서버의 공인 발신 IP를 화이트리스트에 등록했을 것, 공개 HTTPS 알림 URL이 있을 것. 먼저 샌드박스에서 전체 흐름을 테스트하세요.

서명 규칙

모든 요청에는 appId, timestamp(밀리초 Unix 시간, 플랫폼 시간과 30초 이내), nonce(10자 이상, 재사용 불가), sign 헤더가 포함됩니다. sign은 요청 본문 필드와 appId·timestamp·nonce를 이름순으로 key=value로 나열해 &로 연결하고 끝에 appSecret을 바로 붙인 문자열의 SHA-256(소문자 16진수)입니다. HMAC이 아닙니다. null 값을 보내지 말고, appSecret을 브라우저나 앱에 두지 마세요.

결제 수납 요청

POST /transaction/payin/v1/apply는 수납 주문을 만들고 결제자용 payUrl을 반환합니다. 결제 확인은 서명이 검증된 알림이나 조회로만 하고, 브라우저 복귀 페이지로 판단하지 마세요.

출금 요청

POST /transaction/payout/v1/apply는 비동기로 처리됩니다. code=0은 접수되었다는 뜻이며 지급 완료가 아닙니다. 시간 초과나 500은 결과가 확인되지 않았다는 뜻이므로, 먼저 원 주문을 조회하고 전체 문서의 처리 규칙에 따라 판단한 뒤 다시 요청하세요.

USDT 입금

USDT 수납은 currency=USDT와 플랫폼이 부여한 네트워크별 상품 코드를 사용하며, 금액은 소수점 4자리까지입니다. 결과는 알림이나 조회로 확인합니다.

태국(THB)

태국(THB): PromptPay QR 수납과 태국 은행 이체 출금. 수납 은행 코드: SCB, KBANK, KTB, BAY, GSB, TTB, 출금 은행 코드: SCB, KBANK, KTB, BAY, GSB, TTB, BBL(귀사가 이용 가능한 은행은 개통 안내에 기재). 건당 기본 범위: 500.00–49999.00 THB.

주문 조회

POST /transaction/payin/v1/query와 POST /transaction/payout/v1/query는 merchantOrderNo 또는 orderNo로 조회합니다. appId당 초당 5회까지이며, 3–5초 간격으로 백오프하며 조회하세요.

잔액 조회

POST /transaction/payout/v1/balance는 통화별 balance(장부), balanceActive(사용 가능), balanceFreeze(동결)를 반환합니다.

비동기 알림

플랫폼은 동일한 네 개의 서명 헤더와 함께 notifyUrl로 JSON을 POST합니다. 서명을 검증하고 주문 단위로 멱등 처리한 뒤 정확히 SUCCESS 또는 OK로 응답하세요. 확인되지 않은 알림은 제한된 횟수만큼 재전송됩니다.

주문 상태

payStatus를 paymentStatus, isFinal과 함께 사용하세요. 수납 조회의 payStatus=0은 결제 실패를 뜻하지 않습니다.

오류 코드

code=0은 API 호출 성공을 뜻하며, 결제 결과는 별도의 주문 상태입니다. 모든 오류 코드와 권장 처리 방법은 전체 문서에 있습니다.

전체 예제

샌드박스 가맹점을 만들고 샌드박스 가이드의 quickstart 패키지와 5분 자가 점검을 실행한 다음, 운영 전환 체크리스트를 따르세요.