웰컴페이먼츠
웰컴페이먼츠 결제창 연동 방법을 안내합니다.
1. 웰컴페이먼츠 PG 설정하기
웰컴페이먼츠 설정 페이지의 내용을 참고하여 PG 설정을 진행합니다.
2. 최신 JavaScript SDK로 업데이트하기
웰컴페이먼츠 결제는 최신 SDK에서만 지원되는 기능입니다.
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>
웰컴페이먼츠를 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다
JavaScript SDK 문서를 통해 최신 SDK를 설치해주세요.
3.결제 요청하기
JavaScript SDK IMP.request_pay(param, callback)
을 호출하여 웰컴페이먼츠 결제/빌링키 발급/빌링키 발급과 동시에 결제창을 호출할 수 있습니다.
트랜잭션 결과는 PC의 경우 callback 함수로 전달되고 모바일의 경우 m_redirect_url로 302 리디렉션됩니다.
IMP.request_pay({
pg: 'welcome.{상점 ID}',
pay_method: 'card',
merchant_uid: "orderNo0001", // 가맹점에서 채번한 주문 고유 번호입니다.
name: '주문명:결제테스트',
amount: 1004,
buyer_email: 'test@portone.io',
buyer_name: '구매자이름',
buyer_tel: '010-1234-5678',
m_redirect_url: '{모바일에서 결제 완료 후 리디렉션 될 URL}',
}, function(rsp) { // callback 로직
const { imp_uid, merchant_uid } = rsp;
// 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다.
});
주요 파라미터 설명
주요 파라미터 설명
pg
* welcome
PG사 구분코드
pay_method
* string
결제수단 구분코드
- card (신용카드)
- trans (실시간 계좌이체)
- vbank (가상계좌)
- phone (휴대폰소액결제)
- culturegift (문화상품권)
- lpay (LPAY)
- kakaopay (카카오페이)
- payco (페이코)
- tosspay (토스페이)
merchant_uid
* string
주문 번호
매번 고유하게 채번되어야 합니다.
amount
* integer
결제 금액
string 이 아닌 점에 유의하세요.
tax_free
number
면세 금액
vat_amount
number
부가세 금액
상점 아이디가 “부가세 업체 정함”으로 설정 된 경우일때만 전달 가능합니다.
주의: 전체 금액의 10% 이하만 허용 됩니다.
buyer_name
* string
구매자 이름
주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다.
buyer_tel
* string
구매자 연락처
주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다.
buyer_email
string
구매자 이메일 주소
m_redirect_url
string
모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL
주의: 웰컴페이먼츠의 경우 모바일 환경에서 필수 입력입니다.
notice_url
string 또는 string[]
트랜잭션 종료 후 웹훅이 발송 될 가맹점 서버 URL
주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다.
confirm_url
string
트랜잭션 승인 직전 최종 승인 여부를 질의 할 가맹점 서버 URL
트랜잭션 승인 직전, 포트원 서버에서 confirm_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다.
app_scheme
string
IOS 앱에서 결제시 카드/은행 앱에서 인증 후 복귀 될 가맹점 커스텀 앱 URL Scheme
- 예: portone://
- 주의: IOS 앱 결제시 필수 입력이며 앱이 아닌 모바일 웹 결제시에는 입력하지 마세요.
currency
KRW
결제 통화
웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다.
language
string
결제창 언어 설정
- ko(한국어, 기본값)
- en(영어)
- zh(중국어)
digital
string
휴대폰 소액결제시 실물/컨텐츠 여부
주의: 휴대폰 소액결제시 필수 입력입니다.
vbank_due
* string
가상계좌 입금기한
- YYYY-MM-DD
- YYYY-MM-DD HH:mm:ss
- YYYYMMDD
- YYYYMMDDHHmmss
주의: 웰컴페이먼츠의 경우 무시되며 무조건 59초로 설정 됩니다.
escrow
boolean
에스크로 결제 여부
웰컴페이먼츠의 경우, 카드/계좌이체/가상계좌 결제시 에스크로 결제가 허용됩니다.
useCardPoint
boolean
카드사 포인트 사용 여부
웰컴페이먼츠의 경우, 카드사 포인트 사용 불가 옵션(useCardPoint: false)은 지원하지 않습니다.
카드사 포인트 사용(useCardPoint: true) 또는 기본값(=파라미터 전달하지 않음, 결제창에서 고객이 카드사 포인트 사용 여부 결정)만 사용 가능합니다.
useFreeInterestFromMall
boolean
상점 부담 무이자 할부 사용 여부
period
object
서비스 제공 기간
(from과 to) 또는 interval 중 하나만 입력 가능합니다.
주의: 모바일 환경 - 휴대폰 소액결제시엔 지원하지 않습니다.
-
from
: 서비스 제공 시작 시각 -
to
: 서비스 제공 종료 시각- YYYY-MM-DD
- YYYY-MM-DD HH:mm:ss
- YYYYMMDD
- YYYYMMDDHHmmss
웰컴페이먼츠의 경우
- PC: 날짜까지만 입력 가능하며 시간은 무시됩니다.
- 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다.
-
interval
: 서비스 제공 간격- 1m: 매월 정기결제
- 1y: 매년 정기결제
bypass.logo_url
string
결제창에 노출 될 메인 로고 URL(크기: 89x19)로 PC 전용 파라미터입니다.
bypass.logo_2nd
string
결제창에 노출 될 서브 로고 URL(크기: 64x13)로 PC 전용 파라미터입니다.
bypass.P_CARD_OPTION
object
모바일 카드/간편결제 전용 파라미터입니다.
-
신용카드 우선 선택 옵션
예) selcode=14
- 해당 카드 코드에 해당하는 카드가 선택된 채로 Display
- 간편결제는 불가능 (타 카드 선택 가능)
-
선택적 표시 옵션
예1) onlycard=visa3d 예2) selcode=14:onlycard=visa3d
- 안심결제: visa3d
- ISP: isp
- 간편결제: easypay 중 선택 적 표시
bypass.P_ONLY_EASYPAYCODE
string
카드 결제창 내 렌더링 될 간편 결제 리스트를 의미하며 모바일 전용 파라미터입니다.
예) 카카오페이, 엘페이, 페이코만 렌더링 → ”KAKAOPAY:LPAY:PAYCO” 전달
- 카카오페이: KAKAOPAY
- 엘페이: LPAY
- 페이코: PAYCO
- 토스페이: TOSSPAY
bypass.acceptmethod
array
형식 | 설명 |
---|---|
SKIN(색상코드) | 결제 창의 배경 색상 - 기본값 : #c1272c - 예시: SKIN(#fc6b2d) |
below1000 | 1,000원 미만 결제 허용 여부 - 기본값: 허용하지 않음 |
paypopup | 안심클릭을 팝업 형태로 렌더링 시킬지 여부 - 기본값: 레이어 |
onlyeasypaycode(간편 결제 리스트) | 카드 결제창 내 렌더링 될 간편 결제 리스트 예) 카카오페이, 엘페이, 페이코만 렌더링 → ”kakaopay:lpay:payco” 전달 - 카카오페이: kakaopay - 엘페이: lpay - 페이코: payco - 토스페이: tosspay |
SLIMQUOTA(슬림 할부 설정) | 부분 무이자 설정. 슬림 할부 - 형식) SLIMQUOTA(코드-개월:개월^코드-개월:개월 - 예시) SLIMQUOTA(11-2:3^34-2:3) |
형식 | 설명 |
---|---|
hppdefaultcorp(통신사 코드) | 휴대폰 소액결제시 기본 선택되어있는 통신사 - 기본: 기본 선택되어있는 통신사 없음 예) KT 기본 선택 → ”hppdefaultcorp(KT)” 전달 - SKT: SKT - KT: KTF - LG 유플러스: LGT - 알뜰폰 전체: MVNO - 알뜰폰 CJ 헬로 모바일: CJH - 알뜰폰 티플러스: KCT - 알뜰폰 SK 세븐모바일: SKL |
hppnofix(N 또는 Y) | 휴대폰 소액결제창에 자동 입력되는 buyer_tel 값을 수정할 수 있는지 여부 - 기본값: 수정 가능 - Y : 수정 불가능 - N : 수정 가능(기본) |
//
...중략
pg: 'welcome',
bypass: {
welcome: {
acceptmethod: [
"SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d
"below1000", // 1,000원 이하 결제 허용
"paypopup", // 안심 클릭을 팝업으로 렌더링
"onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링
"hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택
"hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능
]
}
}
bypass.P_RESERVED
array
형식 | 설명 |
---|---|
below1000=Y | 1,000원 미만 결제 허용 여부 - 기본값: 허용하지 않음 |
형식 | 설명 |
---|---|
hpp_default_corp=통신사 코드 | 휴대폰 소액결제시 기본 선택되어있는 통신사 - 기본: 기본 선택되어있는 통신사 없음 예) KT 기본 선택 → ”hpp_default_corp=KT” 전달 - SKT: SKT - KT: KTF - LG 유플러스: LGT - 알뜰폰 전체: MVNO - 알뜰폰 CJ 헬로 모바일: CJH - 알뜰폰 티플러스: KCT - 알뜰폰 SK 세븐모바일: SKL |
hpp_nofix=Y 또는 N | 휴대폰 소액결제창에 자동 입력되는 buyer_tel값을 수정할 수 있는지 여부 - 기본: 수정 가능 - Y : 수정 불가능 - N : 수정 가능(기본) |
//
...중략
pg: 'welcome',
bypass: {
welcome: {
P_RESERVED: [
"below1000=Y", // 1,000원 이하 결제 허용
"hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택
"hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능
]
}
}
웰컴페이먼츠 지원 결제 수단
웰컴페이먼츠 지원 결제 수단
- card + 에스크로, 다이렉트
- vbank + 에스크로
- trans + 에스크로
- phone
- culturegift
- lpay
- kakaopay
- payco
- tosspay
일반 결제 창 호출 파라미터에서 customer_uid, customer_id값을 추가하면 빌링키 발급 창을 호출할 수 있습니다. 빌링키 발급 창에서 빌링키를 발급 받은 후, 빌링 결제 API를 호출해 해당 빌링키로 결제를 할 수 있습니다.
IMP.request_pay({
pg: "welcome.{MID}",
pay_method: "card", // 빌링키 발급 수단입니다. 웰컴페이먼츠의 경우 'card'만 지원됩니다.
merchant_uid: "orderMonthly0001", // 가맹점에서 채번한 주문 고유 번호입니다.
name: "빌링키 발급",
amount: 1000, // 전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다.
customer_uid: "your-customer-unique-id", // 가맹점이 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다.
customer_id: "matthew", // 가맹점이 회원에게 부여한 고유 ID입니다.
buyer_email: "test@portone.io",
buyer_name: "포트원",
buyer_tel: "02-1234-1234",
m_redirect_url: "{모바일에서 빌링키 발급 완료 후 리디렉션 될 URL}",
}, function (rsp) {
const { imp_uid, merchant_uid } = rsp;
// 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 빌링키 발급 상태를 판단합니다.
});
주요 파라미터 설명
주요 파라미터 설명
pg
* welcome
PG사 구분코드
merchant_uid
* string
주문 번호
매번 고유하게 채번되어야 합니다.
amount
* integer
결제 금액
string 이 아닌 점에 유의하세요.
전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다.
pay_method
* card
빌링키 발급 수단
웰컴페이먼츠의 경우, 빌링키 발급 수단은 card
만 허용되며 반드시 card
를 필수로 입력해주셔야 합니다.
customer_uid
* string
빌링키 발급 수단 고유 ID
가맹점이 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다.
customer_id
string
구매자 고유 ID
가맹점이 구매자를 특정하기 위해 채번한 고유 번호입니다.
buyer_name
* string
구매자 이름
주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다.
buyer_tel
* string
구매자 연락처
주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다.
buyer_email
string
구매자 이메일 주소
m_redirect_url
string
모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL
주의: 웰컴페이먼츠의 경우 모바일 환경에서 필수 입력입니다.
notice_url
string 또는 string[]
트랜잭션 종료 후 웹훅이 발송 될 가맹점 서버 URL
주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다.
period
object
서비스 제공 기간
(from과 to) 또는 interval 중 하나만 입력 가능합니다.
-
from
: 서비스 제공 시작 시각 -
to
: 서비스 제공 종료 시각- YYYY-MM-DD
- YYYY-MM-DD HH:mm:ss
- YYYYMMDD
- YYYYMMDDHHmmss
웰컴페이먼츠의 경우
- PC: 날짜까지만 입력 가능하며 시간은 무시됩니다.
- 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다.
-
interval
: 서비스 제공 간격- 1m: 매월 정기결제
- 1y: 매년 정기결제
bypass.logo_url
string
결제창에 노출 될 메인 로고 URL(크기: 89x19)로 PC 전용 파라미터입니다.
bypass.logo_2nd
string
결제창에 노출 될 서브 로고 URL(크기: 64x13)로 PC 전용 파라미터입니다.
웰컴페이먼츠 지원 빌링키 발급 수단
웰컴페이먼츠 지원 빌링키 발급 수단
- card
IMP.request_pay({
pg: 'welcome.{상점 ID}',
pay_method: 'phone', // 빌링키 발급 및 결제 수단입니다. 웰컴페이먼츠의 경우 'phone'만 지원합니다.
merchant_uid: "orderNo0001", // 가맹점에서 채번한 주문 고유 번호입니다.
name: '주문명:결제테스트',
amount: 1000, // 전달한 금액 만큼 실제로 승인이 됩니다.
customer_uid: "your-customer-unique-id", // 가맹점이 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다.
customer_id: "matthew", // 가맹점이 회원에게 부여한 고유 ID입니다.
buyer_email: 'test@portone.io',
buyer_name: '구매자이름',
buyer_tel: '010-1234-5678',
m_redirect_url: '{모바일에서 결제 완료 후 리디렉션 될 URL}',
}, function(rsp) { // callback 로직
const { imp_uid, merchant_uid } = rsp;
// 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다.
});
주요 파라미터 설명
주요 파라미터 설명
pg
* welcome
PG사 구분코드
merchant_uid
* string
주문 번호
매번 고유하게 채번되어야 합니다.
amount
* integer
결제 금액
string 이 아닌 점에 유의하세요.
pay_method
* phone
빌링키 발급 및 결제 수단을
- phone (휴대폰소액결제)
웰컴페이먼츠의 경우, 빌링키 발급 동시에 결제 수단은 phone
만 허용되며 반드시 phone
을 필수로 입력해주셔야 합니다.
빌링키 발급 수단 고유 ID
가맹점이 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다.
customer_id
string
구매자 고유 ID
가맹점이 구매자를 특정하기 위해 채번한 고유 번호입니다.
buyer_name
* string
구매자 이름
주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다.
buyer_tel
* string
구매자 연락처
주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다.
buyer_email
string
구매자 이메일 주소
m_redirect_url
string
모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL
주의: 웰컴페이먼츠의 경우 모바일 환경에서 필수 입력입니다.
notice_url
string 또는 string[]
트랜잭션 종료 후 웹훅이 발송 될 가맹점 서버 URL
주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다.
confirm_url
string
트랜잭션 승인 직전 최종 승인 여부를 질의 할 가맹점 서버 URL
트랜잭션 승인 직전, 포트원 서버에서 confirm_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다.
currency
KRW
결제 통화
웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다.
digital
* string
실물/컨텐츠 여부
period
object
서비스 제공 기간
(from과 to) 또는 interval 중 하나만 입력 가능합니다.
주의: 모바일 환경에서는 지원하지 않습니다.
-
from
: 서비스 제공 시작 시각 -
to
: 서비스 제공 종료 시각- YYYY-MM-DD
- YYYY-MM-DD HH:mm:ss
- YYYYMMDD
- YYYYMMDDHHmmss
웰컴페이먼츠의 경우
- PC: 날짜까지만 입력 가능하며 시간은 무시됩니다.
- 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다.
-
interval
: 서비스 제공 간격- 1m: 매월 정기결제
- 1y: 매년 정기결제
bypass.acceptmethod
array
형식 | 설명 |
---|---|
hppdefaultcorp(통신사 코드) | 휴대폰 소액결제시 기본 선택되어있는 통신사 - 기본: 기본 선택되어있는 통신사 없음 예) KT 기본 선택 → ”hppdefaultcorp(KT)” 전달 - SKT: SKT - KT: KTF - LG 유플러스: LGT - 알뜰폰 전체: MVNO - 알뜰폰 CJ 헬로 모바일: CJH - 알뜰폰 티플러스: KCT - 알뜰폰 SK 세븐모바일: SKL |
hppnofix(N 또는 Y) | 휴대폰 소액결제창에 자동 입력되는 buyer_tel 값을 수정할 수 있는지 여부 - 기본값: 수정 가능 - Y : 수정 불가능 - N : 수정 가능(기본) |
//
...중략
pg: 'welcome',
bypass: {
welcome: {
acceptmethod: [
"SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d
"below1000", // 1,000원 이하 결제 허용
"paypopup", // 안심 클릭을 팝업으로 렌더링
"onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링
"hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택
"hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능
]
}
}
bypass.P_RESERVED
array
형식 | 설명 |
---|---|
hpp_default_corp=통신사 코드 | 휴대폰 소액결제시 기본 선택되어있는 통신사 - 기본: 기본 선택되어있는 통신사 없음 예) KT 기본 선택 → ”hpp_default_corp=KT” 전달 - SKT: SKT - KT: KTF - LG 유플러스: LGT - 알뜰폰 전체: MVNO - 알뜰폰 CJ 헬로 모바일: CJH - 알뜰폰 티플러스: KCT - 알뜰폰 SK 세븐모바일: SKL |
hpp_nofix=Y 또는 N | 휴대폰 소액결제창에 자동 입력되는 buyer_tel값을 수정할 수 있는지 여부 - 기본: 수정 가능 - Y : 수정 불가능 - N : 수정 가능(기본) |
//
...중략
pg: 'welcome',
bypass: {
welcome: {
P_RESERVED: [
"below1000=Y", // 1,000원 이하 결제 허용
"hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택
"hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능
]
}
}
웰컴페이먼츠 지원 빌링키 발급과 동시에 결제 수단
웰컴페이먼츠 지원 빌링키 발급과 동시에 결제 수단
- phone
가능한 트랜잭션 환경
가능한 트랜잭션 환경
- PC (iframe)
- 모바일 (리디렉션)