결제를 취소하고 고객에게 환불하기

승인된 결제를 취소하려면 토스페이먼츠 결제 취소 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

Case 1. 가상계좌 환불하는 방법

가상계좌 결제를 취소할 때는 환불받을 고객의 계좌 정보를 결제 취소 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

Case 2. 결제위젯 환불 계좌 확인하는 방법

상점관리자에서 환불 계좌 입력 > 필수 입력을 선택했다면 고객이 환불 계좌 정보를 위젯에 입력합니다.

환불 계좌 정보는 결제 승인 뒤에 받은 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