카카오페이 결제> 온라인 결제> 단건 결제

카카오페이 단건 결제 사용 방법 

단건 결제 = 한 번의 결제로 지불이 완료되는 구매건

 

cf. 정기 결제 = 정기적으로 여러 차례 결제가 발생하는 결제 

 

일반적인 상품 판매나 비용 지불 시 단건 결제를 사용 

단건 결제 시 가맹점 코드(CID)가 필요합니다.
- 카카오페이와 제휴를 통해 애플리케이션> ClientID를 전달 주시면 가맹점코드(CID)를 발급해 드립니다.
- 테스트 결제는, 가맹점 코드로 "TC0ONETIME"와 "Secret key(dev)"를 통해 결제 호출이 가능합니다.

https://developers.kakaopay.com/docs/payment/online/single-payment#payment-ready

카카오페이 | 개발자센터

 

 

결제준비(ready)

카카오페이 결제를 시작하기 위해 결제정보를 카카오페이 서버에 전달하고 결제 고유번호(TID)와 URL을 응답받는 단계입니다.

1. Secret key를 헤더에 담아 파라미터 값들과 함께 POST로 요청합니다.
2. 요청이 성공하면 응답 바디에 JSON 객체로 다음 단계 진행을 위한 값들을 받습니다.
3. 서버(Server)는 tid를 저장하고, 클라이언트는 사용자 환경에 맞는 URL로 리다이렉트(redirect)합니다.

Request

Request Syntax

POST /online/v1/payment/ready HTTP/1.1
Host: open-api.kakaopay.com
Authorization: SECRET_KEY ${SECRET_KEY}
Content-Type: application/json

 

Request Body Payload

 

• 카드사 코드* : SHINHAN, KB, HYUNDAI, LOTTE, SAMSUNG, NH, BC, HANA, CITI, KAKAOBANK, KAKAOPAY, WOORIONLY
• KAKAOBANK, KAKAOPAY, CITY는 KB/BC에 미포함, 별도 지정 필요
• SUHYUP, SHINHYUP, JEONBUK, JEJU, SC 등 기타 상세 분류가 필요한 경우 협의필요
• 컵 보증금(green_deposit) 사용 시 부분 취소 불가

Response

Response Body Payload

Request

curl --location 'https://open-api.kakaopay.com/online/v1/payment/ready' \
--header 'Authorization: SECRET_KEY ${SECRET_KEY}' \
--header 'Content-Type: application/json' \
--data '{
		"cid": "TC0ONETIME",
		"partner_order_id": "partner_order_id",
		"partner_user_id": "partner_user_id",
		"item_name": "초코파이",
		"quantity": "1",
		"total_amount": "2200",
		"vat_amount": "200",
		"tax_free_amount": "0",
		"approval_url": "https://developers.kakao.com/success",
		"fail_url": "https://developers.kakao.com/fail",
		"cancel_url": "https://developers.kakao.com/cancel"
	}'

 

curl 명령어

• --location: 리다이렉트를 따라가도록 설정합니다.
• 'https://open-api.kakaopay.com/online/v1/payment/ready': 카카오페이 결제 준비 API 엔드포인트 UR

헤더

• 'Authorization: SECRET_KEY ${SECRET_KEY}': 카카오페이 API 인증을 위한 시크릿 키를 전송합니다. ${SECRET_KEY}는 실제 시크릿 키로 대체해야 합니다.
• 'Content-Type: application/json': 요청 본문이 JSON 형식임을 나타냅니다.

 

데이터 (요청 본문)

 

