목차

고객이 선택한 은행에서 가상계좌를 발급받으세요. 해당 계좌에 주문금액이 입금되면 결제가 완료됩니다. 입금 통보는 웹훅으로 확인할 수 있습니다.

가상계좌 흐름도

샘플 프로젝트다양한 언어의 가상계좌 API 연동 샘플 프로젝트입니다
경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, DGB대구은행, 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 전북은행, 케이뱅크, 하나은행에서 가상계좌를 발급받을 수 있습니다.
아니요. 결제 금액만 정확히 입금된다면 주문한 고객과 입금명이 달라도 결제는 정상적으로 처리됩니다.
현금영수증은 고객이 가상계좌에 입금한 뒤에 발급됩니다. 입금 전에는 현금영수증을 확인할 수 없습니다.

1. 가상계좌 발급하기

결제 고객이 원하는 은행 정보와 결제 정보를 담아 가상계좌 발급 요청 API를 호출합니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/virtual-accounts \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"amount":15000,"orderId":"gwZjZXrOdVFyobTPibJkE","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20","cashReceipt":{"type":"소득공제","registrationNumber":"01011111111"}}'

가상계좌 입금 기한 설정하기

가상계좌 입금 기한의 기본 값은 발급 시점으로부터 7일입니다. 입금 기한을 바꾸려면 validHours, dueDate 선택 파라미터를 사용하세요. 설정할 수 있는 최대 기한은 발급 시점으로부터 30일입니다. 입금 기한을 넘기면 발급된 가상계좌는 더 이상 사용할 수 없습니다.

두 파라미터 중 하나만 선택해서 사용해야 합니다. 두 파라미터는 사용 기한을 발급 시점으로부터 상대적으로 설정할 지, 특정 시점으로 설정할 지에 차이가 있습니다.

예를 들어 가상계좌 입금 기한을 발급 시점부터 하루로 설정하고 싶다면, 아래와 같이 validHours 파라미터를 24로 설정해서 가상계좌 발급 요청 API를 호출하세요.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/virtual-accounts \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"amount":15000,"orderId":"kIcWU6BmRkkwCHECxuumh","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20","validHours":24}'

입금 기한 설정 파라미터

  • validHours number

    가상계좌가 유효한 시점을 시간 단위로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, validHours120으로 설정하면 발급 후 120시간 뒤인 2022년 1월 5일 오전 1시 전까지 입금되어야 합니다.

  • dueDate number

    입금 기한을 특정 시점으로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, dueDate2022-01-10T01:00:00로 설정하면 2022년 1월 10일 오전 1시 전까지 입금되어야 합니다.

고정 가상계좌 발급받기

고정 가상계좌는 특정 고객이 최초에 발급받은 계좌에 반복적으로 입금할 수 있는 계좌입니다. 고객 전용 가상계좌라고 볼 수 있습니다. 이런 특징 때문에 고정 가상계좌는 accountKey 파라미터를 설정해서 입금하는 고객과 1:1로 매칭해야 합니다.

아래와 같이 accountKey 파라미터를 추가해서 가상계좌 발급 요청 API를 호출하세요. 응답으로 virtualAccount.accountType고정Payment 객체가 돌아옵니다.

첫 발급 후 다시 발급을 요청할 때 같은 accountKey를 보내면 해당 키로 발급됐던 가상계좌가 다시 발급됩니다.

curl --request POST \
--url https://api.tosspayments.com/v1/virtual-accounts \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"accountKey":"a123456","amount":15000,"orderId":"H7joPUPUeuoPRVqPPfWRS","orderName":"토스 티셔츠 외 2건","customerName":"김토스","bank":"20"}'

고정 가상계좌 설정 파라미터

  • accountKey string

    고정 가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키 값입니다. 주민등록번호나 휴대폰 번호 등 개인 정보가 특정될 수 있는 값을 포함하면 안됩니다.

고정 가상계좌는 추가 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

2. 가상계좌 정보 확인하기

API 호출 결과로 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": "가상계좌"
}
JSON

🙋 응답 객체에 원하는 필드가 없어요.

응답 객체의 필드는 API 버전에 따라 조금씩 달라집니다. 개발자센터에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요.

API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.

3. 입금하고 결제 완료하기 🛎

가상계좌 결제는 발급된 계좌에 고객이 입금한 시점에 결제가 됩니다. 직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 등록된 웹훅 URL로 알림이 발송됩니다.

테스트 입금하기

테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 컬럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.

토스페이먼츠 가상계좌 테스트하기

입금 확인하기

{
"createdAt": "2022-06-09T15:40:09+09:00",
"secret": "",
"status": "DONE",
"transactionKey": "13CD6AE82C268B57F4E7FB976DC45475",
"orderId": ""
}
JSON

가상계좌 발급 요청이 정상적으로 승인된 응답에만 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": ""
}
JSON
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기