커넥트페이 UI 연동하기

커넥트페이 JavaScript SDK를 이용해 UI 작업없이 자체 간편결제를 구축하는 과정을 알아봅니다.

SDK를 초기화한 뒤 결제창 실행을 위한 필수 파라미터를 채우면 커넥트페이 결제창을 띄울 수 있습니다.

1 SDK 준비하기

스크립트를 삽입해서 SDK를 추가합니다.

파라미터로 클라이언트 키와 customerKey, 리다이렉트 URL을 추가해서 SDK를 초기화합니다. 리다이렉트 URL은 권한을 증명하는 인증코드를 받기 위해 반드시 설정해야 하는 필수 파라미터입니다.

<script src="https://js.tosspayments.com/v1/connectpay"></script>
<script> var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' var customerKey = 'customer123' // 초기화 var connectPay = ConnectPay(clientKey, customerKey, { redirectUrl: 'http://example.com/auth', // UI 커스터마이징 옵션 설정 (optional) ui: { highlightColor: '#26C2E3', buttonStyle: 'full', labels: { oneTouchPay: '바로페이', }, }, }) </script>
HTML

초기화 파라미터

  • redirectUrl 필수 · string

    리다이렉트 URL은 권한을 증명하는 인증코드를 받기 위해 반드시 필요합니다.

    개발 설정 페이지에 값이 추가되어 있어야 합니다.

  • ui string

    UI 커스터마이징 옵션을 담은 객체입니다. 각 파라미터 옵션에 따라 달라지는 결제창 UI는 SDK 페이지를 참고하세요.

    • buttonStyle string

      버튼 스타일입니다. 값이 없으면 default가 기본값으로 지정됩니다.

      default로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, full로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다.

      • default
      • full
    • highlightColor string

      UI의 메인 강조 컬러입니다. 값이 없으면 기본 색상인 #3182f6로 설정됩니다.

      웹에서 사용할 수 있는 색상 코드 형식을 모두 사용할 수 있습니다.

    • showNavigationBar string

      커넥트페이에서 제공하는 상단 내비게이션 UI를 사용할지 여부입니다. 값이 없으면 기본값으로 true가 설정됩니다.

      상단 내비게이션을 사용하지 않으려면 false로 설정해야 합니다.

    • labels object

      UI에 사용되는 커스텀 텍스트들을 모아둔 객체입니다.

      • oneTouchPay string

        UI에 표시되는 원터치결제를 대신해 사용할 텍스트입니다. 값이 없으면 원터치결제가 보여집니다.

초기화가 끝나면 SDK에 포함된 메서드를 사용할 수 있습니다. 이 과정에 대한 더 자세한 설명은 JavaScript SDK에서 확인할 수 있습니다.

2 커넥트페이 결제창 열기

SDK가 준비되었다면 requestPayment 메서드를 실행해서 커넥트페이 결제창을 열 수 있습니다.

아래와 같이 requestPayment에 결제관련 정보를 파라미터로 추가하세요.

connectPay.requestPayment({
amount: 19000, // 결제금액
orderId: '', // 주문에 대한 ID 값
orderName: '토스 티셔츠 외 2건', // 주문명
methodId: 'c_method123', // 결제수단 ID
successUrl: 'https://example.com/success', // 성공 리다이렉트 URL
failUrl: 'https://example.com/fail', // 실패 리다이렉트 URL
customerEmail: 'customer@example.com', // 고객의 이메일주소 (optional)
})
JavaScript

결제정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    가맹점에서 사용하는 해당 주문에 대한 ID입니다. 각 주문마다 유니크해야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

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

  • methodId string

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

    getPaymentMethods를 통해 결제수단 ID에 대해 자세히 알아보세요.

  • customerEmail string

    고객의 이메일주소입니다.

  • shippingAddress string

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

  • taxFreeAmount string

    면세금액입니다.

  • cardInstallmentPlan string

    카드로 결제할 때 설정하는 할부 개월 수입니다. 값이 있으면 할부 개월 수가 고정된 상태로 결제창이 열립니다.

    값은 2부터 12까지 사용할 수 있습니다. 0이 들어가는 경우 할부가 아닌 일시불로 결제됩니다.

    값을 따로 넣지 않으면 결제창에서 전체 할부 개월 수를 선택할 수 있습니다.

  • useCardPoint string

    카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않으면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다.

    이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다. 이 값을 false로 주면 사용자는 카드사 포인트를 사용할 수 없습니다.

  • discountCode string

    카드로 결제할 때 설정하는 카드사의 할인 코드입니다.

    카드혜택 조회 API를 통해 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.

  • cashReceipt string

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

    • type string

      현금영수증의 종류입니다. 미발급소득공제지출증빙 중 하나입니다. 값이 있으면 결제창에 현금영수증이 입력된 채 열립니다.

    • registrationNumber string

      현금영수증 발급을 위한 개인 식별 번호입니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

결제창 실행 후 흐름

  • 커넥트페이를 최초로 사용하는 고객이라면 약관 동의 및 인증 관련 창이 뜹니다.
  • 아직 등록된 결제수단이 없다면 결제창에서 결제수단을 등록하는 흐름으로 이어집니다.
    • 결제수단 등록창을 여는 메서드인 addPaymentMethod를 사용하면 결제창 흐름 바깥에서 결제수단 등록 기능을 제공할 수 있습니다.

3 결제승인 요청하기

리다이렉트 URL 확인하기

결제 요청이 성공하거나 실패하면 위에서 설정한 successUrl, failUrl 로 이동합니다. URL에 포함된 쿼리 파라미터로 결제승인을 요청할 수 있습니다.

성공 리다이렉트 URL은 아래와 같이 paymentKey, orderId, amount 세가지 쿼리 파라미터와 함께 돌아옵니다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • orderId: 가맹점에서 발급된 고유한 주문 ID값 입니다. 결제창을 열 때 requestPayment에 담아 보낸 값입니다.
  • amount: 실제로 결제된 금액입니다.

돌아온 파라미터들을 이용해 결제 승인 요청 API를 호출할 수 있습니다.

결제 금액이 같은지 검증하기

결제창을 열 때 requestPayment메서드에 담아 보냈던 amount값과 리다이렉트 URL에 있는 실제 결제 금액인 amount값이 같은지 확인해보세요.

값이 같다면 이제 결제 승인 API를 호출할 준비가 되었습니다.

API 호출하기

결제승인 API를 호출합니다. 리다이렉트 URL로 받은 값 중 paymentKey는 결제승인 API에 Path 파라미터로 추가하고, orderIdamount 값은 요청 본문으로 함께 보냅니다.

요청
curl https://api.tosspayments.com/v1/payments/{paymentKey} \
-H 'Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg==' \
-H 'Content-Type: application/json' \
-d '{
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"amount": 15000
}'

successUrl로 리다이렉트 된 후 10분 이내에 결제승인 API를 호출해야 합니다.

4 결제 완료하기

승인 응답을 확인해보세요. API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제승인 성공입니다.

상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다.

결제 타입을 나타내는 필드인 type의 값이 CONNECTPAY로 고정되어 있습니다.

카드 결제 승인 응답에는 card 필드가, 계좌이체 결제 승인 응답에는 transfer 필드가 포함되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.3",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "CONNECTPAY", // 커넥트페이를 이용한 결제
"easyPay": null,
"taxFreeAmount": 0
}
JSON
내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기