개발자센터
V1
V2

토스페이먼츠

토스페이먼츠 (신 모듈 / 2022-07-27 버전) 연동 방법을 확인합니다.

1. 토스페이먼츠 PG 설정하기

토스페이먼츠 설정 페이지의 신 모듈 연동 내용을 참고하여 PG 설정을 진행합니다.

2. 최신 JavaScript SDK로 업데이트하기

토스페이먼츠 신 모듈 결제는 최신 SDK에서만 지원되는 기능입니다.

JS SDK
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>

토스페이먼츠 신모듈을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다

JavaScript SDK문서를 통해 최신 SDK를 설치해주세요.

3. 결제 요청하기

신규 SDK가 제공하는 IMP 모듈에서 request_pay 함수를 호출합니다.

pg 파라미터를 tosspayments로 지정하여 토스페이먼츠 신 모듈 연동임을 명시해주세요.

토스페이먼츠 신 모듈을 기준으로 작성한 예시 코드는 아래와 같습니다.

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: true, // 영어 결제창 활성화
      },
    },
  },
  (response) => {
    // PC 환경에서 결제 프로세스 완료 후 실행 될 로직
  }
);

주요 파라미터 설명

pg *string

PG사 구분코드

tosspayments 로 지정하면 됩니다.

pay_method string

  • 카드 (card)
  • 계좌이체(trans)
  • 가상계좌(vbank)
  • 휴대폰 소액결제(phone)
  • 도서문화상품권(booknlife)
  • 스마트문상(smartculture)
  • 컬쳐랜드(cultureland)
  • 카카오페이 (kakaopay)
  • 네이버페이 (naverpay)
  • 엘페이 (lpay)
  • 삼성페이(samsung)
  • SSGpay (ssgpay)
  • 애플페이 (applepay)
  • 페이코 (payco)
  • 토스간편결제 (tosspay)

merchant_uid * string

주문번호

매번 고유하게 채번되어야 합니다.

amount *number

결제금액

string 이 아닌점에 유의하세요

buyer_name * string

구매자 이름

buyer_email string

구매자 email 주소

currency string

통화구분코드

appCard boolean

카드 결제시, 카드 결제창에 앱카드만 선택 가능하도록 할지 여부 (기본값: false)

useCardPoint boolean

카드 결제시, 카드 포인트 사용 허용할지 여부

기타 파라미터 설명

bypass object

isCulturalExpense boolean

문화비 지출여부

useInternationalCardOnly boolean

해외카드(Visa, MasterCard, UnionPay) 결제 여부입니다. 값이 true면 해외카드 결제가 가능한 영문 결제창이 열립니다.

cashReceiptType string

현금성 결제(계좌이체, 가상계좌)창에서 선택할 수 있는 현금영수증 발급 유형 (기본값: 결제창에서 선택 가능)

  • anonymous (미발행, 자진발급)
  • personal (소득공제)
  • corporate (지출증빙)
{
	pay_method: 'trans',
	bypass: {
		isCulturalExpense: true,
		cashReceiptType: 'personal'
	}
}

3. 부가기능

javascript
display: { card_quota: [6], // 할부개월 6개월만 활성화 only_installment: true // 일시불 항목은 제외 }

파라미터 설명

  • card_quota :

- 지정한 숫자에 해당하는 할부개월수만 표기

- []: 일시불만 결제 가능

- 2,3,4,5,6: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\

  • only_installment : true 인 경우 card_quota 에 설정한 할부개월수만 표시

할부결제는 5만원 이상 결제 요청시에만 이용 가능합니다.

4. 사용가능 기능

토스페이먼츠 신모듈을 통해서 사용가능한 추가 기능들은 다음과 같습니다. 자세한 내용은 API 문서를 참고해주세요.

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

신 토스페이먼츠 모듈 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.)

해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다.

imp_uid, merchant_uid

따라서 해당 SDK를 사용하실때는 IMP.request_pay()로부터 응답된 객체(또는 쿼리 파라미터)에서 imp_uid를 가지고 아임포트 REST API(GET /payments/imp_uid)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회하여 응답 파라미터 중 status 파라미터로 결제 상태를 파악하셔야 합니다.

<script src="https://cdn.iamport.kr/v1/iamport.js"></script>

위 JS SDK 를 이용하여 토스페이먼츠,케이에스넷 연동시 callback Data는 아래와 같이 두가지 형태로만 내려갑니다.

  • imp_uid
  • merchant_uid

위 PG사를 제외한 다른 PG사는 imp_success 파라미터가 기존처럼 내려가지만 해당 파리미터는 deprecated 된 값이기 때문에 해당 값에 의존성을 가진 프로그램 로직은 모두 삭제하시는 방향성을 잡아가셔야 하는점 유념하시기 바랍니다.

토스페이먼츠 API 버전 설정

  • 토스페이먼츠 개발자센터 로그인

  • 왼쪽 네비게이션 메뉴 API 키 선택 → API 버전을 2022-07-27로 선택

    API 버전을 다르게 설정하면 결제 승인 / 실패 시 실제 응답과 다른 응답을 받아볼 수 있으니 반드시 API 버전을 2022-07-27로 맞춰주시기 바랍니다