결제요청 파라미터
결제요청 파라미터를 확인 할 수 있습니다.
결제요청 파라미터 정의
channelKey: string
채널키
결제를 진행할 채널을 지정합니다.
포트원 콘솔 내 [결제 연동] - [연동 정보] - [채널 관리] 에서 확인 가능합니다.
최신 JavaScript SDK 버전부터 사용 가능합니다.
pg(deprecated): string
PG사 구분코드
다음과 같은 형식으로 기재합니다.
PG사코드.{상점ID}
pg 파라미터는 지원 중단 예정입니다.
JS SDK를 가장 최신 버전으로 업그레이드 후 channelKey
파라미터로 채널 설정(PG사 구분)을 대체해주세요.
pay_method: string
escrow: boolean
에스크로 결제창 활성화 여부
일부 PG사만 지원됩니다.
에스크로 설정은 PG사와 협의 이후 진행되어야 하는 점에 유의해주세요
products: object[]
상품 정보
토스페이먼츠 신모듈(pg
: tosspayments.~
)을 통한 에스크로 결제(escrow
: true
)시에만 유효하며, 필수값은 아닙니다.
1개의 주문 건에 여러 상품이 결제될 때 상품에 따라 배송이 다르게 이루어지는 경우, 1개의 주문에 여러 배송 정보를 넣기 위해 사용됩니다.
상품을 나타내는 아래의 객체들을 갖는 배열을 전달해주세요.
merchant_uid: string
고객사 주문번호
- 주문번호는 매 결제 요청 시마다 항상 다른, 고유한 값으로 채번되어야 합니다.
- 40자 이내로 작성해주세요
- 결제 승인완료 처리된 주문번호를 동일하게 재설정할 경우 사전거절 처리됩니다.
name: string
주문명
- 40자 이내로 작성해주세요
amount: number
결제금액
- 문자열이 아닌 숫자 타입으로 지정해야 하는 점에 유의하세요.
custom_data: object
사용자 정의 데이터
- 결제 응답시 echo 로 받아보실 수 있는 필드 입니다.
- JSON notation(string)으로 저장됩니다.
- 주문 건에 대해 부가정보를 저장할 공간이 필요할 때 사용합니다
tax_free: number
면세금액
- 결제금액 중 면세금액에 해당하는 금액을 입력합니다.
vat_amount: number
부가세
- 결제금액 중 부가세에 해당하는 금액을 입력합니다. (기본값: null)
currency: string
결제통화 구분코드
-
미입력 시 기본값은 KRW 입니다.
-
예외적으로, PayPal 은 원화(KRW) 미지원으로 인해 USD 가 기본값으로 적용됩니다.
- PayPal에서 지원하는 통화는 PayPal 지원 통화를 참고해주세요.
language: string
결제창 언어 설정 (지원되지 않는 일부 PG사 존재)
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) 수신 URL
- 포트원 관리자 콘솔에 설정한 웹훅 URL 대신 사용할 웹훅 URL 을 결제 시마다 설정할 수 있습니다.
- 해당 값 설정 시 관리자 콘솔에 설정한 URL 에는 웹훅 발송이 되지 않는 점에 유의해주세요.
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
결제완료이후 이동될 URL 주소
- 결제창이 새로운 URL 로 리다이렉트되는 결제 방식의 경우 필수 설정 항목입니다.
- 대부분의 모바일 결제환경에서 결제창 호출 시 필수적으로 요구됩니다.
- 리다이렉트 환경에서 해당 필드 누락 시 결제 결과를 수신받지 못하는 점에 유의하세요.
app_scheme: string
모바일 앱 결제 중 고객사 앱 복귀를 위한 URL scheme
- WebView 환경 결제시 필수 설정 항목입니다.
- ISP/앱카드 등에서 결제정보 인증 후 기존 앱으로 복귀할 때 사용합니다.
biz_num: string
사업자등록번호
- 다날 가상계좌 결제수단 사용 시 필수 항목입니다.
useFreeInterestFromMall: boolean
상점 부담 무이자 할부 사용 여부
고객사가 부담하는 무이자 할부 여부를 설정 할 수 있습니다.
부가기능
원하는 할부개월수만 활성화하기
{
"display": {
"card_quota": [6] // 할부개월 6개월만 활성화
}
}
파라미터 설명
할부결제는 5만원 이상 결제 요청시에만 이용 가능합니다.
카드사 결제모듈 바로(direct) 호출하기
const param = {
// ....중략....
card: {
direct: {
code: "367", // 카드사 금융결제원 표준 코드 (현대카드)
quota: 3, // 지정 할부개월수 (3개월)
},
},
};
파라미터 설명
주의사항
- PG마다 다이렉트 호출 지원 여부가 상이합니다. PG별 가이드 문서 및 테스트를 통해 다이렉트 호출이 가능한지 확인해주세요.
- 일부 PG사의 경우 승인된 상점아이디에 대해서만 카드사 결제창 direct 노출 기능을 지원합니다. 반드시 포트원을 통해 현재 사용중인 상점아이디가 카드사 결제창 direct 호출이 가능한지 확인해주세요.
원하는 카드사만 결제창 노출하기
{
"card": {
"detail": [
{ "card_code": "*", "enabled": false }, // 모든 카드사 비활성화
{ "card_code": "366", "enabled": true } // 특정 카드사 (신한카드) 만 활성화
]
}
}
파라미터 설명
상점 부담 무이자 할부 최대 개월수 설정하기
{
"card": {
"detail": [
{ "card_code": "366", "max_month": 5 }, // 특정 카드사 (신한카드) 상점 부담 무이자 최대 5개월 할부 설정
{ "card_code": "381", "max_month": 3 } // 특정 카드사 (KB국민카드) 상점 부담 무이자 최대 3개월 할부 설정
]
},
"useFreeInterestFromMall": true
}
파라미터 설명
상점 부담 무이자 할부 사용 여부