API & SDK/브랜드페이
목차

브랜드페이 JavaScript SDK

브랜드페이 JavaScript SDK는 브라우저 환경에서 사용할 수 있는 브랜드페이 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.

SDK 설치 및 초기화

<script> 태그에 브랜드페이 SDK 파일을 추가합니다. 스크립트가 로드되면 전역 객체(window)에 생기는 BrandPay() 초기화 함수에 파라미터를 설정해서 브랜드페이 객체를 생성하세요.

checkout.html
HTML
<head>

  <meta charset="utf-8" />

  <!-- 1. 스크립트 추가 -->

  <script src="https://js.tosspayments.com/v1/brandpay"></script>

</head>

<script>
  var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 테스트용 클라이언트 키
  var customerKey = '' // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID

  // 2. 브랜드페이 객체 생성
  var brandpay = BrandPay(clientKey, customerKey, {
    redirectUrl: 'http://example.com'
  })
</script>

초기화 파라미터

  • clientKey 필수 · string

    클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 API 개별 연동 키 > 브랜드페이 MID로 발급된 키 값을 사용하세요.

  • customerKey 필수 · string

    구매자 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.

  • options object

    인증에 필수인 리다이렉트 URL, 선택적으로 적용할 수 있는 UI 옵션으로 이루어진 객체입니다.

  • redirectUrl string

    리다이렉트 URL에는 Access Token 발급 과정에 필요한 값이 돌아옵니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 브랜드페이 페이지에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.

    * 브랜드페이 페이지에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.

  • windowTarget string

    브랜드페이 창을 여는 방법입니다. iframe, popup 중 하나입니다. 기본값은 iframe입니다. 모바일 환경에서는 popup을 사용할 수 없습니다.

메서드

브랜드페이 JavaScript SDK에서 제공하는 메서드 목록입니다.

브랜드페이 회원은 SDK를 초기화할 때 사용한 customerKey로 구분됩니다. 회원의 결제수단이 등록되지 않은 상태에서 브랜드페이 메서드를 실행하면 결제수단 등록이 먼저 진행됩니다.

브랜드페이를 처음 사용한다면 휴대폰 본인인증이 필수입니다. 처음 한 번 인증하고 하면, 나중에 카드를 등록할 때 다시 인증할 필요가 없습니다.

addPaymentMethod('카드'|'계좌')

결제수단을 등록하는 메서드입니다.

JavaScript
brandpay

  .addPaymentMethod('카드')

  .then(function (methods) {

    // 성공 처리

  })

  .catch(function (error) {

    if (error.code === 'USER_CANCEL') {

      // 사용자가 결제창을 닫은 경우 에러 처리

    }

  })

파라미터

  • methodType string

    등록하고 싶은 결제수단입니다. 카드, 계좌를 지원합니다. 파라미터 없이 실행하면 계좌와 카드를 모두 등록할 수 있는 창으로 연결됩니다.

응답

결제수단이 등록되면 Promise가 돌아옵니다. Promise는 다음과 같은 결제수단 정보가 있는 객체를 반환합니다.

  • newCustomerToken: 토스페이먼츠에서 사용하는 고객의 인증 토큰입니다.
  • result: 고객의 결제 수단 정보를 담은 BrandpayMethodResponse 객체입니다.

getPaymentMethods()

등록된 결제수단을 조회하는 메서드입니다.

JavaScript
brandpay

  .getPaymentMethods()

  .then(function (methods) {

    // 성공 처리

  })

  .catch(function (error) {

    if (error.code === 'USER_CANCEL') {

      // 사용자가 결제창을 닫은 경우 에러 처리

    }

  })

응답

결제수단을 조회하면 Promise가 돌아옵니다. Promise는 결제수단 정보가 있는 BrandpayMethodResponse 객체를 반환합니다.

requestPayment(결제 정보)

브랜드페이 결제창을 띄우고 결제를 요청하는 메서드입니다. 결제 요청의 응답을 처리하는 방법을 알아보세요.

JavaScript
brandpay

  .requestPayment({

    amount: 15000,

    orderId: '',

    orderName: '토스 티셔츠 외 2건',

    customerEmail: 'customer@example.com',

  })

  .then(function (data) {

    // 결제 요청 성공 처리

  })

  .catch(function (error) {

    if (error.code === 'USER_CANCEL') {

      // 사용자가 창을 닫아 취소한 경우에 대한 처리

    }

  })

