결제취소 API

모든 결제내역을 취소할 수 있는 API 를 안내합니다.

Previous결제관련 API Next결제내역 단건조회 API

Last updated 2 years ago

Was this helpful?

결제취소 API

모든 결제내역을 취소할 수 있는 API 를 안내합니다.

Deprecated

이 문서는 더 이상 관리되지 않습니다.

를 이용해주세요.

결제수단 및 PG사와 상관없이 취소 및 부분취소가 가능합니다.

승인된 결제를 취소합니다.

POST https://api.iamport.kr/payments/cancel

신용카드/실시간계좌이체/휴대폰 소액결제의 경우 즉시 취소처리가 이뤄지게 되며 가상계좌의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다.

(가상계좌 환불관련 특약계약 필요)

Request Body

Name

Type

Description

imp_uid*

String(32)

포트원 거래고유번호

merchant_uid

String(40)

주문번호 (imp_uid 누락시 필수)

amount

Double

취소 요청금액

(

누락시 전액취소

)

tax_free

Double

취소요청금액 중 면세금액 (

누락되면 0원처리

)

vat_amount

integer

부가세 지정(기본값: null)

결제 시 부가세를 지정했던 경우 필수 입력 바랍니다.

지원 PG사

-나이스페이먼츠

-이니시스

refund_tel

String(16)

환불계좌 예금주 연락처(

가상계좌

취소,

스마트로 PG사 인경우 필수

)

checksum

Double

현재시점의 취소 가능한 잔액.

reason

String(256)

취소사유

refund_holder

String(16)

환불계좌 예금주

(

가상계좌

취소시 필수)

refund_bank

String(4)

환불계좌 은행코드 (하단 은행코드표 참조,

가상계좌 취소 시

필수)

refund_account

String(16)

환불계좌 계좌번호 (

가상계좌 취소

시 필수)

extra

Object

추가 파라미터

code integer

응답코드

0이면 정상적인 조회, 0이 아닌 값이면 message를 확인해봐야 합니다

message string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

response (PagedPaymentAnnotation, optional)

imp_uid * string(32)

포트원 결제 고유 UID

merchant_uid string(40)

주문번호

pay_method string(20)

결제수단 구분코드

channel string(10)

결제환경 구분코드

['pc', 'mobile', 'api']

pg_provider string(16)

PG사 구분코드

emb_pg_provider string(16)

허브형결제 PG사 구분코드

pg_tid string(80)

pg사 거래번호

pg_id string(80)

PG사 MID

escrow boolean

에스크로 결제여부

apply_num string(20)

신용카드 승인번호

bank_code string(4)

은행 표준코드(링크보기)

bank_name string(20)

은행 명칭

card_code string(3)

card_name string(20)

카드사명

card_quota integer

할부개월 수(0이면 일시불)

card_number string(20)

마스킹 카드번호

card_type string(2)

카드 구분코드

vbank_code string(4)

가상계좌 은행 표준코드(하단이미지 참고)

vbank_name string(20)

입금받을 가상계좌 은행명

vbank_holder string(16)

입금받을 가상계좌 예금주

vbank_date string

입금받을 가상계좌 마감기한 (UNIX timestamp)

vbank_issued_at string

가상계좌 생성 시각 (UNIX timestamp)

name string(40)

제품명

amount integer

주문(결제)금액

cancel_amount integer

결제취소금액

currency string(3)

통화구분코드

buyer_name string(16)

주문자명

buyer_email string(64)

주문자 Email주소\

buyer_tel string(16)

주문자 전화번호

buyer_addr string(128)

주문자 주소

buyer_postcode string(8)

주문자 우편번호

custom_data string

echo data JSON string으로 전달

user_agent string(256)

결제를 시작한 단말기의 UserAgent

status string(20)

결제상태 구분코드

started_at string

결제시작시점 (UNIX timestamp)

paid_at string

결제완료시점 (UNIX timestamp)\

failed_at string

결제실패시점 (UNIX timestamp)

cancelled_at string

결제취소시점 (UNIX timestamp)

fail_reason string(256)

결제실패 사유

cancel_reason string(256)

결제취소 사유

receipt_url string(300)

신용카드 매출전표 확인 URL

cash_receipt_issued boolean

현금영수증 자동발급 여부

customer_uid string(80)

해당 결제처리에 사용된 customer_uid

customer_uid_usage string(20)

customer_uid 사용 구분코드

['issue', 'payment', 'payment.scheduled']

cancel_history (Array[PaymentCancelAnnotation], optional):

취소/부분취소 내역

cancel_history array []

pg_tid string

PG사 승인취소번호

amount integer

취소 금액

cancelled_at string

결제취소된 시각 UNIX timestamp

reason * string(256)

결제취소 사유

