결제 생성
결제 건을 생성합니다.
결제 생성 완료 후, 구매자의 결제 인증을 얻어 완료처리하는 방법은 토스페이 시작하기 > 3. 구매자 인증 받기를 참고하세요.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
요청 파라미터
가맹점 API Key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
테스트가 완료되면 운영 오픈 전 반드시 '실거래용 API Key'로 변경 후 체크해주세요!
가맹점의 상품 주문번호
주문번호는 50자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다. 주문번호는 매회 유니크한 값으로 활용해 주셔야하며, 구매자 인증완료(PAY_APPROVED) 전의 주문번호는 재사용이 가능합니다. 단, 사용자 인증완료 후에는 재 사용이 불가하며 최초 생성 후 2년이 지난 주문 번호는 재사용이 불가합니다. 테스트와 라이브 환경 사이에서 중복되지 않도록 가맹점의 관리가 필요하며 중복되는 경우 오류가 발생합니다.
상품 설명
상품 설명은 공백으로만 설정할 수 없고, 백슬래시("\")와 따옴표(",")를 포함할 수 없으며 총 255자 이내여야 합니다. 이
값에 한글이 포함되었다면 인코딩에 유의해주세요.
토스 인코딩 방식 참고사항
구매자 인증완료 후 연결할 가맹점 웹페이지 URL
사용자 인증이 완료되는 시점에 인증 데이터와 함께 결제완료 페이지로 이동시킵니다. 이 때, 전달되는 인증 데이터는 아래
링크에서 확인해 보실 수 있습니다. (단, 전달되는 인증 데이터는 결제수단 별로 차이가 있을 수 있습니다.)
구매자 인증완료 참고사항
토스페이창에 진입한 사용자가 결제를 중단할 때 사용자를 이동시킬 가맹점 취소 페이지
이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 강제로 종료하지
않고 가맹점의 취소 페이지로 이동할 수 있습니다. 구매자 편의를 위하여 반드시 활용해주세요!
구매자가 결제창을 종료한 경우 즉시 가맹점이 설정한 retCancelUrl로 redirect 되며, 토스 서버에서는 강제로 결제상태를 취소처리 합니다. 상점에서 취소거래 구분이 필요하다면 주문번호를 활용하는 등 자체적으로 거래구분 처리 해주세요.
결제 완료 후 연결할 가맹점 측 앱 스킴 값
가맹점의 결제 구현환경이 App to App인 경우 retAppScheme 값을 선언해 주시면 토스페이 완료 후 가맹점 앱으로 redirect 할
수 있습니다.
단, 사용자의 진입점이 앱이 아닌 일반 웹브라우저인 경우 retAppScheme가 포함되어 있다면 이전 브라우저가 뜨지 않아 결제가 완료될 수 없으니 반드시 유념해 주세요.
iOS 앱 결제의 경우 필수 구현을 권장합니다. iOS 특성 상, 자동 앱 전환이 되지 않기 때문에 가맹점 앱 스킴 값을 이 곳에
선언해 주셔야 인증 후 가맹점 앱으로 랜딩됩니다.
safari 등 모바일 웹 브라우저에서 자동 전환되지 않는 이슈는 OS 이슈인 점 참고 부탁드립니다. (Ex. testshop://)
모바일 웹뷰 결제 가이드 참고사항
자동 승인 여부 설정
가맹점의 판매 상품에 따라 '자동 승인 설정' 을 활용할 수 있습니다. true 를 선언한 경우 resultCallback 을 필수 값으로
체크합니다.
자동 승인 설정 참고사항
결제 결과 콜백 URL
자동 승인 설정(autoExecute=true) 시 ResultCallback 구현이 필수이며, 결제 상태 확인을 위해 모든 가맹점에 사용을 권장합니다.
결제 결과 콜백 버전
콜백 버전에 따라 전달되는 응답 값이 다를 수 있으니 최신 버전(V2) 이용을 권장합니다. 이 값이 포함되지 않을 경우 승인 콜백은 V2 버전의 데이터가 전달됩니다.
- V1: 콜백 데이터를 파라미터 형식으로 전달 (
application/x-www-form-urlencoded). - V2: 콜백 데이터를 JSON 형식으로 전달.
총 결제 금액
금액과 관련된 모든 파라미터는 숫자 형태로 보내주셔야 에러가 발생하지 않습니다.
결제 금액 중 비과세 금액
판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수 값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.
결제 금액 중 과세 금액
별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.
결제 금액 중 부가세
값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
결제 금액 중 봉사료
봉사료 금액입니다.
결제 만료 기한
결제 만료 기한 (기본값 15분, 최대 60분 설정 가능)
형식: YYYY-MM-DD HH:MM:SS (예: 2020-03-03 12:30:20)
결제수단 구분 변수
가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다. 아래 옵션 값에 따라 설정 가능합니다.
| 값 | 설명 |
|---|---|
| TOSS_MONEY | 결제수단 중 토스머니만 노출 |
| CARD | 결제수단 중 카드만 노출 |
| null 또는 그 외의 값 | 상점에 설정된 기본 결제수단으로 노출 |
현금영수증 발급 가능 여부
현금영수증 기능을 활용하시는 경우 true, 미사용의 경우 false로 선언해 주시기 바랍니다.
반드시 true 또는 false 값을 전달해 주셔야 하고, null과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false로
처리됩니다.
현금영수증 발급 타입
문화비 관련 상품의 경우, 발급 타입을 설정하여 보내주세요.
| 값 | 설명 |
|---|---|
| CULTURE | 문화비 |
| GENERAL | 일반 (기본값) |
| PUBLIC_TP | 교통비 |
카드 옵션
결제창에 특정 카드만 노출하고 싶다면, options 변수에 토스 카드 코드를 추가해 주세요. 예를 들어, 삼성카드와 현대카드만 결제가 가능하도록 노출을 제어한다면 아래와 같이 토스 카드 코드를 넘겨주시면 됩니다.
"cardOptions": {"options": [{"cardCompanyCode": 3}, {"cardCompanyCode": 5}]}할부 제한 타입
신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다.
| 값 | 설명 |
|---|---|
| USE | 할부 사용 (기본값) |
| NOT_USE | 할부 미사용 |
Example Request
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo":"1",
"amount":10000,
"amountTaxFree":0,
"productDesc":"테스트결제",
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute":true,
"resultCallback":"https://pay.toss.im/payfront/demo/callback",
"callbackVersion":"V2",
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1",
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel"
}'응답 파라미터
결제를 진행할 수 있는 토스페이 웹페이지 URL
토스가 전달한 값 그대로를 구매자에게 띄워주세요.
토스페이 토큰
매회 유니크한 토큰 값이 생성됩니다. 가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다.
응답이 성공이 아닌 경우 설명 메시지
응답이 성공이 아닌 경우 설명 메시지입니다.
Example Response
{
"code": 0,
"checkoutPage": "https://pay.toss.im/payfront/auth?payToken=example-payToken",
"payToken": "example-payToken"
}