결제요청 파라미터
결제요청 파라미터를 확인 할 수 있습니다.
기존 SDK와의 변경점
-
pg
파라미터: tosspayments (토스페이먼츠 신모듈)이 추가되었습니다. -
escrowProducts
파라미터가 추가되었습니다.- 토스페이먼츠 신모듈을 사용하시면서
escrow
파라미터가true
인 경우에만 유효합니다.
- 토스페이먼츠 신모듈을 사용하시면서
결제요청 파라미터 정의
pg
string
PG사 구분코드
다음과 같은 형식으로 기재합니다.
PG사코드.{상점ID}
상세코드 확인하기
상세코드 확인하기
결제대행사
danal
(다날 휴대폰소액결제 및 휴대폰 본인인증)danal_tpay
(다날 결제창 일반/정기결제)daou
(키움페이 결제창 일반결제 및 API 수기/정기결제)html5_inicis
(이니시스 결제창 일반/정기결제)inicis_unified
(이니시스 통합인증)inicis
(이니시스 API 수기/정기결제 및 신용카드 본인인증)kcp
(NHN KCP 결제창 일반/수기결제 및 API 수기/정기결제)kcp_billing
(NHN KCP 결제창 정기결제)kicc
(이지페이(한국정보통신) 결제창 일반/정기결제)ksnet
(KSNET 결제창 일반결제 및 API 수기/정기결제)mobilians
(모빌리언스 결제창 일반/정기결제)nice
(나이스페이먼츠(구모듈) 결제창 일반결제 및 API 수기/정기결제)nice_v2
(나이스페이(신모듈) 결제창 일반결제 및 API 수기/정기결제)settle
(헥토파이낸셜 결제창 일반결제 및 API 수기/정기결제)settle_acc
(헥토파이낸셜 내통장결제)smartro
(스마트로(구모듈) 결제창 일반결제 )smartro_v2
(스마트로(신모듈) 결제창 일반/정기결제 및 API 수기/정기결제)tosspayments
(토스페이먼츠(신모듈) 결제창 일반/수기/정기결제 및 API 일반/수기/정기결제)toss_brandpay
(토스페이먼츠 브랜드페이)uplus
(토스페이먼츠(구모듈) 결제창 일반결제)welcome
(웰컴페이먼츠 결제창 일반/정기결제 및 API 일반/정기결제)
간편결제 직연동
tosspay
(토스페이 일반결제)tosspay_v2
(토스페이 일반/정기결제)payco
(페이코 일반/정기결제)kakaopay
(카카오페이 일반/정기결제)naverpay
(네이버페이-결제형)naverco
(네이버페이-주문형)smilepay
(스마일페이 일반/정기결제)
해외 결제대행사
paypal
(페이팔(ExpressCheckout) 결제창 일반결제)paypal_v2
(페이팔(SPB/RT) 결제창 일반/정기결제)eximbay
(엑심베이 결제창 일반결제)paymentwall
(페이먼트월 결제창 일반 및 API 수기/정기결제)
pay_method
string
결제수단 구분코드
PG사별 지원되는 결제수단이 모두 상이합니다.
각 PG사별 결제 연동 가이드를 참고하세요
상세코드 확인하기
상세코드 확인하기
card
(신용카드)trans
(실시간계좌이체)vbank
(가상계좌)phone
(휴대폰소액결제)applepay
(애플페이)naverpay
(네이버페이)samsungpay
(삼성페이)kpay
(KPay앱)kakaopay
(카카오페이)payco
(페이코)lpay
(LPAY)ssgpay
(SSG페이)tosspay
(토스페이)cultureland
(컬쳐랜드)smartculture
(스마트문상)culturegift
(문화상품권)happymoney
(해피머니)booknlife
(도서문화상품권)point
(베네피아 포인트 / OK캐시백 포인트)wechat
(위쳇페이)alipay
(알리페이/알리페이플러스)unionpay
(유니온페이)pinpay
(핀페이)ssgpay_bank
(SSG 은행계좌)skpay
(11Pay (구.SKPay))naverpay_card
(네이버페이 - 카드)naverpay_point
(네이버페이 - 포인트)paypal
(페이팔 SPB 결제)toss_brandpay
(토스페이먼츠 브랜드페이)tosspay_card
(토스페이 - 카드)tosspay_money
(토스페이 - 머니(계좌, 포인트))
escrow
boolean
에스크로 결제창 활성화 여부
일부 PG사만 지원됩니다.
- 에스크로 설정은 PG사와 협의 이후 진행되어야 하는점 주의하세요
escrowProducts
array
에스크로 결제 정보
에스크로 결제(escrow
: true
)시에만 유효하고, 필수 값은 아닙니다.
토스페이먼츠 신모듈 (pg
: tosspayments.~
)시에만 유효합니다
1개의 주문 건에 여러 상품이 결제될 때 상품에 따라 배송이 다르게 이루어지는 경우, 1개의 주문에 여러 배송 정보를 넣기 위해 필요합니다.
상품을 나타내는 아래의 객체들을 갖는 배열을 전달해주세요.
-
id
string상품 고유 ID
-
name
string상품명
-
code
string상품 코드
-
unitPrice
number상품 단위 가격
-
quantity
number수량
merchant_uid
string
고객사 주문번호
- 주문번호는 매 결제 요청시 고유하게 채번 되어야 합니다.
- 40Byte 이내로 작성해주세요
- 결제 승인완료 처리된 주문번호를 동일하게 재 설정시 사전거절 처리 됩니다.
name
string
결제대상 제품명
- 16byte 이내로 작성해주세요
amount
number
결제금액
- 숫자타입으로 지정해야 하는점 유의하세요
custom_data
object
사용자 정의 데이타
- 결제 응답시 echo 로 받아보실수 있는 필드 입니다.
- JSON notation(string)으로 저장됩니다.
- 주문 건에 대해 부가정보를 저장할 공간이 필요할 때 사용합니다
tax_free
number
면세금액
- 결제 금액 중 면세금액에 해당하는 금액을 입력합니다.
vat_amount
: number
부가세
- 결제 금액 중 부가세(기본값: null)
지원되는 PG사
지원되는 PG사
- 나이스페이먼츠
- (신) 토스페이
currency
string
결제통화 구분코드
- PayPal은 원화(KRW) 미 지원으로 USD가 기본
- PayPal에서 지원하는 통화는 PayPal 지원 통화 참조
상세코드 확인하기
상세코드 확인하기
language
string
결제창 언어 설정 (지원되지 않은 일부 PG사 존재)
상세코드 확인하기
상세코드 확인하기
- en (영어)
- ko (한국어)
- zh (중국어)
buyer_name
string
주문자명
buyer_tel
string
주문자 연락처
- 일부 PG사에서 해당 필드 누락시 오류 발생
buyer_email
string
주문자 이메일
- 일부 PG사에서 해당 필드 누락시 오류 발생(페이먼트월)
buyer_addr
string
주문자 주소
buyer_postcode
string
주문자 우편번호
confirm_url
string
confirm_process 사용 시 고객사 endpoint url 설정
- 기술지원 메일로 별도 요청이 필요합니다. (support@portone.io)
notice_url
string
웹훅(Webhook) 수신 주소
- 포트원 관리자 콘솔에 설정한 웹훅 주소대신 사용할 웹훅 주소를 결제시마다 설정할 수 있습니다.
- 해당 값 설정시 관리자 콘솔에 설정한 주소로는 웹훅발송이 되지 않는점 유의하시기 바랍니다.
customer_uid
string
고객사 정의 빌링키
비인증 결제 이용시 빌링키와 1:1로 맵핑되는 고객사 정의 고객 빌링키입니다.
추가속성
digital
boolean
디지털 구분자
- 휴대폰 결제수단인 경우 필수 항목입니다.
- 결제제품이 실물이 아닌 경우 true 로 설정합니다.
- 실물/디지털 여부에 따라 수수료율이 상이하게 측정되니 유의하시기 바랍니다.
vbank_due
string
가상계좌 입금기한
-
결제수단이 가상계좌인 경우 입금기한을 설정할 수 있습니다.
-
다음과 같은 형식으로 설정이 가능합니다 :
YYYY-MM-DD
YYYYMMDD
YYYY-MM-DD HH:mm:ss
YYYYMMDDHHmmss
m_redirect_url
string
결제완료이후 이동될 EndPoint URL 주소
- 결제창이 새로운 창으로 리다이렉트 되어 결제가 진행되는 결제 방식인 경우 필수 설정 항목 입니다.
- 대부분의 모바일 결제환경에서 결제창 호출시 필수 항목입니다.
- 리다이렉트 환경에서 해당 필드 누락시 결제 결과를 수신 받지 못합니다.
app_scheme
string
모바일 앱 결제중 고객사 앱복귀를 위한 URL scheme
- WebView 환경 결제시 필수설정 항목 입니다.
- ISP/앱카드 앱에서 결제정보인증 후 기존 앱으로 복귀할 때 사용합니다.
biz_num
string
사업자등록번호
- 다날-가상계좌 결제수단 사용시 필수 항목입니다.
부가기능
{
"display": {
"card_quota": [6] // 할부개월 6개월까지만 활성화
}
}
파라미터 설명
-
card_quota :
[]
: 일시불만 결제 가능2,3,4,5,6
: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능
할부결제는 5만원 이상 결제 요청시에만 이용 가능합니다.
할부개월수 3개월까지 활성화 예제
const param = {
//....중략.......
card: {
direct: {
code: "367",
quota: 3,
},
},
};
파라미터 설명
- code : 카드사 금융결제원 표준 코드. 링크 참조 (string)
- quota : 할부 개월 수. 일시불일 시 0 으로 지정. (integer)
주의사항
- 현재 KG이니시스, KCP, 토스페이먼츠, 나이스페이먼츠, KICC, 다날 6개 PG사에 대해서만 카드사 결제창 direct 호출이 가능합니다.
- 일부 PG사의 경우, 모든 상점아이디에 대하여 카드사 결제창 direct 노출 기능을 지원하지 않습니다. 반드시 포트원을 통해 현재 사용중인 상점아이디가 카드사 결제창 direct 호출이 가능하도록 설정이 되어있는지 PG사에 확인이 필요합니다.
\ 현대카드 결제모듈 바로 호출 예제
{
"card": {
"detail": [
{ "card_code": "*", "enabled": false }, //모든 카드사 비활성화
{ "card_code": "366", "enabled": true } //특정 카드만 활성화
]
}
}
파라미터 설명
- card_code : 금결원 카드사코드 링크 참조 (string)
- enabled : 해당카드 활성화 여부 (boolean)
신한카드만 결제창 노출 처리 예제