결제 생성하기
결제 생성 요청에 대해 좀 더 자세히 알아봅니다. 아래 예제는 결제 생성 API가 지원하는 모든 파라미터를 사용한 코드입니다.
예제 코드
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo": "1", # 토스몰 고유의 주문번호 (필수)
"amount": 25000, # 결제 금액 (필수)
"amountTaxFree": 0, # 비과세 금액 (필수)
"productDesc": "A티셔츠", # 상품 정보 (필수)
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq", # 상점의 API Key (필수)
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1", # 결제 완료 후 연결할 웹 URL (필수)
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel", # 결제 취소 시 연결할 웹 URL (필수)
"autoExecute": true, # 자동 승인 설정 (필수)
"resultCallback": "https://pay.toss.im/payfront/demo/callback", # 결제 결과 callback 웹 URL (필수-자동승인설정 true의 경우)
"callbackVersion": "V2", # callback 버전 (필수-자동승인설정 true의 경우)
"amountTaxable": 22727, # 결제 금액 중 과세금액
"amountVat": 2273, # 결제 금액 중 부가세
"amountServiceFee": 0, # 결제 금액 중 봉사료
"expiredTime": "2024-06-17 12:47:35", # 결제 만료 예정 시각
"cashReceipt": true # 현금영수증 발급 가능 여부
}'결제 생성 API의 Endpoint
필수 Parameters
결제 생성 요청 시 반드시 아래 9가지 값을 함께 보내주셔야합니다.
- 상점 주문번호 : 추후 상점 주문 정보와 결제 정보를 매칭하기 위해 필요
- 결제 금액 : 손님으로부터 받을 금액
- 비과세 금액 : 손님으로부터 받을 금액중 비과세 금액
- 상품명 : 결제할 상품에 대한 정보
- 상점 API Key : 이곳에 '테스트용 API Key'를 넣으면 테스트 결제가, '실거래용 API Key'를 넣으면 진짜 출금되는 결제가 생성됩니다.
- 구매자 인증 완료 후 연결할 URL : 구매자가 결제를 확인하고 인증 완료하면 이 파라미터를 통해 설정한 URL로 구매자를 보내드립니다. 일반적으로 구매 완료 페이지 또는 구매 완료 페이지로 연결할 수 있는 곳을 지정합니다.
- 구매자가 결제 취소 시 연결할 URL : 구매자가 결제를 취소하면 이 파라미터를 통해 설정한 URL로 구매자를 보내드리고, 토스는 자동으로 해당 거래건을 취소처리 합니다. 상점에서 취소거래 구분이 필요하다면 자체적으로 거래구분 처리 해주세요.
- 자동 승인 설정 : 구매자가 인증을 완료하면 토스가 자동으로 승인을 진행합니다. 가맹점은 결과 값만 확인해 주시면 됩니다.
- 결제 결과 callback URL : 토스 서버가 출금을 성공하면 가맹점 서버로 결제 성공 callback을 요청합니다. 이후 가맹점에서는 결제완료 상태변경 등의 로직을 처리할 수 있습니다. (이 값은 자동 승인 설정이 'true'일 경우에만 필수 값입니다.)
모바일 웹뷰 결제 가이드
모바일 웹뷰 결제는 앱투앱(App to App) 이동이 필요합니다. 앱투앱 이동을 위해 필요한 준비사항은 다음과 같습니다.
안드로이드
Intent URI 사용
intent://pay?payToken={payToken}#Intent;scheme=supertoss;package=viva.republica.toss;end`Intent URI 파싱 처리
가맹점 앱에서 Intent URI를 파싱하여 처리해야 합니다. 잘못된 Activity로 라우팅되지 않도록 아래와 같이 구현합니다.
val intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME).apply {
// URI를 브라우저에서 열 수 있도록 설정
addCategory(Intent.CATEGORY_BROWSABLE)
component = null
selector = null
}
try {
startActivity(intent)
} catch (_: ActivityNotFoundException) {
// 토스 앱 미설치 시 스토어로 이동
intent.`package`?.let { packageName ->
val marketIntent = Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$packageName"))
startActivity(marketIntent)
}
}아이폰(iOS)의 경우
Universal Link 사용
https://ul.toss.im?scheme=supertoss%3A%2F%2Fpay%3FpayToken%3D{payToken}주의사항
토스 앱 설치 여부 확인 및 처리
- ‘앱으로 결제하기’ 클릭 시, 앱 설치 유무를 체크합니다
- 설치되어 있는 경우: 앱을 호출
- 설치되어 있지 않은 경우: 앱스토어로 이동
iframe 사용 금지 권장
- 토스는 iframe 방식 호출을 공식적으로 지원하지 않습니다.
- 새 창을 띄워 호출하는 방식을 권장합니다.
결제 만료 기한 (expiredTime)
이 파라미터를 통해 '결제 생성 후, 언제까지 결제 승인을 진행할 수 있는지' 설정할 수 있습니다. '결제 대기' 상태인 결제건의 만료 기한이 도래하면 토스 서버에서 자동으로 결제를 취소합니다.
상점 혹은 판매 물품에 특성에 따라 결제 만료 기간을 길게 혹은 짧게 설정할 수 있습니다.
재고의 변동이 적고, 구매자의 결제가 급하지 않다면 결제 만료 기한을 길게 설정하세요. 구매자는 먼저 주문만 해두고 원하는 시점에 결제할 수 있습니다. 재고의 변동이 크거나 '결제 대기' 상태를 오래 지속하고싶지 않은 경우엔 결제 만료 기한을 짧게 설정하세요.
현금영수증 발급 가능 여부 (cashReceipt)
현금영수증 발급 가능 여부를 설정할 수 있습니다. 카드결제 혹은 문화상품권이나 백화점상품권, 모바일 쿠폰 등 과세 대상에서 제외되는 유가증권 등의 상품은 현금영수증 발행이 불가하며, 토스 머니와 같이 현금성 결제건에 한하여 현금영수증 발행이 가능합니다.
- true : 현금영수증 발급 가능 (값을 설정하지 않으면 기본 true)
- false : 현금영수증 발급 불가
자동 승인 여부 (autoExecute)
토스페이에서는 두 가지 옵션을 제공합니다. 구매자 인증이 완료되면 토스에서 즉시 출금을 시도하고 결제를 완료시키는 방법과 구매 상품의 재고 상황에 따라 '최종 승인'의 주체가 가맹점이 될 수도 있습니다. 결제 상점의 판매 상품에 따라 두 가지 방식을 고려하여 옵션을 활용할 수 있습니다.
결제 생성 시, autoExecute를 'true'로 설정 : 구매자 인증완료 후 출금시도와 함께 결제완료 상태를 전달합니다.
결제 생성 시, autoExecute를 'false'로 설정 : 해당 결제건은 가맹점의 최종 승인 전까진 대기 상태에 머무르게 됩니다. (PAY_APPROVED 상태) 결제 승인 API를 통해 최종 승인 (execute API): PAY_APPROVED 상태의 결제건에 대해 승인을 요청하면 출금을 시도하고 출금 완료 시 결제 완료로 상태를 변경합니다. 이때 토스머니 잔액을 체크하고 잔고가 부족하다면 충전 후 출금됩니다.
아래 그림을 참고하세요.
복합과세 처리 (amount-)
전체 결제 금액 중 '비과세' 처리해야할 금액이 섞여있거나 부가세, 봉사료 비중을 원하는대로 설정하고 싶다면 결제 생성 시 '복합과세' 파라미터를 이용하세요.
- amountTaxable : 결제 금액 중 '과세금액' 비중
- amountTaxFree : 결제 금액 중 '비과세금액' 비중
- amountVat : 결제 금액 중 '부가세' 비중
- amountServiceFee : 결제 금액 중 '봉사료' 비중 토스에서는 총 금액과 비과세 금액만 필수로 체크하고 있습니다. 복합과세 설정이 필요하다면 네 가지 값을 설정해 주셔야 하며, 네 가지 값의 합은 총 결제 금액(amount)과 반드시 동일해야 합니다. 동일하지 않을 경우 에러가 발생합니다. 위 파라미터를 통해 설정한 값은 현금 영수증 발행 시 그대로 반영됩니다.
위 파라미터 값을 설정하지 않는 경우, 자동으로 아래와 같이 처리됩니다.
-
부가세 : 전체 금액(amount)을 11로 나눈 후 소수점 첫째 자리에서 올림
-
과세금액 : 전체 금액에서 부가세를 뺀 나머지 값
-
비과세금액, 봉사료 : 0 단, 현금영수증 발행 불가 결제(cashReceipt = false)인 경우, 아래와 같이 처리됩니다.
-
과세금액 : 전체 금액(amount)과 동일
-
부가세, 비과세금액, 봉사료 : 0