파라미터

  • RequestPaymentParameters 필수 · object

    결제 정보 파라미터입니다.

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    주문번호입니다. 주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다.

  • successUrl string

    결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다. 리다이렉트 URL 방식으로 결제 요청을 처리하고 싶을 때 추가해주세요.

  • failUrl string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.

  • methodId string

    결제수단 ID 입니다. 등록되어 있는 결제수단 중 하나를 지정해서 바로 결제하고 싶을 때 사용합니다.

  • customerEmail string

    구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • shippingAddress string

    고객의 배송지 주소입니다. 부정거래탐지시스템(FDS, Fraud Detection System, 거래 정보와 고객 정보, 평소 거래 패턴 등을 분석해서 의심되는 전자금융거래를 탐지하고 차단하는 기술)에 사용할 수 있습니다.

  • taxFreeAmount string

    결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • cultureExpense boolean

    문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. 결제수단이 계좌일 때만 설정하세요.

  • cardInstallmentPlan number

    신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다.

    • 2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다.
    • 결제 금액(amount)이 5만원 이상일 때만 할부가 적용됩니다.
  • useCardPoint boolean

    카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않거나 값이 false라면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다. 이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다.

    * 추가 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

  • discountCode string

    카드 또는 계좌 즉시 할인 코드입니다.

    카드 프로모션 조회 API, 계좌 프로모션 조회 API로 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.

  • cashReceipt object

    계좌로 결제할 때 현금영수증 발급 정보를 담는 객체입니다.

  • type 필수 · string

    현금영수증의 종류입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.

  • registrationNumberType string

    현금영수증 번호 타입입니다. 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 중 하나를 선택할 수 있습니다.

    • MOBILE: 휴대폰 번호

    • BUSINESS_REGISTRATION: 사업자등록번호

    • CASH_RECEIPT_CARD: 현금영수증 카드 번호

  • registrationNumber string

    현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

응답

requestPayment() 메서드의 응답은 리다이렉트 URL 또는 Promise로 받을 수 있습니다. 자세한 응답 데이터를 확인하세요.

  • 결제 요청이 성공하면 paymentKey, orderId, amount, methodId가 반환됩니다. 결제 금액이 맞는지 확인하고 결제를 완료하기 위해 결제 승인 API를 호출하세요.
  • 결제 요청이 실패하면 에러 코드와 메시지가 반환됩니다.

openSettings()

브랜드페이 결제 관리창을 여는 메서드입니다. 결제수단 관리, 결제 비밀번호 설정, 원터치결제 설정, 이메일 관리 메뉴가 있습니다.

JavaScript
brandpay.openSettings()

응답

결제 관리창이 열리면 resolve되지 않는 Promise가 반환됩니다.

setupPassword()

결제 비밀번호를 변경하는 메서드입니다. 기존 비밀번호를 입력하고 새로운 비밀번호를 설정할 수 있어요. 결제수단이 등록되지 않은 구매자라면 결제수단이 등록됩니다.

JavaScript
brandpay.setupPassword().catch(function (error) {

  if (error.code === 'USER_CANCEL') {

    // 사용자가 창을 닫아 취소한 경우에 대한 처리

  }

})

응답

비밀번호 등록・변경이 완료되면 resolve되지 않는 Promise가 반환됩니다.

setupOneTouchPay()

원터치결제 설정창을 여는 메서드입니다. 원터치결제를 끄거나 켤 수 있습니다. 원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

JavaScript
brandpay.setupOneTouchPay()

응답

원터치결제 설정창이 열리면 resolve되지 않는 Promise가 반환됩니다.

toggleOneTouchPay()

원터치결제 설정창에 진입하지 않고 바로 끄거나 켤 때 사용합니다. 원터치결제가 꺼진 상태에서 켤 때는 비밀번호를 입력해야 설정이 완료됩니다. 켜진 상태에서 끌 때는 바로 상태가 변경됩니다.

원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

JavaScript
brandpay.toggleOneTouchPay()

  .then(data) {

    // 성공 처리

  }

  .catch(function (error) {

  if (error.code === 'USER_CANCEL') {

    // 사용자가 창을 닫아 취소한 경우에 대한 처리

  }

})

