통합 결제 API
HTTP + JSON으로 주문 생성, 상태 조회, 환불을 처리합니다.
해외 결제를더 명확하고 안정적으로.
주문 생성부터 자금 정산까지, 결제·환불·알림·출금을 하나의 서버 API로 관리하세요. 팀은 비즈니스에 집중할 수 있습니다.
주문이 들어오고,정산이 완료됩니다.
Fig. 1예시용 수치입니다
- 통합 API
- HTTP + JSON
- 기존 서버에 쉽게 연동
- 테스트와 운영 분리
- 2개 환경
- 키 접두사로 구분
- 서명된 알림
- HMAC-SHA256
- 신뢰할 수 있는 비동기 이벤트
- 미결 거래
- 자동 대사
- 최종 상태 재확인
- 무료 테스트 환경
- 호스팅 결제
- 검증 가능한 Webhook
01플랫폼 기능
결제 흐름에 필요한 모든 것
하나의 API에서 상태를 조회하고 자금 이동을 추적할 수 있습니다.
호스팅 결제
서명된 링크로 이동하므로 결제 정보를 직접 처리할 필요가 없습니다.
환경 분리
테스트와 운영에 별도 키를 사용해 실거래 오류 위험을 줄입니다.
안정적인 Webhook
서명 검증, 실패 시 재전송, 전송 기록, 수동 재전송을 지원합니다.
자동 대사
알림 누락 시 미결 결제와 환불 상태를 다시 확인합니다.
지갑과 원장
입금, 환불, 출금에 따른 잔액 변화를 추적합니다.
02결제 수단과 요금
받을 수 있는 결제와 요금
플랫폼 표준 조건입니다. 심사를 통과한 가맹점은 계약된 요율을 가맹점 포털에서 확인할 수 있습니다.
- 결제 수단
- 카드
- Apple Pay
- Google Pay
- 알리페이
- 위챗페이
- PayPal
- 테스트 환경에서는 모든 수단을 사용할 수 있습니다. 운영 환경의 결제 수단은 심사 시 가맹점별로 활성화되며, 포털에서 추가를 신청할 수 있습니다.
- 통화
- USD · HKD · CNY
- 통화마다 별도의 지갑이며 같은 통화로 출금합니다. 자동 환전은 없습니다.
- 표준 요금
- 3.5% + 고정 수수료
- 결제 성공 건당 부과되며 고정 수수료는 $0.30 · HK$2.35 · ¥2.00입니다. 수수료는 주문 금액을 넘지 않습니다.
03개발자 중심
요청 한 번으로 첫 결제 시작
서버에서 주문을 만든 뒤 반환된 결제 URL로 구매자를 이동시키세요. 주문 참조 번호는 멱등 키로도 사용됩니다.
요청
curl -X POST https://api.kukopay.com/v1/orders \
-H "X-Api-Key: kuko_test_•••" \
-H "Content-Type: application/json" \
-d '{
"out_trade_no": "ORD_2026_001",
"amount": 2990,
"currency": "USD",
"subject": "Premium plan"
}'응답 201
{
"code": 201,
"data": {
"trade_no": "TRD_SB_9F3A2C7E…",
"status": "pending",
"checkout_url": "https://checkout.kukopay.com/…"
}
}주문 금액
$29.90 USD
ORD_2026_001
테스트 환경결제 완료
결제 라이프사이클
- 주문 생성
POST /v1/orders - 결제 화면 진입
checkout_url - 결제 성공
payment.succeeded - Webhook 전송 완료
HTTP 200 - 원장에 기록
+ $29.90
Fig. 2예시 화면이며 실제 거래가 아닙니다
빠른 시작 보기04연동 방식
시스템에 맞는 가장 짧은 연동 경로
어떤 방식이든 같은 주문, 같은 호스팅 결제 화면, 같은 정산과 알림을 사용합니다. 차이는 코드를 누가 작성하느냐뿐입니다.
05연동 과정
4단계로 결제 완료
브라우저 복귀는 사용자 경험을 위한 것이며, 상품 제공은 서명 검증된 서버 알림을 기준으로 합니다.
- 01
테스트 키 발급
가맹점 등록 후 테스트 키를 신청합니다.
- 02
주문 생성
금액, 주문 번호, 알림 URL을 보내 결제 링크를 받습니다.
- 03
구매자 결제
구매자를 KukoPay 호스팅 결제 화면으로 이동시킵니다.
- 04
검증 후 제공
payment.succeeded를 검증하고 이벤트 ID로 중복 처리합니다.
06보안 설계
안전 장치를 흐름에 내장
환경 분리, 서명 검증, 원장 규칙으로 운영 실수를 줄입니다.
키 보호
키는 암호화해 보관하며 가맹점이 재발급할 수 있습니다.
접근 제어
가맹점별 API 제한과 선택적 IP 허용 목록.
환경 분리
테스트와 운영은 독립된 키와 원장을 사용합니다.
자금 일관성
잔액 변경과 멱등 상태 전환을 기록합니다.
07자주 묻는 질문
연동 전에 알아둘 내용
KukoPay는 무엇인가요?
KukoPay는 해외 판매 비즈니스를 위한 결제 게이트웨이입니다. 서버에서 API를 한 번 호출해 주문을 만들고 구매자를 KukoPay 호스팅 결제 화면으로 보내면, 결제 채널에서 결과를 확인한 뒤 해당 통화의 지갑에 입금하고 서명된 Webhook으로 알려 드립니다. 환불, 차지백, 대사, 출금도 같은 API와 가맹점 포털에서 처리합니다.
어떤 결제 수단과 통화를 지원하나요?
카드, Apple Pay, Google Pay, 알리페이, 위챗페이, PayPal을 지원하며 통화는 USD, HKD, CNY입니다. 테스트 환경에서는 모두 사용할 수 있고, 운영 환경의 결제 수단과 통화는 심사 시 가맹점별로 활성화되며 포털에서 추가를 신청할 수 있습니다. 통화마다 별도의 지갑이며 자동 환전은 없습니다.
요금은 얼마인가요?
표준 요금은 결제 성공 건당 3.5% + 고정 수수료(USD $0.30, HKD HK$2.35, CNY ¥2.00)이며, 수수료는 주문 금액을 넘지 않습니다. 계약 시 결제 수단 그룹별로 요율을 정할 수 있고, 적용된 요율은 주문마다 기록됩니다. 테스트 환경은 무료입니다.
사업자가 아니어도 가입할 수 있나요?
네. 중국 본토 법인, 개인사업자, 중국 본토 외 지역에 등록된 법인뿐 아니라 만 18세 이상 개인도 본인 신분증으로 신청할 수 있습니다. 개인 가맹점은 결제 한도가 있고, 본인 명의 개인 계좌로만 출금할 수 있으며, 디지털 상품과 온라인 게임은 취급할 수 없습니다.
코드 없이 결제를 받을 수 있나요?
네. 결제 링크는 코드가 필요 없습니다. 일반적인 결제 프로토콜을 지원하는 시스템은 게이트웨이 URL과 키만 입력하면 되고, 지원 플랫폼에는 기성 플러그인이 있습니다. 환불, 대사, 차지백 증빙 제출은 가맹점 포털에서 할 수 있습니다.
API 문서는 어디에 있나요?
공개 문서는 kukopay.com/docs에 있으며, 키·주문·Webhook 전송 기록은 가맹점 포털에서 확인할 수 있습니다.
중복 주문과 중복 제공은 어떻게 막나요?
주문 생성 시 고유한 out_trade_no를 사용하고 Webhook은 이벤트 ID로 중복 제거하세요. 시간 초과 후 같은 주문 번호로 재시도할 수 있습니다.
브라우저 복귀로 결제 완료를 판단할 수 있나요?
아니요. payment.succeeded Webhook의 서명을 검증한 뒤 제공하고, 필요하면 주문 조회로 추가 확인하세요.