Search

토스페이먼츠(신 모듈) 일반결제 연동상세 안내

Tags
PG 식별자
tosspayments
가능한 결제수단
- 카드 - 계좌이체 - 가상계좌 - 에스크로 (계좌이체, 가상계좌) - 휴대폰 소액결제 - 상품권 결제 (도서문화상품권, 스마트문상, 컬쳐랜드) - 간편결제 (카카오페이, 네이버페이, L페이, 삼성페이, SSG페이, 페이코, 토스페이)
가능한 결제환경
- PC (iframe) - 모바일 (리디렉션)
가능한 기능
- 결제 금액 사전 등록 - 결제 - 승인 취소(환불) - 현금영수증 조회 / 등록 / 삭제 - external 현금영수증 조회 / 등록 / 삭제
지원 브라우저
IE11+ MicroSoftEdge Chrome Safari Firefox 등 (단, IE11의 경우 일부 카드사와 간편결제사 자체적으로 지원하지 않는 경우가 있음)
JS SDK
https://cdn.iamport.kr/v1/iamport.js 기존에 쓰던 v1.1.X v1.2.X로는 토스페이먼츠 - 신모듈 사용 불가능

PG 연동 설정

왼쪽 네비게이션 결제 연동 메뉴 클릭
테스트 연동 설정
테스트 연동 관리 탭 클릭
결제대행사 설정에서 토스페이먼츠 / 토스페이먼츠 선택 후 오른쪽 + 추가 버튼 클릭
테스트 연동 정보 확인 후 오른쪽 하단 저장 버튼 클릭
등록 완료 후, 결제 요청시 pg 파라미터에 tosspayments.tvivarepublica2를 입력
실 연동 설정
실 연동 관리 탭 클릭
결제대행사 설정에서 토스페이먼츠 / 토스페이먼츠 선택 후 오른쪽 + 추가 버튼 클릭
토스페이먼츠로부터 전달 받은 실 연동 정보 입력 후 오른쪽 하단 저장 버튼 클릭
등록 완료 후, 결제 요청시 pg 파라미터에 tosspayments.실연동상점아이디를 입력

토스페이먼츠 API 버전 설정

왼쪽 네비게이션 메뉴 API 키 선택 → API 버전을 2022-07-27로 선택
API 버전을 다르게 설정하면 결제 승인 / 실패시 실제 응답과 다른 응답을 받아볼 수 있으니 반드시 API 버전을 2022-07-27로 맞춰주시기 바랍니다

결제 금액 사전 등록

아임포트는 결제 금액 위/변조를 막기 위해, 특정 주문 번호에 대해 결제 될 금액을 사전 등록할 수 있는 REST API를 제공하고 있으며 스펙은 아래와 같습니다. (자세한 내용은 관련 문서 참고)
요청 URL: https://api.iamport.kr/payments/prepare
요청 메소드: POST
요청 본문
{ merchant_uid: 'order_id_1667634130160', amount: '109000' }
JavaScript
파라미터
필수 입력 여부
의미
예시
merchant_uid
required
주문 번호
order_id_1667634130160
amount
required
결제 금액
109000
위와 같이 등록이 완료되면, 주문번호 order_id_1667634130160에 대해 109000 금액과 일치하지 않은 금액으로의 결제 요청은 차단(인증결제의 경우 결제창 호출이 되지 않음)됩니다.

JS SDK

아래와 같이 기존에 쓰시던 버전은 토스페이먼츠 - 신모듈 결제가 불가능합니다.
https://cdn.iamport.kr/js/iamport.payment-1.1.X.js
https://cdn.iamport.kr/js/iamport.payment-1.2.X.js
토스페이먼츠 - 신모듈 결제를 위해서는 아래 새로운 SDK를 사용해주셔야 합니다.

https://cdn.iamport.kr/v1/iamport.js

단, 새로운 SDK를 사용하시는 가맹점은 더이상 jQuery를 사용하지 않으셔도 됩니다.
URL
제공 기능
jQuery dependency
기존 SDK
- https://cdn.iamport.kr/js/iamport.payment-1.1.X.js - https://cdn.iamport.kr/js/iamport.payment-1.2.X.js
토스페이먼츠 - 신모듈 제외
O
신규 SDK
https://cdn.iamport.kr/v1/iamport.js
토스페이먼츠 - 신모듈 포함
X

