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를 사용하지 않으셔도 됩니다.
더이상 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
Table
Search
기존에 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)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회하셔야 합니다.
자세한 내용은 일반결제 연동하기 > STEP5. 결제 정보 검증 및 저장하기를 참고해주세요.
승인 취소(환불)
아임포트는 결제 승인 완료 건에 대해 승인 취소(환불)를 할 수 있는 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 |
