고객이 선택한 은행에서 가상계좌를 발급받으세요. 해당 계좌에 주문금액이 입금되면 결제가 완료됩니다. 입금 통보는 웹훅으로 확인할 수 있습니다.
결제 고객이 원하는 은행 정보와 결제 정보를 담아 가상계좌 발급 요청 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)이고,
validHours
를120
으로 설정하면 발급 후 120시간 뒤인 2022년 1월 5일 오전 1시 전까지 입금되어야 합니다. - dueDate number
입금 기한을 특정 시점으로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고,
dueDate
를2022-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)로 문의해주세요.
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": "가상계좌"
}
가상계좌 결제는 발급된 계좌에 고객이 입금한 시점에 결제가 됩니다. 직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 등록된 웹훅 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
로 돌아옵니다.
가상계좌 결제는 환불할 결제수단이 등록되어 있지 않습니다. 따라서 결제 취소 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": ""
}