응답

원터치결제 설정이 바뀌면 Promise가 resolve되고 다음과 같은 객체를 반환합니다.

  • isEnabled: 원터치결제 설정을 켤 때는 true 값이 돌아오고, 원터치결제 설정을 끄면 false 값이 돌아옵니다.

isOneTouchPayEnabled()

사용자의 원터치결제 설정 상태를 확인할 때 사용합니다. 원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

JavaScript
brandpay.isOneTouchPayEnabled()

  .then(isEnabled) {

    // 성공 처리

  }

  .catch(function (error) {

  if (error.code === 'USER_CANCEL') {

    // 사용자가 창을 닫아 취소한 경우에 대한 처리

  }

})

응답

원터치결제 설정 상태가 확인되면 Promise가 resolve되고 boolean을 반환합니다. 원터치결제가 설정되어 있다면 true, 설정되어 있지 않으면 false가 돌아옵니다.

requestAgreement(약관 항목)

약관 동의 창을 띄우는 메서드입니다. 자동결제(빌링)를 연동할 때만 이 메서드를 실행하세요. 회원가입, 카드, 계좌 관련 약관은 최초에 결제수단을 등록할 때 SDK가 자동으로 메서드를 실행합니다.

응답
JavaScript
brandpay

  .requestAgreement('빌링') // 자동결제 선택 약관 동의 호출

  .then(function () {

    // 성공 처리

  })

  .catch(function (error) {

    if (error.code === 'USER_CANCEL') {

      // 사용자가 창을 닫아 취소한 경우에 대한 처리

    }

  })

파라미터

  • termScope string

    동의를 받고 싶은 약관 항목입니다. 예를 들어 빌링으로 설정하면 자동결제 약관 동의 창이 열립니다. 카드, 계좌, 회원가입, 빌링을 지원합니다.

응답

구매자가 약관에 동의하면 Promise가 resolve됩니다.

