가상계좌 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":"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)로 문의해주세요.
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": "가상계좌"
}
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": ""
}