2. 최신 JavaScript SDK로 업데이트하기
토스페이먼츠 신 모듈 결제는 최신 SDK에서만 지원되는 기능입니다.
Copy <script src="https://cdn.iamport.kr/v1/iamport.js"></script>
토스페이먼츠 신모듈을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다
토스페이먼츠 신 모듈을 기준으로 작성한 예시 코드는 아래와 같습니다.
인증결제창 요청 비인증 결제창 요청 비인증 API 방식
Copy 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
merchant_uid * string
주문번호
매번 고유하게 채번되어야 합니다.
amount * integer
결제금액
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
현금성 결제(계좌이체, 가상계좌)창에서 선택할 수 있는 현금영수증 발급 유형 (기본값: 결제창에서 선택 가능)
Copy {
pay_method: 'trans',
bypass: {
isCulturalExpense: true,
cashReceiptType: 'personal'
}
} 인증결제창 호출 파라미터에서 customer_uid 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다.
Copy IMP.request_pay({
pg : 'tosspayments.{MID}',
pay_method : 'card', // 'card'만 지원됩니다.
merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호
name : '최초인증결제',
amount : 0, // 실제 승인은 발생되지 않고 오직 빌링키만 발급됩니다.
customer_uid : 'your-customer-unique-id', // 필수 입력.
buyer_email : 'test@portone.io',
buyer_name : '포트원',
buyer_tel : '02-1234-1234',
m_redirect_url : '{모바일에서 결제 완료 후 리디렉션 될 URL}',
customer_id :'matthew' //가맹점이 회원에게 부여한 고유 ID
}, function(rsp) {
if ( rsp.success ) {
alert('빌링키 발급 성공');
} else {
alert('빌링키 발급 실패');
}
});
비인증 결제를 위해서는 토스페이먼츠로 부터 발급받은 MID정보 를 포트원 관리자콘솔에 설정하셔야 비 인증 결제창을 활성화 시킬수 있습니다.
빌링키 발급시 실 결제는 발생되지 않습니다
주요 파라미터 설명
pg * string
PG사 구분코드
tosspayments
customer_uid * string
카드 빌링키
비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다.
amount * Integer
결제금액
결제창에 표시될 금액으로 실제 승인은 이루어지지 않습니다. (실 결제를 발생시키기 위해서는 customer_uid 로 REST API 를 이용하여 결제요청 을 해주셔야 합니다.)\
customer_id string
구매자 식별자
빌링키를 발급한 고객의 고유 ID 를 지정합니다.(회원ID) 해당 값 설정시 빌링키와 고객을 맵핑할 수 있습니다. 누락시 포트원에서 임의의 값을 설정합니다.
빌링키(customer_uid)로 결제 요청하기
빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 포트원 서버에 저장 됩니다. customer_uid를 가맹점 내부서버에 저장하시고 비 인증 결제요청 REST API
Copy curl -H "Content-Type: application/json" \
-X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/again API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.
MID 발급시 주의사항
토스페이먼츠로 부터 MID 발급시 API version 1.4
일회성 결제 요청하기
REST API POST /subscribe/payments/onetime 을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다.
Copy curl -H "Content-Type: application/json" \
-X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/onetime 빌링키 발급 요청하기
REST API POST /subscribe/customers/{customer_uid}
Copy curl -H "Content-Type: application/json" \
-X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \
https://api.iamport.kr/subscribe/customers/your-customer-unique-id 빌링키 발급 및 최초 결제 요청하기
REST API POST /subscribe/payments/onetime
customer_uid
Copy curl -H "Content-Type: application/json" \
-X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/onetime 빌링키로 결제 요청하기
빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 customer_uid 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 customer_uid를 이용해서 재결제(POST /subscribe/payments/again
Copy curl -H "Content-Type: application/json" \
-X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/again 할부개월수 설정 카드사 모듈 바로 호출 특정 카드사 노출 고정식 가상계좌 발급
Copy display: {
card_quota: [6], // 할부개월 6개월만 활성화
only_installment: true // 일시불 항목은 제
} 파라미터 설명
- 지정한 숫자에 해당하는 할부개월수만 표기
- []: 일시불만 결제 가능
- 2,3,4,5,6: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\
only_installment : true
할부결제는 5만원 이상 결제 요청시 에만 이용 가능합니다.
Copy card: {
direct: {
code: "367",
quota: 3
}
} 파라미터 설명
code : 카드사 금융결제원 표준 코드. 링크 string )
quota : 할부 개월 수. 일시불일 시 0 으로 지정. (integer )
Copy card : {
detail : [
{card_code:"*", enabled:false}, //모든 카드사 비활성화
{card_code:'366', enabled:true} //특정 카드만 활성화
]
} 파라미터 설명
card_code : 금결원 카드사코드 링크 string)
enabled : 해당카드 활성화 여부 (boolean)
토스페이먼츠 고정식 가상계좌 발급 서비스를 이용하기 위해서는 토스페이먼츠 측과 협의 를 통해 결제에 이용하는 MID에 고정식 가상계좌 설정이 반드시 선행되어야 합니다.
해당 설정이 완료되면 두가지 방식으로 고정식 가상계좌를 발급할 수 있습니다.
두 방식 모두 고유식별번호 가 유입되어야 하며 해당 값은 각 고객을 특정할수 있는 고유값이어야 합니다.
결제창 방식을 이용하기 위해서 고객에게 사전에 해당 고유식별번호가 안내되어야 하며 가상계좌 발급단계에서 아래 첨부이미지처럼 고유식별번호 란에 해당 값이 유입되어야 합니다.
API 방식 또한 vbank_key 파라미터가 고유식별번호에 대응되는 값으로 API방식은 가맹점에서 직접 해당 값을 기재해서 호출할수 있기 때문에 고객 편의차원에서 훨씬 간편한 고정식 가상계좌 서비스를 제공할수 있습니다.
토스페이먼츠 신모듈을 통해서 사용가능한 추가 기능들은 다음과 같습니다. 자세한 내용은 API 문서를 참고해주세요.
기존에 deprecated된 응답들은 모두 제거됐습니다. ⚠️
신 토스페이먼츠 모듈 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 dprecated 로 명시된 파라미터는 모두 삭제되었습니다.)
해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다.
imp_uid, merchant_uid
따라서 해당 SDK를 사용하실때는 IMP.request_pay로부터 응답된 객체(또는 쿼리 파라미터)에서 imp_uid를 가지고 아임포트 REST API(GET /payments/imp_uid)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회 하여 응답파라미터중 status 파라미터로 결제 상태를 파악하셔야 합니다.
