개발자센터
V1
V2
이 페이지의 다른 버전 보기
릴리즈 노트 기술 블로그

결제요청 파라미터

결제요청 파라미터를 확인 할 수 있습니다.

결제요청 파라미터 정의

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사

  • 나이스페이먼츠
  • (신) 토스페이

currency string

결제통화 구분코드

  • PayPal은 원화(KRW) 미 지원으로 USD가 기본
  • PayPal에서 지원하는 통화는 PayPal 지원 통화 참조

상세코드 확인하기

결제통화 구분코드

  1. KRW
  2. USD
  3. EUR
  4. JPY
  • 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 설정

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)

신한카드만 결제창 노출 처리 예제