결제 연동/기타 연동 방식/가상계좌 API 연동하기
목차

✅ 가상계좌 발급 API로 구매자가 원하는 은행의 가상계좌를 발급받으세요. (서버 투 서버)

✅ 발급한 계좌에 주문 금액이 입금되면 결제가 완료됩니다. 입금 통보는 웹훅으로 확인할 수 있습니다.

가상계좌 흐름도

샘플 프로젝트다양한 언어의 가상계좌 API 연동 샘플 프로젝트입니다.

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":"PfbMPPA3sJQoFo3bEvBzz","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20"}'

발급 옵션 1: 가상계좌 입금 기한 설정하기

가상계좌 입금 기한은 발급 시점으로부터 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":"7Linj2VTekcg-PrH6uNsX","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20","validHours":24}'

입금 기한 설정 파라미터

  • validHours number

    가상계좌 발급 시점으로부터 가상계좌가 유효한 시간입니다. 설정한 validHours 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 설정할 수 있는 최대값은 2160시간(90일)입니다.

  • dueDate number

    가상계좌 입금 기한입니다. dueDate이 지난 시점에 입금을 시도하면 실패합니다. 티켓 예매 등 주문 시간과 상관없이 정해진 시점까지 결제를 받아야 할 때도 사용할 수 있습니다. 설정할 수 있는 최대값은 결제 요청일로부터 90일입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.

발급 옵션 2: 고정 가상계좌 발급받기

고정 가상계좌는 일반 가상계좌와 달리 특정 고객에게 같은 가상계좌를 반복적으로 발급할 수 있는 계좌입니다. 고객 전용 가상계좌라고 볼 수 있습니다. 고객이 입금한 이후에 고정 가상계좌는 다시 반납되지만, 다시 발급을 요청할 때 같은 accountKey를 보내면 해당 키로 발급됐던 가상계좌가 다시 발급됩니다.

이런 특징 때문에 고정 가상계좌는 accountKey 파라미터를 설정해서 입금하는 고객과 1:1로 매칭해야 합니다.

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

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. 가상계좌 정보 확인하기

가상계좌 발급에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다. 응답에는 virtualAccount 필드가 포함되어 있습니다. 가상계좌의 계좌번호, 은행, 입금기한 등 돌아온 정보를 고객에게 안내해주세요.

응답
JSON
{
"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": "가상계좌"
}

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

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

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

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

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

테스트 입금하기

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

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

입금 확인하기

JSON
{
"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":"김토페"}}'

결제가 취소되면 웹훅으로 아래와 같은 이벤트 본문이 돌아옵니다.

JSON
{
"createdAt": "2022-01-01T22:24:15.805132",
"secret": "Kt96cGITIgRk2NhKDJuks",
"status": "CANCELED",
"transactionKey": "24C808B15D39D1B7CE3290A9F92F2FC4",
"orderId": ""
}

자주 묻는 질문

경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, DGB대구은행, 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 전북은행, 하나은행에서 가상계좌를 발급받을 수 있습니다.

아니요. 결제 금액만 정확히 입금된다면 주문한 고객과 입금명이 달라도 결제는 정상적으로 처리됩니다.

현금영수증은 구매자가 가상계좌에 입금한 뒤에 발급됩니다. 입금 전에는 현금영수증을 확인할 수 없습니다.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기