계좌이체 연동

결제창에서 고객이 입력한 계좌 정보를 통해 결제 금액을 이체할 수 있도록 계좌이체를 연동해보세요.

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 준비에 대한 더 자세한 설명은 연동 준비 페이지에서 확인할 수 있습니다.

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

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

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

tossPayments.requestPayment('계좌이체', { // 결제 수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
bank: '기업'
})
JavaScript

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

두 번째 파라미터는 결제 정보입니다. 필수 파라미터인 결제 금액(amount), 주문 ID(orderId) 같은 주문 정보와 결제 요청 결과에 따라 리다이렉트 될 URL(successUrl, failUrl)을 추가하세요. 은행(bank)이나 현금영수증(cashReceipt)과 같은 파라미터로 선택적으로 추가할 수 있습니다.

계좌이체 결제창 예시 이미지

결제창을 띄웠을 때 위와 같이 선택한 결제 수단인 계좌이체가 뜨고, 입력한 결제 정보가 잘 담겨있다면 결제 승인을 요청하세요.

결제 정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

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

  • orderName 필수 · string

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

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • bank string

    결제창에 사전에 선택될 은행 코드가 들어가도록 지정합니다. 은행 코드를 참고하세요.

  • cashReceipt object

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

  • type string

    현금영수증 발급 용도입니다. 소득공제지출증빙, 미발행 중 하나입니다. 소득공제, 지출증빙 중 하나의 값을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다. 미발행을 넣으면 결제창에서 현금영수증 발급 용도를 선택할 수 없습니다.

  • useEscrow boolean

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

  • escrowProducts object

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

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

    • id string

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

    • name string

      상품 이름입니다.

    • code string

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

    • unitPrice number

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

    • quantity number

      상품 구매 수량입니다.

  • customerName string

    고객의 이름입니다.

  • customerEmail string

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

  • taxFreeAmount number

    전체 결제 금액 중 면세 금액입니다. 값이 0으로 돌아왔다면 전체 결제 금액이 과세 대상입니다.

    *일반 상점일 때는 모든 결제 금액이 과세에 해당하기 때문에 0이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.

  • cultureExpense boolean

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

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

결제창 띄우기

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

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

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는 결제 승인 API에 Path 파라미터로 추가하고, orderId, amount 값은 요청 본문으로 함께 보냅니다.

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

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

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

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제 승인 성공입니다. 상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다.

계좌이체 승인 응답에는 항상 transfer 필드가 포함 되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "계좌이체",
"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": null,
"transfer": {
"bank": "기업",
"settlementStatus": "COMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
JSON

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

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