계좌이체 연동

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

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',
bank: '기업'
})

두번째 파라미터는 결제정보입니다. 주문정보, 결제정보, 결제요청 결과에 따라 리다이렉트(Redirect) 될 URL을 추가해보세요.

tossPayments.requestPayment('계좌이체', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
bank: '기업',
})

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

선택적으로 은행(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

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

  • taxFreeAmount number

    면세 금액입니다.

  • customerName string

    고객의 이름입니다.

  • customerEmail string

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

  • cashReceipt object

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

  • type string

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

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

결제창 띄우기

결제창 호출 준비를 마치고 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\":\"F2cbJadSYC2D9_J1nbeXi\"}"))
    .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.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": null,
"transfer": {
"bank": "기업",
"settlementStatus": "COMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"useDiscount": false,
"type": "NORMAL",
"easyPay": null
}

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

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