토스페이먼츠(신모듈)

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

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

결제대행사 채널 설정하기 페이지의 내용을 참고하여 채널 설정을 진행합니다.

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(
  {
    channelKey: "{콘솔 내 연동 정보의 채널키}",
    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 환경에서 결제 프로세스 완료 후 실행 될 로직
  },
);

4. 부가기능

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만원 이상 결제 요청시에만 이용 가능합니다.

5. 사용가능 기능

토스페이먼츠 신모듈을 통해서 사용가능한 추가 기능들은 다음과 같습니다. 자세한 내용은 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로 맞춰주시기 바랍니다