가상계좌(무통장입금) 결제 연동

결제창에서 고객이 원하는 은행 정보를 입력받아 가상계좌를 발급해보세요. 해당 계좌에 주문금액이 입금되면 결제가 완료됩니다.

가상계좌 결제 흐름도

1 먼저, SDK를 준비하세요

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

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>

클라이언트 키를 사용해 객체를 초기화합니다.

var clientKey = 'test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe'
var tossPayments = TossPayments(clientKey)

2 결제창을 호출하세요 🚀

결제창 호출에 사용되는 메서드는 requestPayment입니다. 메서드를 실행하면 결제창이 열립니다.

requestPayment는 다음과 같이 사용합니다.

tossPayments.requestPayment({ 결제수단 }, { 결제정보 })

호출 준비하기

첫번째 파라미터는 결제수단입니다. 결제수단으로 가상계좌를 추가하세요.

tossPayments.requestPayment('가상계좌', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
validHours: 24,
cashReceipt: {
type: '소득공제'
}
})

두번째 파라미터는 결제정보입니다.

주문정보, 결제정보, 결제요청 결과에 따라 리다이렉트(Redirect) 될 URL을 추가해보세요.

tossPayments.requestPayment('가상계좌', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
validHours: 24,
cashReceipt: {
type: '소득공제',
},
})

결제금액(amount), 주문 ID(orderId) 같은 주문정보와 결제요청 결과에 따라 리다이렉트 될 URL(successUrlfailUrl)은 필수 파라미터입니다.

선택적으로 가상계좌 유효 시간(validHours)이나 현금영수증(cashReceipt)과 같은 정보를 추가할 수 있습니다. accountType, accountKey은 고정 가상계좌를 발급할 때만 사용합니다.

가상계좌 타입은 두 가지가 있습니다. 일반 가상계좌는 정해진 금액을 입금하면 사라지는 일회성 계좌입니다. 고정 가상계좌는 고정된 계좌에 여러 번 금액을 입금할 수 있는 계좌로, 입금할 때마다 입금 콜백이 가맹점에 전달됩니다. accountTypeaccountKey를 사용해서 원하는 타입의 계좌를 발급해보세요.

결제정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

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

  • orderName 필수 · string

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

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • accountType string

    가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.

  • accountKey string

    고정 가상계좌 발급을 위해 필요한 고유한 키값입니다.

  • validHours number

    가상계좌가 유효한 시간을 의미합니다. 기본값은 72(3일)입니다.

  • virtualAccountCallbackUrl string
    입금완료 콜백 URL 주소입니다.
  • customerEmail string

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

  • customerMobilePhone string

    고객의 휴대폰 번호입니다.

  • taxFreeAmount number
    면세금액입니다.
  • cashReceipt object

    현금영수증 발급정보를 담는 객체입니다.

    • type string

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

  • useEscrow boolean

    에스크로 사용 여부입니다. 값을 주지 않으면 사용자가 에스크로 결제 여부를 선택합니다. 기본값은 false 입니다.

  • escrowProducts object

    각 상품에 대한 상세 정보를 담는 배열입니다.

    예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.

    • id string

      상품의 ID입니다. 이 값은 유니크해야 합니다.

    • name string

      상품 이름입니다.

    • code string

      가맹점에서 사용하는 상품 관리 코드입니다.

    • unitPrice number

      상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격인 점에 유의해주세요.

    • quantity number

      상품 구매 수량입니다.

  • currency string

    결제할 때 사용할 통화 단위입니다. 값이 없으면 기본 값은 KRW입니다. 원화인 KRW만 사용합니다.

  • dueDate string

    입금 만료 시간입니다. 현재시간을 기준으로 3일 미만으로 만료시간을 직접 설정하고 싶은 경우 사용합니다. 3일 이상의 시간을 지정하는 경우 에러가 발생합니다.

    ISO 8601 형식인 YYYY-MM-DDThh:mm:ss를 사용합니다.

    validHoursdueDate 중 하나만 사용해야 합니다.

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

