Developers
V1
V2

Get payments by status API

Gets details of payments by payment status.

GET https://api.iamport.kr/payments/status/{payment_status}

Gets details of payments by payment status.

The search period is up to 90 days. The default value of the to parameter is the current date, and that of the from parameter is 90 days before the to parameter.

If from/to parameters are not specified, this returns the data for the last 90 days from the current time.

Parameters

Path

payment_status*
String
Payment status code

all
ready
paid
cancelled
failed

Query

page
Integer

Page number

Starts from 1

limit
Integer

Search results per page

Up to 1000, default: 20

from
Integer

Search start time

Default: 90 days before to parameter (UNIX timestamp)

to
Integer

Search end time

Default: current time (UNIX timestamp)

sorting
String

Sort by

Default: started (Refer to description below)

Responses

200: OK
Success

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)

total`` * integer

Total search results

previous * integer

Previous page number

If none, 0

next * integer

Next page number

If none, 0

**list ** (Array[PaymentAnnotation], optional)

Array of payment records (up to 20)

imp_uid * string

iโ€™mport payment transaction UID

merchant_uid * string

Order ID

pay_method * string

Payment method code

channel * string

Payment environment code

  • pc**:** (authenticated) PC
  • mobile: (authenticated) mobile
  • api: recurring or non-authenticated

pg_provider * string

PG code


emb_pg_provider * string

Hub-type PG code

pg_tid * string

PG transaction ID

pg_id * string

PG MID

escrow boolean

Indicates an escrow payment

apply_num string

Credit card approval number

bank_code string

Bank code

bank_name string

Bank name


card_code string

Credit card code (KFTC Credit Card Codes: link )

card_name string

Credit card name

card_quota integer

Number of installments (0 means one-off)

card_number string

Masked credit card number


card_type string

Credit card type code

  • 0: credit
  • 1: check

vbank_code string

Virtual account bank code (refer to image below)


vbank_name string

Refund virtual account

vbank_holder string

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

Product name

amount * integer

Order (payment) amount

cancel_amount integer

Cancelled amount

currency string

Currency

  • USD
  • KRW
  • EUR

buyer_name string

Customer name

buyer_email string

Customer email\

buyer_tel string

Customer phone

buyer_addr string

Customer address

buyer_postcode string

Customer zip code

custom_data string

echo data as JSON string

user_agent string

UserAgent of the device where payment is initiated

status * string

Payment status code

  • ready
  • paid
  • cancelled
  • failed

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

Reason for failure

cancel_reason string

Reason for cancellation

receipt_url string

Credit card receipt URL

**cash_receipt_issued ** boolean

Option to automatically issue cash receipt

customer_uid string

customer_uid related to the payment transaction

customer_uid_usage string

customer_uid use code

  • payment.scheduled: scheduled payment
  • payment: payment
  • issue**: billing key issuance**

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.

400: Bad Request
Invalid payment_status or page out of data range
{
    // Response
}
401: Unauthorized
Missing or invalid access token
{
    // Response
}

Key request parameter description

sorting String

Sort by code

A minus (-) indicates a descending sort order.

  • -started : Sort in descending order (DESC) based on payment start time (payment window open time)
  • started : Sort in ascending order (ASC) based on payment start time (payment window open time)
  • -paid : Sort in descending order (DESC) based on payment completion time
  • paid: Sort in ascending order (ASC) based on payment completion time
  • -updated : Sort in descending order (DESC) based on the last modification time (the modification time is changed whenever payment status changes)
  • updated : Sort in ascending order (ASC) based on the last modification time (the modification time is changed whenever payment status changes)

Response Model Schema

{
  "code": 0,
  "message": "string",
  "response": {
    "total": 0,
    "previous": 0,
    "next": 0,
    "list": [
      {
        "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"
      }
    ]
  }
}