BrandpayMethodResponse 객체

  • selectedMethodId string

    가장 최근에 등록했거나 사용한 결제수단의 id 값입니다.

  • cards array

    등록된 카드 정보입니다.

  • id string

    결제수단의 아이디입니다.

  • cardName string

    카드 이름입니다.

  • alias string

    고객이 직접 설정한 해당 결제수단의 별명입니다.

  • cardNumber string

    카드 번호입니다.

  • cardCompany string

    카드 발급사 코드입니다. 카드사 코드를 참고하세요.

  • issueCompany string

    카드 발급사 코드입니다. 카드사 코드를 참고하세요.

  • companyCode string

    카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.

  • acquirerCode string

    카드 매입사 숫자 코드입니다. 카드사 코드를 참고하세요.

  • issuerCode string

    카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.

  • ownerType string

    카드의 소유자 타입입니다. 개인, 법인 중 하나입니다.

  • cardType string

    카드 종류입니다. 신용, 체크, 기프트 중 하나입니다.

  • installmentMinimumAmount string

    할부가 가능한 최소 금액 정보입니다. 이 금액과 고객이 결제할 금액을 비교해서 할부 선택 UI를 보여줄 지 결정할 수 있습니다.

  • registeredAt string

    결제수단을 등록한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)

  • status string

    결제수단 활성화 여부를 나타냅니다. 결제수단을 조회할 때는 이 값이 ENABLED인 결제수단만 돌아옵니다. 결제수단을 삭제하면 이 값이 DISABLED로 변경됩니다.

    • ENABLED: 결제수단이 등록되어 사용할 수 있는 상태
    • DISABLED: 결제수단이 삭제되어 사용할 수 없는 상태
  • isAvailable boolean

    결제수단 사용 가능 여부입니다.

  • icon string

    카드사・은행 아이콘입니다. 예를 들어 icn-bank-square-hyundaicard는 현대카드 아이콘 코드입니다. icn-bank-square-에 카드사・은행 이름이 조합되어 있습니다.

  • iconUrl string

    카드사・은행 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드사・은행 아이콘을 보여줄 수 있습니다.

  • icons string

    카드사・은행 아이콘 이름, URL입니다.

    • fill: 배경이 채워진 아이콘입니다.
    • normal: 배경이 없는 아이콘입니다.
    • square: 직사각형 아이콘입니다.
  • color string

    아이콘의 색상입니다. 아이콘 이미지와 함께 결제수단 UI를 직접 만들 때 사용할 수 있습니다.

    • background: 아이콘의 배경색입니다.
    • text: 아이콘의 텍스트 색입니다.
  • cardImgUrl string

    카드 실물 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드 실물 이미지를 보여줄 수 있습니다.

  • cardProductCode string

    PLCC 상품을 구분하는 코드입니다. 카드사에서 발급합니다.

  • promotions array

    카드사 프로모션 정보가 담기는 배열입니다. 혜택이 큰 순서대로 정렬되어 내려갑니다.

  • type string

    프로모션 종류입니다. 아래 네 가지 값 중 하나가 돌아옵니다. 상세 정보는 type 이름과 같은 객체에 들어있습니다.

    • CARD_DISCOUNT: 카드 즉시 할인입니다. cardDiscount 객체에 관련 정보가 돌아옵니다.

    • CARD_INTEREST_FREE: 카드 무이자 할부입니다. cardInterestFree 객체에 관련 정보가 돌아옵니다.

    • CARD_POINT: 카드 포인트 할인입니다. cardPoint 객체에 관련 정보가 돌아옵니다.

    • BANK_DISCOUNT: 계좌 할인입니다. bankDiscount 객체에 관련 정보가 돌아옵니다.

  • cardDiscount string

    카드사의 즉시 할인 정보입니다.

  • issuerCode string

    프로모션을 진행하는 카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.

  • discountAmount string

    할인되는 금액입니다.

  • minimumPaymentAmount string

    카드사 즉시 할인을 적용할 수 있는 최소 결제 금액입니다.

  • maximumPaymentAmount string

    카드사 즉시 할인을 적용할 수 있는 최대 결제 금액입니다.

  • currency string

    통화 정보입니다.

  • discountcode string

    프로모션 코드입니다. 카드사에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

  • dueDate string

    프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

  • balance string

    남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다.

  • cardInterestFree string

    카드 무이자 할부 정보입니다.

    • issuerCode 프로모션을 진행하는 카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.

    • minimumPaymentAmount 무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

    • currency 통화 정보입니다.

    • dueDate 프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

    • installmentFreeMonths 카드 무이자 할부를 적용할 수 있는 개월 수 입니다.

  • cardPoint string

    카드 포인트 정보입니다.

    • issuerCode 프로모션을 진행하는 카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.

    • minimumPaymentAmount 카드 포인트를 적용할 수 있는 최소 결제 금액입니다.

    • currency 통화 정보입니다.

    • dueDate 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

  • accounts array

    등록된 계좌 정보입니다.

  • id string

    결제수단의 아이디입니다.

  • type string

    계좌 유형입니다. 일반 출금 계좌를 등록하면 WITHDRAW 값이 돌아옵니다.

  • accountName string

    계좌 이름입니다.

  • alias string

    고객이 직접 설정한 해당 결제수단의 별명입니다.

  • bankCode string

    은행 숫자 코드입니다. 단위농협과 홍콩상하이은행을 제외하고 지원합니다. 은행 코드를 참고하세요.

  • accountNumber string

    계좌번호입니다.

  • registeredAt string

    결제수단을 등록한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)

  • status string

    결제수단 활성화 여부를 나타냅니다. 결제수단을 조회할 때는 이 값이 ENABLED인 결제수단만 돌아옵니다. 결제수단을 삭제하면 이 값이 DISABLED로 변경됩니다.

    • ENABLED: 결제수단이 등록되어 사용할 수 있는 상태
    • DISABLED: 결제수단이 삭제되어 사용할 수 없는 상태
  • isAvailable boolean

    결제수단 사용 가능 여부입니다.

  • icon string

    카드사・은행 아이콘입니다. 예를 들어 icn-bank-square-hyundaicard는 현대카드 아이콘 코드입니다. icn-bank-square-에 카드사・은행 이름이 조합되어 있습니다.

  • iconUrl string

    카드사・은행 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드사・은행 아이콘을 보여줄 수 있습니다.

  • icons string

    은행 아이콘 이름, URL입니다.

    • fill: 배경이 채워진 아이콘입니다.
    • normal: 배경이 없는 아이콘입니다.
    • square: 직사각형 아이콘입니다.
  • color string

    아이콘의 색상입니다. 아이콘 이미지와 함께 결제수단 UI를 직접 만들 때 사용할 수 있습니다.

    • background: 아이콘의 배경색입니다.
    • text: 아이콘의 텍스트 색입니다.
  • promotions array
  • bankDiscount string

    계좌 할인 정보입니다.

    • bankCode 프로모션을 진행하는 은행 숫자 코드입니다. 은행 코드를 참고하세요.

    • discountAmount 할인 금액입니다.

    • minimumPaymentAmount 계좌 할인을 적용할 수 있는 최소 결제 금액입니다.

    • maximumPaymentAmount 계좌 할인을 적용할 수 있는 최대 결제 금액입니다.

    • currency 통화 정보입니다.

    • discountCode 계좌 할인 프로모션 코드입니다. 은행에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

    • dueDate 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