결제창 띄우기

결제창 호출 준비를 마치고 requestPayment 메서드를 실행하면 결제창이 열립니다.

결제창을 띄워 선택한 결제수단, 결제정보를 잘 담고 있는지 확인하고 결제승인 요청 단계를 진행하세요.

3 결제승인을 요청하세요

리다이렉트 URL 확인하기

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

성공 리다이렉트 URL에는 paymentKey, orderId, amount 세가지 쿼리 파라미터가 들어있습니다.

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

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

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

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

결제승인 API 호출하기

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"))
    .header("Authorization", "Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"amount\":15000,\"orderId\":\"Oe8MtURp3o9O3jgtVer55\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

4 승인 응답을 확인해주세요

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 승인 응답이 완료되었습니다.

상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다. 가상계좌 승인 응답에는 virtualAccount 필드가 포함 되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.3",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "가상계좌",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"status": "DONE",
"requestedAt": "2021-01-20T20:12:46+09:00",
"approvedAt": "2021-01-20T20:12:47+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": {
"accountNumber": "X6505636518308",
"accountType": "일반",
"bank": "우리",
"customerName": "박토스",
"dueDate": "2021-02-05T21:05:09+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE"
},
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"useDiscount": false,
"type": "NORMAL",
"easyPay": null
}

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

5 입금을 확인하고 결제를 완료하세요 🛎

고객의 결제수단 정보를 입력받아 요청 즉시 결제되는 다른 결제 방식과 달리, 가상계좌를 이용한 결제는 발급된 계좌에 고객이 입금한 시점에 결제가 됩니다. 따라서 비동기적으로 알게 되는 결제 상태 변화를 확인할 수 있도록 콜백 URL을 설정하고 알림을 받는 과정이 필요합니다.

금액이 입금되거나 결제가 취소되는 등의 결제 상태 변화가 생기면 가맹점이 알 수 있도록 토스페이먼츠 서버가 등록된 가맹점 콜백 URL을 호출합니다.

입금 확인은 토스페이먼츠 홈페이지 > 내 상점 > 개발 정보 페이지에서 가상계좌 입금 알림 URL 을 설정하면 가능합니다.

혹은 아래와 같이 결제창을 띄울 때 선택 파라미터 virtualAccountCallbackUrl을 추가할수도 있습니다.

tossPayments.requestPayment('가상계좌', {
amount: 15000,
orderId: 'a4CWyWY5m89PNh7xJwhk1',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
validHours: 24,
cashReceipt: {
type: '소득공제',
},
virtualAccountCallbackUrl: 'https://www.mystore.com/event/virtaul-account',
})

virtualAccountCallbackUrl은 개발 정보 페이지에서 설정한 콜백 URL보다 우선순위가 높습니다.

더 자세한 내용은 웹훅 연동하기 페이지를 참고하세요.

가상계좌 발급이 지원되는 은행

가상계좌를 발급할 수 있는 은행은 아래와 같습니다. 추가되는 은행은 지속적으로 업데이트될 예정입니다.

한글 코드영문 코드은행 이름
'경남''KYONGNAMBANK'경남은행
'국민''KOOKMIN'KB국민은행
'기업''IBK'IBK기업은행
'농협''NONGHYEOP'NH농협은행
'대구''DAEGUBANK'DGB대구은행
'부산''BUSANBANK'부산은행
'수협''SUHYUP'Sh수협은행
'신한''SHINHAN'신한은행
'우리''WOORI'우리은행
'우체국''POST'우체국예금보험
'하나''HANA'하나은행
  • 더 궁금한 내용이 있나요?자주 묻는 질문
  • 코드 샘플을 참고하세요TossPayments GitHub
  • 기술지원이 필요한가요?디스코드 채팅|이메일 보내기