주문 생성
POST /v1/orders는 결제 주문을 만들고 호스팅 결제의 checkout_url을 반환합니다.
핵심 사항
- amount는 최소 통화 단위의 양의 정수입니다. currency는 USD, HKD, CNY이며 운영 가능 통화는 계정 설정에 따릅니다.
- out_trade_no는 선택적 1~128자 가맹점 주문 번호이며 멱등성에도 사용합니다. subject는 최대 255자입니다.
- notify_url은 공개 HTTPS 주소여야 합니다. 운영에서 생략하려면 활성화된 payment.succeeded 엔드포인트가 필요합니다. 동일 요청 재시도는 200, 내용 변경은 409입니다.
- return_url은 브라우저용입니다. checkout_url에 &locale=en 또는 &locale=zh를 추가해 결제 언어를 지정할 수 있습니다. bearer token을 로그에 남기지 마세요.
예시
bash
curl -X POST "https://api.kukopay.com/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KUKOPAY_API_KEY" \
-d '{
"out_trade_no": "ORD_20260921_0001",
"amount": 2990,
"currency": "USD",
"subject": "Premium plan",
"notify_url": "https://shop.example.com/webhooks/kukopay",
"return_url": "https://shop.example.com/orders/complete"
}'요청 필드
| 필드 | 필수 | 설명 |
|---|---|---|
out_trade_no | 아니요 | 가맹점 주문 번호, 1~128자. 생략하면 자동 생성하며 길이 초과 값은 잘라내지 않고 거부합니다. |
amount | 예 | 최소 통화 단위의 양의 정수. 2990은 $29.90입니다. 문자열, 소수 및 음수는 거부됩니다. |
currency | 아니요 | USD, HKD 또는 CNY이며 기본값은 USD입니다. 샌드박스에서는 세 통화 모두 가능하고 운영에서는 승인된 통화만 가능하며 아니면 400 invalid_request를 반환합니다. |
subject | 아니요 | 상품명, 최대 255자. 길이를 초과하면 거부됩니다. |
notify_url | 조건부 | 주문별 비동기 알림을 받는 공개 HTTPS URL. 샌드박스에서도 localhost 및 사설 주소는 400을 반환하므로 로컬 테스트에는 공개 터널을 사용하세요. |
return_url | 아니요 | 결제 성공 후 구매자 브라우저가 돌아갈 주소. 사용자 경험을 위한 이동이며 결제 확인은 아닙니다. |
운영 주문에서 notify_url을 생략하려면 payment.succeeded를 구독하는 활성 운영 Webhook 엔드포인트가 하나 이상 필요합니다. 주문별 URL이 지정되면 엔드포인트 배포보다 우선합니다.
처음 생성하면 HTTP 201, 같은 가맹점 주문 번호와 동일한 내용으로 재시도하면 HTTP 200, 내용이 다르면 HTTP 409입니다.
결제 화면 언어
결제 화면은 중국어와 영어를 지원합니다. 기본적으로 구매자의 브라우저 언어를 따르고 그 외 언어는 영어를 사용합니다. checkout_url에 &locale=en 또는 &locale=zh를 추가해 고정할 수 있습니다.
사이트로 돌아가기
결제 후 영수증을 표시하고 약 5초 뒤 return_url로 이동합니다. 구매자는 즉시 돌아가거나 화면에 머물 수 있습니다. 이미 결제된 링크를 다시 열면 자동 이동하지 않습니다.
| 자리표시자 | 대체 값 |
|---|---|
{TRADE_NO} | KukoPay 거래 번호 |
{OUT_TRADE_NO} | 가맹점 주문 번호 |
https://shop.example.com/orders/{OUT_TRADE_NO}/complete브라우저 복귀는 결제 증거가 아닙니다. 구매자가 페이지를 닫을 수 있으므로 검증된 Webhook 또는 주문 조회 후 상품을 제공하세요.
브랜드 표시
포털의 계정 → 브랜드와 결제 화면에서 가맹점명, 로고, 브랜드 색상을 설정하세요. 샌드박스와 운영에 모두 적용되며 설정하지 않으면 등록한 회사명이 표시됩니다.