결제창 호출

일반적인 결제 연동은 아임포트 인증결제 연동하기 문서에 작성 된 플로우와 동일하나 토스페이먼츠 - 신모듈을 기준으로 작성한 예시 코드는 아래와 같습니다.
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>
HTML
const userCode = '가맹점 식별코드'; IMP.init(userCode); IMP.request_pay({ pg: 'tosspayments', // 반드시 "tosspayments"임을 명시해야 함 merchant_uid: 'order_id_1667634130160', name: '나이키 와플 트레이너 2 SD', pay_method: 'card', escrow: false, amount: '109000', tax_free: 3000, buyer_name: '홍길동', buyer_email: 'buyer@example.com', buyer_tel: '02-1670-5176', buyer_addr: '성수이로 20길 16', buyer_postcode: '04783', m_redirect_url: 'https://helloworld.com/payments/result', // 모바일 환경에서 필수 입력 notice_url: 'https://helloworld.com/api/v1/payments/notice', confirm_url: 'https://helloworld.com/api/v1/payments/confirm', currency: 'KRW', locale: 'ko', custom_data: { userId: 30930 }, display: { card_quota: [0, 6] }, appCard: false, useCardPoint: true, bypass: { tosspayments: { useInternationalCardOnly: false } } ...중략 }, response => { // PC 환경에서 결제 프로세스 완료 후 실행 될 로직 ...중략 })
JavaScript
Table
Search
파라미터
데이터 타입
필수 입력 여부
의미
예시
merchant_uid
Open
string
optional
가맹점 채번 주문 고유 번호
order_id_1667635042846
name
Open
string
optional
주문명
나이키 와플 트레이너 2 SD
pay_method
Open
string
optional
결제 수단 (기본값: card)
- card (카드) - vbank (가상계좌) - trans (계좌이체) - phone (휴대폰소액결제) - booknlife (도서문화상품권) - smartculture (스마트문상) - cultureland (컬쳐랜드) - lpay (LPAY) - lgpay (LGPAY) - samsungpay (삼성페이) - ssgpay (SSGPAY) - kakaopay (카카오페이) - naverpay (네이버페이) - payco (페이코) - tosspay (토스페이)
amount
Open
string
optional
결제 금액 (기본값: 0)
109000
tax_free
Open
number
optional
면세 금액 (기본값: 0)
3000
buyer_name
Open
string
optional
구매자 이름
홍길동
buyer_tel
Open
string
optional
구매자 연락처
02-1670-5176
buyer_email
Open
string
optional
구매자 이메일 주소
gildonghong@email.com
buyer_addr
Open
string
optional
구매자 주소
성수이로 20길 16
buyer_postcode
Open
string
optional
구매자 우편번호
04783
m_redirect_url
Open
string
partially required
모바일 환경에서 결제 프로세스 완료 후 302 리디렉션 될 가맹점 웹 페이지 URL PC의 경우에는 필요 없음 주의: 모바일 환경에서는 필수 입력
https://helloworld.com/payments/result
confirm_url
Open
string
optional
결제창이 호출되고 구매자가 최종 결제 승인을 하기까지 수량 소진 등 모종의 사유로 더이상 결제가 불가능 하게 되는 상황을 대비해, 최종 결제 승인 직전 최종 결제 승인 여부를 질의할 가맹점 웹서버 endpoint 아임포트가 해당 endpoint로 최종 결제 승인 질의시, 200 외의 응답을 받으면 최종 결제 승인을 시키지 않고 결제 실패 상태로 기록함 주의: 아임포트 CS팀으로 해당 기능 사용 신청을 해야 함
https://helloworld.com/api/v1/payments/confirm
escrow
Open
boolean
optional
에스크로 결제 여부 (기본값: false) 토스페이먼츠 - 신모듈은 가상계좌와 계좌이체 수단에 대해 에스크로 결제 기능을 지원
false
escrowProducts
Open
array
optional
에스크로 결제 정보 에스크로 결제(escrow: true)시 유효 주의: 토스페이먼츠 - 신모듈에만 유효
currency
Open
string
optional
결제 통화 (기본값: KRW) 토스페이먼츠는 한화(KRW)만 지원
KRW
locale
Open
string
optional
결제창 언어 (기본값: ko) 토스페이먼츠는 한국어(ko)만 지원
ko
custom_data
Open
object
optional
결제 정보와 함께 관리하고 싶은 가맹점 커스텀 JSON 데이터
{ userId: 30930 }
vbank_due
Open
string
optional
가상계좌 결제시, 가상계좌 입금 기한 (기본값: PG사가 설정한 값) 주의: 아래 형식만 유효함 - 20221231 - 20221231235959 - 2022-12-31 - 2022-12-31 23:59:59
예1) 2022-12-31 23:59:59 예2) 2022-12-31 → 2022-12-31 23:59:59로 자동 적용
display
Open
object
optional
결제창에 렌더링 될 카드 할부 개월수 리스트 설정 값 (기본값: PG사나 카드사 정책에 따라 다름)
{ card_quota: [0, 5] }
appCard
Open
boolean
optional
카드 결제시, 카드 결제창에 앱카드만 선택 가능하도록 할지 여부 (기본값: false) 주의: 일부 카드사만 사용 가능
false
useCardPoint
Open
boolean
optional
카드 결제시, 카드 포인트 사용 허용할지 여부
true
card
Open
object
optional
카드 결제시 세부 설정 정보
{ direct: { code: ‘366’ } }
bypass
Open
object
optional
아임포트 인터페이스로 정규화되지 않은 PG사별 specific 파라미터
Table
Search
파라미터
데이터 타입
필수 입력 여부
의미
예시
imp_uid
Open
string
required
아임포트 거래 고유 번호
imp_123456789012
merchant_uid
Open
string
required
가맹점 채번 주문 고유 번호
order_id_1667635042846
error_code
Open
string
optional
결제 승인 실패 또는 중단시 에러 코드
F400
error_msg
Open
string
optional
결제 승인 실패 또는 중단시 에러 메시지
[PAY_PROCESS_CANCELED] 사용자가 결제를 취소하였습니다