receipt_url * string(300)

취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음

주요 요청 파라미터 상세 설명

imp_uid & merchant_uid
취소 요청시 두 파라미터중 하나는 필수로 유입되어야 합니다.

checksum integer
승인 잔액
API요청자가 기록하고 있는 취소가능 잔액과 포트원에서 기록하고 있는 취소가능 잔액이 일치하는지 사전에 검증하고 검증에 실패하면 트랜잭션을 수행하지 않습니다. null인 경우에는 검증 프로세스를 생략합니다.

amount integer
취소금액
누락시 전액취소 됩니다.

extra object
추가 파라미터.
네이버페이 사용시 extra.requester를 설정해야 합니다.
customer: 구매자에 의한 요청
admin: (기본값) 관리자에 의한 요청
예시) { "extra": { "requester": "customer" } }

Response Model Schema

{
  "code": 0,
  "message": "string",
  "response": {
    "imp_uid": "string",
    "merchant_uid": "string",
    "pay_method": "string",
    "channel": "pc",
    "pg_provider": "string",
    "emb_pg_provider": "string",
    "pg_tid": "string",
    "pg_id": "string",
    "escrow": true,
    "apply_num": "string",
    "bank_code": "string",
    "bank_name": "string",
    "card_code": "string",
    "card_name": "string",
    "card_quota": 0,
    "card_number": "string",
    "card_type": "null",
    "vbank_code": "string",
    "vbank_name": "string",
    "vbank_num": "string",
    "vbank_holder": "string",
    "vbank_date": 0,
    "vbank_issued_at": 0,
    "name": "string",
    "amount": 0,
    "cancel_amount": 0,
    "currency": "string",
    "buyer_name": "string",
    "buyer_email": "string",
    "buyer_tel": "string",
    "buyer_addr": "string",
    "buyer_postcode": "string",
    "custom_data": "string",
    "user_agent": "string",
    "status": "ready",
    "started_at": 0,
    "paid_at": 0,
    "failed_at": 0,
    "cancelled_at": 0,
    "fail_reason": "string",
    "cancel_reason": "string",
    "receipt_url": "string",
    "cancel_history": [
      {
        "pg_tid": "string",
        "amount": 0,
        "cancelled_at": 0,
        "reason": "string",
        "receipt_url": "string"
      }
    ],
    "cancel_receipt_urls": [
      "string"
    ],
    "cash_receipt_issued": true,
    "customer_uid": "string",
    "customer_uid_usage": "issue"
  }
}

Swagger Test Link

Previous결제관련 API Next결제내역 단건조회 API

Last updated 2 years ago

Was this helpful?

Deprecated

이 문서는 더 이상 관리되지 않습니다.

를 이용해주세요.

결제수단 및 PG사와 상관없이 취소 및 부분취소가 가능합니다.

승인된 결제를 취소합니다.

POST https://api.iamport.kr/payments/cancel

(가상계좌 환불관련 특약계약 필요)

Request Body

Name

Type

Description

imp_uid*

String(32)

포트원 거래고유번호

merchant_uid

String(40)

주문번호 (imp_uid 누락시 필수)

amount

Double

취소 요청금액

(

누락시 전액취소

)

tax_free

Double

취소요청금액 중 면세금액 (

누락되면 0원처리

)

vat_amount

integer

부가세 지정(기본값: null)

결제 시 부가세를 지정했던 경우 필수 입력 바랍니다.

지원 PG사

-나이스페이먼츠

-이니시스

refund_tel

String(16)

환불계좌 예금주 연락처(

가상계좌

취소,

스마트로 PG사 인경우 필수

)

checksum

Double

현재시점의 취소 가능한 잔액.

reason

String(256)

취소사유

refund_holder

String(16)

환불계좌 예금주

(

가상계좌

취소시 필수)

refund_bank

String(4)

환불계좌 은행코드 (하단 은행코드표 참조,

가상계좌 취소 시

필수)

refund_account

String(16)

환불계좌 계좌번호 (

가상계좌 취소

시 필수)

extra

Object

추가 파라미터

code integer

응답코드

0이면 정상적인 조회, 0이 아닌 값이면 message를 확인해봐야 합니다

message string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

response (PagedPaymentAnnotation, optional)

imp_uid * string(32)

포트원 결제 고유 UID

merchant_uid string(40)

주문번호

pay_method string(20)

결제수단 구분코드

channel string(10)

결제환경 구분코드

['pc', 'mobile', 'api']

pg_provider string(16)

PG사 구분코드

emb_pg_provider string(16)

허브형결제 PG사 구분코드

pg_tid string(80)

pg사 거래번호

pg_id string(80)

PG사 MID

escrow boolean

에스크로 결제여부

apply_num string(20)

