앱카드 결제창 연동하기

지정한 카드사의 앱카드나 자체 결제창으로 카드 결제를 연동하는 방법을 알아봅니다.

1. 먼저, SDK를 준비하세요

SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>
<body>
<script> var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' var tossPayments = TossPayments(clientKey) // 클라이언트 키로 초기화하기 </script>
</body>

SDK 준비에 대한 더 자세한 설명은 일반 결제 SDK 페이지에서 확인할 수 있습니다.

2. 결제창을 띄워보세요 🚀

객체가 초기화 되었다면 이제 SDK에 포함된 메서드를 실행할 수 있습니다. 결제창 호출에 사용되는 메서드는 requestPayment입니다.

아래와 같이 tossPayments.requestPayment(결제 수단, 결제 정보) 형식으로 파라미터를 넣고 실행하면 결제창이 열립니다.

tossPayments.requestPayment('카드', { // 결제 수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
flowMode: 'DIRECT',
cardCompany: '현대',
})
JavaScript

requestPayment 메서드의 첫번째 파라미터는 결제 수단입니다. 결제 수단으로 카드를 추가하세요.

두번째 파라미터는 결제 정보입니다. 카드사의 앱카드나 자체 결제창을 바로 실행하려면 결제 정보의 flowMode 값을 DIRECT로 고정하고 카드사 코드(cardCompany)를 필수로 추가해주어야 합니다. 카드사 코드가 없으면 결제창이 실행되지 않습니다. 결제 금액(amount), 주문 ID(orderId)도 필수 파라미터로 추가해주세요.

결제창을 띄웠을 때 cardCompany에 설정한 카드사의 앱카드나 자체 결제창으로 연결되었다면 결제 승인을 요청하세요.

카드사의 앱카드나 자체 결제창 연동은 국내 카드사만 지원합니다. 일반 카드 결제와 달리 cardCompany의 값으로 해외 카드사 코드는 사용할 수 없으니 유의하세요.

결제 정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • windowTarget string

    브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.

    값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.

    * 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

  • cardCompany string

    카드사 코드입니다. 값이 있으면 카드사가 고정된 상태로 결제창이 열립니다.

    예를 들어, BC라는 값을 주면 BC카드로 고정된 결제창이 열립니다. 카드사 코드를 참조하세요.

  • flowMode string

    값으로 DIRECT를 넣고 cardCompany 파라미터 값을 채우면 결제창의 약관 동의, 카드 선택 페이지를 건너뛰고 특정 카드사의 결제로 바로 연결됩니다.

    DEFAULT, DIRECT 중 하나의 값이 들어올 수 있습니다.

  • appScheme string

    모바일 ISP 앱에서 상점 앱으로 돌아오기 위해 사용됩니다. 내 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.

  • cardInstallmentPlan number

    할부 개월 수를 고정해 결제창을 열 때 사용합니다. 결제 금액(amount)이 5만원 이상일 때만 사용할 수 있습니다.

    2부터 12사이의 값을 사용할 수 있고, 0이 들어가는 경우 할부가 아닌 일시불로 결제됩니다.

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

  • freeInstallmentPlans array

    무이자 할부를 적용할 카드사 및 할부 개월 정보입니다. 이 파라미터에 포함된 정보와 고객이 선택한 카드사 및 할부 개월이 매칭되면 무이자 할부가 적용됩니다.

    *이 파라미터를 통해 적용된 무이자 할부 비용은 상점이 부담합니다.

    • company 필수 · string

      할부를 적용할 카드사 코드입니다. 카드사 코드를 참조하세요.

    • months 필수 · array

      무이자를 적용할 할부 개월 정보입니다. 할부 개월을 배열에 추가해주세요.

  • customerName string

    고객의 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.

  • customerEmail string

    고객의 이메일 주소입니다. 최대 길이는 100자입니다.

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

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

  • cultureExpense boolean

    문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓 박물관/미술관 입장권 등)

결제 정보 파라미터는 결제 수단에 따라 조금씩 달라집니다. 각 가이드에서 결제 수단별 파라미터 구성을 확인해보세요.

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를 호출할 수 있습니다.

결제 요청에 실패했다면 결제 실패 URL 리다이렉트를 살펴보세요.

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

결제창을 열 때 requestPayment 메서드에 담아 보냈던 amount 값과 리다이렉트 URL에 있는 실제 결제 금액인 amount 값이 같은지 확인해보세요. 값이 같다면 이제 결제 승인 API를 호출할 준비가 되었습니다.

결제 승인 API 호출하기

결제 승인 API를 호출합니다. 리다이렉트 URL로 받은 paymentKey, orderId, amount를 요청 본문으로 함께 보냅니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"CbJcJrtv9UBatPCL1cpNL","amount":15000,"orderId":"ujeGpwnym1_AwqzbZlvvq"}'

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

4. 결제를 성공적으로 완료하셨네요! 🎉

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제 승인 성공입니다.

상태 코드와 함께 카드 결제의 응답과 동일한 형태의 응답이 돌아옵니다.

응답
{
"mId": "tosspayments",
"version": "2022-06-08",
"paymentKey": "",
"status": "DONE",
"transactionKey": "",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "농협",
"number": "123456******7890",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX",
"amount": 15000
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
},
"currency": "KRW",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"method": "카드"
}
JSON

연동 과정에 어려움이 있다면 신용·체크카드 결제창 연동 후 테스트 항목을 참고하세요.

응답 필드는 API 버전에 따라 조금씩 달라집니다. 돌아온 응답에 원하는 필드가 없다면 개발자센터에 설정된 API 버전을 확인한 뒤 필요한 버전으로 변경해보세요.

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기