가상계좌 API로 연동하기
✅ 가상계좌 발급 API로 구매자가 원하는 은행의 가상계좌를 발급받으세요. (서버 투 서버)
✅ 발급한 계좌에 주문 금액이 입금되면 결제가 완료됩니다. 입금 통보는 웹훅으로 확인할 수 있습니다.
1. 가상계좌 발급하기
결제 정보와 구매자가 입금하려는 은행 정보를 담아 가상계좌 발급 요청 API를 호출합니다.
발급 옵션 1: 가상계좌 입금 기한 설정하기
가상계좌 입금 기한은 발급 시점으로부터 7일로 기본 설정됩니다. 입금 기한을 바꾸려면 선택 파라미터인 validHours, dueDate 둘 중 하나를 사용하세요. 설정할 수 있는 최대 기한은 발급 시점으로부터 30일입니다. 입금 기한을 넘기면 발급된 가상계좌를 더 이상 사용할 수 없습니다.
두 파라미터 중 하나만 선택해서 사용해야 합니다. 두 파라미터는 사용 기한을 발급 시점으로부터 상대적으로 설정할 지, 특정 시점으로 설정할 지에 차이가 있습니다.
예를 들어 가상계좌 입금 기한을 발급 시점부터 하루로 설정하고 싶다면, 아래와 같이 validHours 파라미터를 24로 설정해서 가상계좌 발급 요청 API를 호출하세요.
입금 기한 설정 파라미터
- validHours number
가상계좌 발급 시점으로부터 가상계좌가 유효한 시간입니다. 설정한
validHours안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 설정할 수 있는 최대값은2160시간(90일)입니다. - dueDate number
가상계좌 입금 기한입니다.
dueDate이 지난 시점에 입금을 시도하면 실패합니다. 티켓 예매 등 주문 시간과 상관없이 정해진 시점까지 결제를 받아야 할 때도 사용할 수 있습니다. 설정할 수 있는 최대값은 결제 요청일로부터 90일입니다.yyyy-MM-dd'T'HH:mm:ssISO 8601 형식을 사용합니다.
2. 가상계좌 정보 확인하기
가상계좌 발급에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다. 응답에는 virtualAccount 필드가 포함되어 있습니다. 가상계좌의 계좌번호, 은행, 입금기한 등 돌아온 정보를 고객에게 안내해주세요.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "WAITING_FOR_DEPOSIT",
"lastTransactionKey": "12FC03A573C88BC945E0B5F2D0D2A2A3",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": null,
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": {
"accountNumber": "X6505636518308",
"accountType": "일반",
"bankCode": "20",
"customerName": "박토스",
"dueDate": "2022-06-09T15:40:09+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE",
"refundReceiveAccount": null
},
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": {
"type": "소득공제",
"receiptKey": "kWzn16mywdYPBal2vxj81P72xv2m2r5RQgOAND7pJe9KE0qL",
"issueNumber": "",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/ewsXcAG7jJztpS7pi59ZJ/tosspayments?ref=PX",
"amount": 15000,
"taxFreeAmount": 0
},
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": "",
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"currency": "KRW",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"method": "가상계좌"
}
3. 입금하고 결제 완료하기 🛎
가상계좌 결제는 발급한 계좌에 구매자가 입금한 시점에 결제가 됩니다. 직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 등록된 웹훅 URL로 알림이 발송됩니다. 가상계좌 웹훅 연동 가이드에서 더 자세히 알아보세요.
테스트 입금하기
테스트 환경에서 발급한 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 컬럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.
입금 확인하기
- 개발자센터의 웹훅 페이지에서
DEPOSIT_CALLBACK웹훅을 등록하세요. - 입금이 완료되면 결제 상태가
DONE으로 바뀌고 아래와 같은 이벤트 본문이 등록한 웹훅 URL로 전송됩니다. - 이벤트 본문의
secret값이 결제 승인 응답으로 돌아온 Payment 객체의secret값과 같은지 확인하세요. 값이 같다면 토스페이먼츠 서버에서 돌아온 올바른 요청입니다.
{
"createdAt": "2022-06-09T15:40:09+09:00",
"secret": "",
"status": "DONE",
"transactionKey": "13CD6AE82C268B57F4E7FB976DC45475",
"orderId": ""
}
가상계좌 발급 요청이 정상적으로 승인된 응답에만 secret 값이 있고, 이후에 결제 조회를 할 때는 보안 이유로 secret 값이 null로 돌아옵니다.
4. 결제 취소하기
가상계좌 결제는 환불할 결제수단이 미리 등록되어 있지 않습니다. 따라서 결제 취소 API를 요청할 때 아래와 같이 refundReceiveAccount를 설정해야 합니다. 은행명, 계좌번호, 예금주 이름으로 구성된 환불 계좌 정보입니다.
취소할 때는 예금주 이름을 정확히 설정하세요. 예금주 이름이 올바르지 않으면 정상적으로 환볼되지 않습니다.
curl --request POST \
--url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"구매자가 취소를 원함","cancelAmount":10000,"refundReceiveAccount":{"bank":"20","accountNumber":"1000123456789","holderName":"김토페"}}'
결제가 취소되면 웹훅으로 아래와 같은 이벤트 본문이 돌아옵니다.
{
"createdAt": "2022-01-01T22:24:15.805132",
"secret": "Kt96cGITIgRk2NhKDJuks",
"status": "CANCELED",
"transactionKey": "24C808B15D39D1B7CE3290A9F92F2FC4",
"orderId": ""
}
자주 묻는 질문
경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, DGB대구은행, 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 전북은행, 하나은행에서 가상계좌를 발급받을 수 있습니다.
아니요. 결제 금액만 정확히 입금된다면 주문한 고객과 입금명이 달라도 결제는 정상적으로 처리됩니다.
현금영수증은 구매자가 가상계좌에 입금한 뒤에 발급됩니다. 입금 전에는 현금영수증을 확인할 수 없습니다.