결제 요청 응답 처리

requestPayment() 메서드 응답은 리다이렉트 URL 또는 Promise로 처리할 수 있습니다.

리다이렉트 URL로 처리하기

✔️ PC 및 모바일 환경에서 사용하세요.

✔️ requestPayment()의 successUrl, failUrl 파라미터를 설정하세요.

✔️ 응답 데이터를 successUrl, failUrl의 쿼리 파라미터로 확인하세요.

주문서
JavaScript
brandpay

  .requestPayment({

    amount: 15000,

    orderId: '',

    orderName: '토스 티셔츠 외 2건',

    // 테스트에서는 성공, 실패 페이지가 없어도 URL에서 쿼리 파라미터를 확인할 수 있어요.

    successUrl: 'http://localhost:8080/success', // 성공 리다이렉트 URL

    failUrl: 'http://localhost:8080/fail', // 실패 리다이렉트 URL

  })

  // 결제창을 띄울수 없는 에러가 발생하면 리다이렉트 URL로 에러를 받을 수 없어요.

  .catch(function (error) {

    if (error.code === 'INVALID_ORDER_NAME') {

      // 유효하지 않은 'orderName' 처리하기

    } else if (error.code === 'INVALID_ORDER_ID') {

      // 유효하지 않은 'orderId' 처리하기

    }

  })

✅ 결제 요청 성공: successUrl로 리다이렉트 됩니다. 쿼리 파라미터로 결제 승인 API를 호출하세요.

https://{ORIGIN}/success?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}&methodId={METHOD_ID}

❎ 결제 요청 실패: failUrl로 리다이렉트 됩니다. 에러 목록을 확인하세요.

https://{ORIGIN}/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}

Promise로 처리하기

✔️ PC 및 모바일 환경에서 사용하세요.

✔️ requestPayment()의 successUrl, failUrl, windowTarget 파라미터를 설정하지 마세요.

✔️ 응답 데이터를 then, catch로 확인하세요.

예시
JavaScript
brandpay

  .requestPayment({

    //결제 정보 파라미터

    // successUrl, failUrl, windowTarget 파라미터를 넘기지 마세요.

  })

  .then(function (data) {

    // 성공 처리: 서버 측에서 결제 승인 API를 호출하세요

  })

  .catch(error => {

    // 에러 처리: 에러 목록을 확인하세요

    // https://docs.tosspayments.com/reference/error-codes#failurl로-전달되는-에러

    if (error.code === 'USER_CANCEL') {

      // 결제 고객이 결제창을 닫았을 때 에러 처리

    } else if (error.code === 'INVALID_CARD_COMPANY') {

      // 유효하지 않은 카드 코드에 대한 에러 처리

    }

  })

응답 데이터

성공 응답

  • paymentKey string

    결제를 식별하는 키 값입니다. 토스페이먼츠에서 발급합니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.

  • orderId string

    주문번호입니다. 결제 요청에 보낸 값입니다.

  • amount number

    결제 금액입니다. 결제 요청에 보낸 결제 금액과 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

  • methodId string

    결제수단의 ID입니다.

실패 응답

  • code string

    에러 코드입니다. 에러 목록을 확인하세요.

  • message string

    에러 메시지입니다.

  • orderId string

    주문번호입니다. 결제 요청에 담아 보낸 값입니다.

  • 더 궁금한 내용이 있나요?
    자주 묻는 질문
  • 코드 샘플을 참고하세요
    TossPayments GitHub
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기