승인된 결제를 취소하려면 토스페이먼츠 결제 취소 API를 호출하세요. 결제 금액 전액 또는 일부를 고객에게 환불할 수 있습니다.
승인된 결제를 취소하려면 결제 키와 결제를 취소하는 이유를 결제 취소 API 파라미터로 추가해서 호출합니다.
- API 엔드포인트에 결제 승인 API 요청 결과로 받은
paymentKey
를 Path 파라미터로 추가하세요. - 취소 이유를
cancelReason
파라미터로 요청 본문에 추가하세요. - 응답의
cancels
필드를 확인하세요. 결제 취소 정보 객체가 배열 안에 돌아옵니다.
요청
curl --request POST \
--url https://api.tosspayments.com/v1/payments/Jh4TJ_5ClbFvBsS88CJnJ/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"고객이 취소를 원함"}'
응답
{
"mId": "tosspayments",
"version": "2022-11-16",
"lastTransactionKey": "",
"paymentKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "CANCELED",
"requestedAt": "2022-01-01T11:31:29+09:00",
"approvedAt": "2022-01-01T11:31:51+09:00",
"useEscrow": false,
"cultureExpense": false,
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"card": {
"issuerCode": "33",
"acquirerCode": "31",
"number": "12341234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": [
{
"cancelReason": "고객이 취소를 원함",
"canceledAt": "2022-01-01T11:32:04+09:00",
"cancelAmount": 10000,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"refundableAmount": 0,
"easyPayDiscountAmount": 0,
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"receiptKey": "V4AJ6AhSWsGN0RocizZQlagPLN8s2IahJLXpfSHzQBTKoDG7"
}
],
"secret": null,
"type": "NORMAL",
"easyPay": "토스페이",
"country": "KR",
"failure": null,
"totalAmount": 10000,
"balanceAmount": 0,
"suppliedAmount": 0,
"vat": 0,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}
JSON
멱등키를 요청 헤더에 추가하면 중복 취소 없이 안전하게 처리됩니다.
결제 금액 중 일부만 취소하려면 cancelAmount
에 취소할 금액을 추가해서 결제 취소 API를 요청합니다. cancelAmount
에 값을 넣지 않으면 전액 취소됩니다.
요청
curl --request POST \
--url https://api.tosspayments.com/v1/payments/YyHE_AbrRxUTIsSscXKrv/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"고객이 취소를 원함","cancelAmount":1000}'
부분 취소를 여러 번 하면 아래와 같이 cancels
필드에 취소 객체가 여러 개 돌아옵니다.
응답
// Payment 객체
{
// ...
"cancels": [
{
"cancelAmount": 1000,
"cancelReason": "고객이 취소를 원함",
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"refundableAmount": 9000,
"easyPayDiscountAmount": 0,
"canceledAt": "2022-01-01T23:23:52+09:00",
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"receiptKey": "CuskOnzZEf0Xbwo8eMZ56slTAXbJ8jUjTX3n6SNuvY5d7Fpf"
},
{
"cancelAmount": 1000,
"cancelReason": "고객이 다른 품목도 취소를 원함",
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"refundableAmount": 8000,
"easyPayDiscountAmount": 0,
"canceledAt": "2022-01-02T20:00:00+09:00",
"transactionKey": "6673C15BF350C3F9BF45CEFC48C7A24E",
"receiptKey": "PLDm1CZSQxTBvYrHytz3yt3MU09Nx57IoCxIEJ8HPzOyIRos"
}
]
// ...
}
JSON
가상계좌 결제를 취소할 때는 환불받을 고객의 계좌 정보를 결제 취소 API 요청에 포함해야 합니다.
refundReceiveAccount
에 환불받을 고객의 계좌 정보를 포함해서 결제 취소를 요청하세요. 요청한 계좌로 취소 금액이 환불됩니다.
요청
curl --request POST \
--url https://api.tosspayments.com/v1/payments/82NATpQ1S3_o-OnsxHG0p/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"고객이 취소를 원함","cancelAmount":10000,"refundReceiveAccount":{"bank":"20","accountNumber":"1000123456789","holderName":"김토페"}}'
응답은 다른 취소 요청과 동일하게 Payment 객체의 cancels
로 돌아옵니다.
응답
{
"mId": "tvivarepublica",
"version": "2022-11-16",
"lastTransactionKey": "",
"paymentKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "가상계좌",
"status": "PARTIAL_CANCELED",
"requestedAt": "2022-01-01T11:48:53+09:00",
"approvedAt": "2022-01-01T11:49:35+09:00",
"useEscrow": false,
"cultureExpense": false,
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"card": null,
"virtualAccount": {
"accountNumber": "X6505831718354",
"accountType": "일반",
"bankCode": "20",
"customerName": "김토스",
"dueDate": "2022-01-03T11:48:53+09:00",
"expired": true,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE",
"refundReceiveAccount": null
},
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": [
{
"cancelReason": "고객 변심",
"canceledAt": "2022-01-01T11:51:04+09:00",
"cancelAmount": 10000,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"refundableAmount": 0,
"easyPayDiscountAmount": 0,
"transactionKey": "ND38Q0IGWUG7UC02G6G1GL1XJRG2BO5N",
"receiptKey": "aIHE2heVz6hwRIWsu0msyxjF6xhPtn9T44fij4BF9bNUN64G"
}
],
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 10000,
"balanceAmount": 0,
"suppliedAmount": 0,
"vat": 0,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}
JSON
상점관리자에서 환불 계좌 입력 > 필수 입력을 선택했다면 고객이 환불 계좌 정보를 위젯에 입력합니다.
환불 계좌 정보는 결제 승인 뒤에 받은 Payment 객체의 virtualAccount.refundReceiveAccount
필드로 확인하세요. 결제창을 띄운 시점부터 30분 동안 결제 조회 API로도 확인할 수 있습니다.
환불 계좌 정보를 저장해놓고 가상계좌 결제 취소에 사용하세요.
응답
{
// Payment 객체
// ...
"virtualAccount": {
"accountNumber": "X6505636518308",
"accountType": "일반",
"bankCode": "20",
"customerName": "박토스",
"dueDate": "2022-01-10T21:05:09+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE",
"refundReceiveAccount": {
"bankCode": "20",
"accountNumber": "001012341342",
"holderName": "박토스"
}
},
// ...
}
JSON