Developers
V1
V2
API & SDK

Cancel payment API

Cancels a payment in full or partially regardless of the payment method and PG.

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

Cancels an approved payment.

Credit card/instant account transfer/mobile micropayment: cancellation is processed immediately.

Virtual account: if you provide the refund account information, the refund information will be registered with PG and processed on the next business day. (Requires virtual account special service contract)

Parameters

Body

imp_uid*
String(32)

ChaiPort transaction ID

merchant_uid
String(40)

Order ID (Required if imp_uid is null)

amount
Double

Amount to refund (

Full refund if null

)

tax_free
Double

Tax free amount out of

amount

(

0 if null

)

checksum
Double

Refundable amount

reason
String(256)

Reason for cancellation

refund_holder
String(16)

Refund account holder

(Required for

virtual account

cancellation)

refund_bank
String(4)

Refund account bank code (Refer to bank codes list below, required for

virtual account

cancellation)

refund_account
String(16)

Refund account number (Required for

virtual account

cancellation)

refund_tel
String(16)

Refund account holder’s phone number (Required for

virtual account

cancellation and

Smartro PG

)

Responses

200: OK
Cancellation successful

code * integer

Response code

0: success,
Not 0: check the message

message * string

Response message

A non-zero code includes a message like ‘Invalid payment info.

response (PagedPaymentAnnotation, optional)

imp_uid * string(32)

i’mport payment transaction UID

merchant_uid * string(40)

Order ID

pay_method * string(20)

Payment method code

channel * string(10)

Payment environment code

[‘pc’, ‘mobile’, ‘api’]

pg_provider * string(16)

PG code

emb_pg_provider * string(16)

Hub-type PG code

pg_tid * string(80)

PG transaction ID

pg_id * string(80)

PG MID

escrow boolean

Indicates an escrow payment

apply_num string(20)

Credit card approval number

bank_code string(4)

Bank code

bank_name string(20)

Bank name

card_code string(3)

Credit card code (KFTC Credit Card Codes: link )

card_name string(20)

Credit card name

card_quota integer

Number of installments (0 means one-off)

card_number string(20)

Masked credit card number

card_type string(2)

Card type code

vbank_code string(4)

Virtual account bank code (refer to image below)

vbank_name string(20)

Refund virtual account

vbank_holder string(16)

Refund virtual account holder

vbank_date string

Refund virtual account expiration (UNIX timestamp)

vbank_issued_at string

Refund virtual account created at (UNIX timestamp)

name string(40)

Product name

amount * integer

Order (payment) amount

cancel_amount integer

Cancelled amount

currency string(3)

Currency

buyer_name string(16)

Customer name

buyer_email string(64)

Customer email\

buyer_tel string(16)

Customer phone

buyer_addr string(128)

Customer address

buyer_postcode string(8)

Customer zip code

custom_data string

echo data as JSON string

user_agent string(256)

UserAgent of the device where payment is initiated

status * string(20)

Payment status code

started_at * string

Payment started at (UNIX timestamp)

paid_at * string

Payment completed at (UNIX timestamp)\

failed_at * string

Payment failed at (UNIX timestamp)

cancelled_at * string

Payment cancelled at (UNIX timestamp)

fail_reason string(256)

Reason for failure

cancel_reason string(256)

Reason for cancellation

receipt_url string(300)

Credit card receipt URL

cash_receipt_issued boolean

Option to automatically issue cash receipt

customer_uid string(80)

customer_uid related to the payment transaction

customer_uid_usage string(20)

customer_uid use code

[‘issue’, ‘payment’, ‘payment.scheduled’]

cancel_history (Array[PaymentCancelAnnotation], optional):

Cancellation/partial cancellation history

cancel_history array []

pg_tid * string

PG cancellation transaction ID

amount * integer

Cancelled amount

cancelled_at * string

Cancelled at (UNIX timestamp)

reason * string(256)

Reason for cancellation

receipt_url * string(300)

Cancellation receipt URL. Availability varies by PG.
401: Unauthorized
Missing or invalid access token

Key parameters

imp_uid & merchant_uid

At least one of these parameters must be specified.

checksum integer

Refundable amount

The checksum is used to check whether the refundable amount is the same between the API requester and the i’mport server. If they do not match, the refund request will fail. If the checksum is null, the verification is not performed.\

amount * integer

Amount to cancel

If not specified, a full refund is requested.

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"
  }
}