기존에 deprecated된 응답들은 모두 제거됐습니다.

기존에는 위 imp_uid, merchant_uid, error_code, error_msg외에 imp_sucess 또는 success라는 boolean형 파라미터가 내려왔고 이는 트랜잭션 정상 종료 여부를 의미했습니다. 하지만 해당 파라미터의 의미가 다소 모호하고 PG사, 결제 환경(PC 또는 모바일) 그리고 결제 수단 별로 내려오는 파라미터의 종류가 상이한 레거시가 존재해 deprecated 됐으며 토스페이먼츠 - 신모듈을 대응하는 새로운 SDK(v1/iamport.js)부터는 아예 과감히 해당 파라미터들을 제거하였습니다.
따라서 새로운 SDK를 사용하실때는 IMP.request_pay로부터 응답된 객체(또는 쿼리 파라미터)에서 imp_uid를 가지고 아임포트 REST API(GET /payments/imp_uid)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회하셔야 합니다.

승인 취소(환불)

아임포트는 결제 승인 완료 건에 대해 승인 취소(환불)를 할 수 있는 REST API를 제공하고 있으며 스펙은 아래와 같습니다. (자세한 내용은 관련 문서 참고)
요청 URL: https://api.iamport.kr/payments/cancel/{imp_uid}
요청 메소드: POST
요청 본문
{ reason: '단순 변심' // 가상계좌 환불시 입금 계좌 정보 // 가상계좌 환불시 필수 입력 refund_holder: '홍길동', refund_bank: '023' refund_account: '44620123456' }
JavaScript
파라미터
필수 입력 여부
의미
예시
amount
optional
취소 요청 금액 (기본값: 결제 취소 가능 금액 전액)
109000
tax_free
optional
취소 요청 면세 금액 (기본값: 0)
3000
checksum
optional
취소 가능 금액
109000
reason
optional
취소 사유 (기본값: 취소요청api)
단순 변심
refund_holder
partially required
가상계좌 환불시, 입금 계좌 예금주
홍길동
refund_bank
partially required
가상계좌 환불시, 입금 계좌 은행 PG사별로 코드 값 상이
- 002 (산업은행) - 003 (기업은행) - 004 (국민은행) - 007 (수협은행) - 011 (농협은행) - 012 (지역농축협) - 020 (우리은행) - 088 (신한은행) - 023 (SC제일은행) - 081 (하나은행) - 027 (씨티은행) - 031 (대구은행) - 032 (부산은행) - 034 (광주은행) - 037 (전북은행) - 039 (경남은행) - 048 (신협) - 071 (우체국) - 045 (새마을금고) - 089 (케이뱅크) - 090 (카카오뱅크) - 092 (토스뱅크) - 064 (산림조합) - 050 (저축은행) - 035 (제주은행) - 054 (HSBC은행)
refund_account
partially required
가상계좌 환불시, 입금 계좌 번호
44620123456

현금영수증 등록

아임포트는 현금성 결제(가상계좌 / 계좌이체)건에 대해, 결제창에서 현금영수증 등록을 하지 못한 경우를 대비해 현금영수증을 등록할 수 있는 REST API를 제공하고 있으며 스펙은 아래와 같습니다. (자세한 내용은 관련 문서 참고)
요청 URL: https://api.iamport.kr/receipts/{imp_uid}
요청 메소드: POST
요청 본문
{ identifier: '1178178260', identifier_type: 'business', type: 'company' }
JavaScript
파라미터
필수 입력 여부
의미
예시
identifier
required
현금영수증 발행대상 식별정보 아래 항목 중 하나 입력 - 국세청 현금영수증 카드번호 - 휴대폰번호 - 주민등록번호 - 사업자등록번호
1178178260
identifier_type
optional
현금영수증 발행 대상 식별정보 유형 - person (주민등록번호) - business (사업자등록번호) - phone(휴대폰번호) - taxcard(국세청 현금영수증 카드번호)
business
type
optional
현금영수증 발행 대상 (기본값: person) - person (개인, 소득공제용) - company (회사, 지출증빙용)
company
tax_free
optional
현금영수증 발행 금액 중 면세금액 (기본값: 0)
0

external 현금영수증 등록

아임포트는 아임포트를 통해 거래되지 않은 현금성 결제 건에 대해서도 현금영수증을 발급 할 수 있는 REST API를 제공하고 있으며 스펙은 아래와 같습니다. (자세한 내용은 관련 문서 참고)
요청 URL: https://api.iamport.kr/receipts/external/{merchant_uid}
요청 메소드: POST
요청 본문
{ merchant_uid: 'order_id_1667643230720', name: '나이키 와플 트레이너 2 SD', amount: 109000, identifier: '1178178260', identifier_type: 'business', type: 'company', tax_free: '3000', pg: 'tosspayments' }
JavaScript
파라미터
필수 입력 여부
의미
예시
merchant_uid
required
가맹점 채번 주문 고유 번호
order_id_1667643230720
name
optional
주문명
나이키 와플 트레이너 2 SD
amount
required
결제 금액
109000
identifier
required
현금영수증 발행대상 식별정보 아래 항목 중 하나 입력 - 국세청 현금영수증 카드번호 - 휴대폰번호 - 주민등록번호 - 사업자등록번호
1178178260
identifier_type
optional
현금영수증 발행 대상 식별정보 유형 - person (주민등록번호) - business (사업자등록번호) - phone(휴대폰번호) - taxcard(국세청 현금영수증 카드번호)
business
type
optional
현금영수증 발행 대상 (기본값: person) - person (개인, 소득공제용) - company (회사, 지출증빙용)
company
tax_free
optional
현금영수증 발행 금액 중 면세금액 (기본값: 0)
0
pg
optional
{PG식별자}.{PG상점아이디} 신토스 - 일반결제시 필수 입력
tosspayments