신용카드 승인번호

bank_code string(4)

은행 표준코드(링크보기)

bank_name string(20)

은행 명칭

card_code string(3)

카드사 코드번호(금융결제원 표준코드번호: )

card_name string(20)

카드사명

card_quota integer

할부개월 수(0이면 일시불)

card_number string(20)

마스킹 카드번호

card_type string(2)

카드 구분코드

vbank_code string(4)

가상계좌 은행 표준코드(하단이미지 참고)

vbank_name string(20)

입금받을 가상계좌 은행명

vbank_holder string(16)

입금받을 가상계좌 예금주

vbank_date string

입금받을 가상계좌 마감기한 (UNIX timestamp)

vbank_issued_at string

가상계좌 생성 시각 (UNIX timestamp)

name string(40)

제품명

amount integer

주문(결제)금액

cancel_amount integer

결제취소금액

currency string(3)

통화구분코드

buyer_name string(16)

주문자명

buyer_email string(64)

주문자 Email주소\

buyer_tel string(16)

주문자 전화번호

buyer_addr string(128)

주문자 주소

buyer_postcode string(8)

주문자 우편번호

custom_data string

echo data JSON string으로 전달

user_agent string(256)

결제를 시작한 단말기의 UserAgent

status string(20)

결제상태 구분코드

started_at string

결제시작시점 (UNIX timestamp)

paid_at string

결제완료시점 (UNIX timestamp)\

failed_at string

결제실패시점 (UNIX timestamp)

cancelled_at string

결제취소시점 (UNIX timestamp)

fail_reason string(256)

결제실패 사유

cancel_reason string(256)

결제취소 사유

receipt_url string(300)

신용카드 매출전표 확인 URL

cash_receipt_issued boolean

현금영수증 자동발급 여부

customer_uid string(80)

해당 결제처리에 사용된 customer_uid

customer_uid_usage string(20)

customer_uid 사용 구분코드

['issue', 'payment', 'payment.scheduled']

cancel_history (Array[PaymentCancelAnnotation], optional):

취소/부분취소 내역

cancel_history array []

pg_tid string

PG사 승인취소번호

amount integer

취소 금액

cancelled_at string

결제취소된 시각 UNIX timestamp

reason * string(256)

결제취소 사유

receipt_url * string(300)

취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음

주요 요청 파라미터 상세 설명

imp_uid & merchant_uid
취소 요청시 두 파라미터중 하나는 필수로 유입되어야 합니다.

checksum integer
승인 잔액
API요청자가 기록하고 있는 취소가능 잔액과 포트원에서 기록하고 있는 취소가능 잔액이 일치하는지 사전에 검증하고 검증에 실패하면 트랜잭션을 수행하지 않습니다. null인 경우에는 검증 프로세스를 생략합니다.

amount integer
취소금액
누락시 전액취소 됩니다.

extra object
추가 파라미터.
네이버페이 사용시 extra.requester를 설정해야 합니다.
customer: 구매자에 의한 요청
admin: (기본값) 관리자에 의한 요청
예시) { "extra": { "requester": "customer" } }

Response Model Schema

{
  "code": 0,
  "message": "string",
  "response": {
    "imp_uid": "string",
    "merchant_uid": "string",
    "pay_method": "string",
    "channel": "pc",
    "pg_provider": "string",
    "emb_pg_provider": "string",
    "pg_tid": "string",
    "pg_id": "string",
    "escrow": true,
    "apply_num": "string",
    "bank_code": "string",
    "bank_name": "string",
    "card_code": "string",
    "card_name": "string",
    "card_quota": 0,
    "card_number": "string",
    "card_type": "null",
    "vbank_code": "string",
    "vbank_name": "string",
    "vbank_num": "string",
    "vbank_holder": "string",
    "vbank_date": 0,
    "vbank_issued_at": 0,
    "name": "string",
    "amount": 0,
    "cancel_amount": 0,
    "currency": "string",
    "buyer_name": "string",
    "buyer_email": "string",
    "buyer_tel": "string",
    "buyer_addr": "string",
    "buyer_postcode": "string",
    "custom_data": "string",
    "user_agent": "string",
    "status": "ready",
    "started_at": 0,
    "paid_at": 0,
    "failed_at": 0,
    "cancelled_at": 0,
    "fail_reason": "string",
    "cancel_reason": "string",
    "receipt_url": "string",
    "cancel_history": [
      {
        "pg_tid": "string",
        "amount": 0,
        "cancelled_at": 0,
        "reason": "string",
        "receipt_url": "string"
      }
    ],
    "cancel_receipt_urls": [
      "string"
    ],
    "cash_receipt_issued": true,
    "customer_uid": "string",
    "customer_uid_usage": "issue"
  }
}

Swagger Test Link