• 'cid': 'TC0ONETIME'.   : 가맹점 코드입니다. 테스트 용도로 'TC0ONETIME'을 사용합니다.
• 'partner_order_id': 'partner_order_id': 가맹점에서 생성한 주문 번호입니다.
• 'partner_user_id': 'partner_user_id': 가맹점에서 관리하는 사용자 ID입니다.
• 'item_name': '초코파이': 결제 상품명입니다.
• 'quantity': '1': 상품 수량입니다.
• 'total_amount': '2200': 총 결제 금액(원)입니다.
• 'vat_amount': '200': 부가가치세 금액(원)입니다.
• 'tax_free_amount': '0' : 면세 금액(원)입니다.
• 'approval_url': 'https://developers.kakao.com/success': 결제 성공 시 리디렉션될 URL입니다.
• 'fail_url': 'https://developers.kakao.com/fail': 결제 실패 시 리디렉션될 URL입니다.
• 'cancel_url': 'https://developers.kakao.com/cancel': 결제 취소 시 리디렉션될 URL입니다.

 

이 curl 명령어를 실행하면 카카오페이 결제 준비 API에 요청을 보내고, 응답으로 결제 정보를 받게 됩니다. 이후 받은 결제 정보를 사용하여 실제 결제 프로세스를 진행할 수 있습니다.

---

Response: 정상적으로 요청에 성공한 경우

 

카카오페이 결제 준비 API 요청에 대한 성공적인 응답

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "tid": "T1234567890123456789",
  "next_redirect_app_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/aInfo",
  "next_redirect_mobile_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/mInfo",
  "next_redirect_pc_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/info",
  "android_app_scheme": "kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
  "ios_app_scheme": "kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
  "created_at": "2023-07-15T21:18:22"
}

 

 

 

tid : 카카오페이에서 생성한 거래 ID입니다.

이 ID를 사용하여 결제 상태를 조회할 수 있습니다.

 

next_redirect_app_url : 앱에서 결제를 진행할 때 사용하는 URL입니다.

 

next_redirect_mobile_url : 모바일 웹에서 결제를 진행할 때 사용하는 URL입니다.

 

next_redirect_pc_url: PC 웹에서 결제를 진행할 때 사용하는 URL입니다.

 

android_app_scheme: 안드로이드 앱에서 결제를 진행할 때 사용하는 스킴(scheme) URL입니다.

ios_app_scheme : iOS 앱에서 결제를 진행할 때 사용하는 스킴(scheme) URL입니다.

created_at : 결제 준비 요청이 생성된 시간입니다.

 

이 응답에서 가장 중요한 값은 tid와

결제 진행을 위한 리디렉션 URL 또는 스킴 URL입니다.

 

 

이 값들을 사용하여 실제 결제 프로세스를 진행할 수 있습니다.

 

예를 들어,

웹에서 결제를 진행하려면

 next_redirect_pc_url을 사용하여

사용자를 해당 URL로 리디렉션합니다.

 

앱에서 결제를 진행하려면 

android_app_scheme 또는 ios_app_scheme을 사용하여

해당 스킴 URL을 열어 결제 프로세스를 시작합니다.

 

 

 

Request

 

 

 

 

응답 필드

error_code

• 발생한 오류의 코드입니다. -780은 결제 승인 실패를 의미합니다.

error_message

• 오류에 대한 간단한 메시지입니다. "approval failure!"는 결제 승인이 실패했음을 나타냅니다.

extras

• 오류에 대한 추가 정보를 제공하는 객체입니다.

extras.method_result_code

• 오류의 상세 코드입니다. "USER_LOCKED"는 사용자가 잠겨있음을 의미합니다.

extras.method_result_message

• 오류에 대한 상세 메시지입니다. "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."는 현재 사용자가 다른 거래를 진행 중이므로 잠시 후에 다시 시도하라는 의미입니다.

이 응답은 사용자가 이미 다른 결제 프로세스를 진행 중이어서 새로운 결제 요청이 실패했음을 나타냅니다. 이런 경우 일정 시간 후에 다시 결제 요청을 시도해야 합니다.일반적으로 이런 오류 응답을 받으면 적절한 오류 메시지를 사용자에게 표시하고, 필요한 경우 재시도 로직을 구현해야 합니다. 또한 오류 코드와 메시지를 기록하여 문제 해결에 활용할 수 있습니다.