⌨️결제상태기준 복수조회 API

결제 상태값을 기준으로 거래내역을 조회할 수 있는 API입니다.

Deprecated

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

PortOne 개발자센터를 이용해주세요.

결제상태값으로 결제내역을 복수조회 합니다.

미결제/결제완료/결제취소/결제실패 상태 별로 검색할 수 있습니다

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

검색기간은 최대 90일까지이며 to파라미터의 기본값은 현재일자이며 from파라미터의 기본값은 to파라미터 기준으로 90일 전입니다.

from/to 파라미터가 없이 호출되면 현재 시점 기준으로 최근 90일 구간에 대한 데이터를 검색하게 됩니다.

Path Parameters

Name	Type	Description
payment_status*	String	결제상태코드 -전체 : all -미결제 : ready -결제완료 : paid -결제취소 : cancelled -결제실패 : failed

Query Parameters

Name	Type	Description
page	Integer	페이지번호 1부터 시작
limit	Integer	페이지 당 조회건수 한 번에 조회할 결제건수 (최대 1000건, 기본값 20건)
from	Integer	검색 시작 시각 기본값 : to 파라미터 기준으로 90일 전 unix timestamp.
to	Integer	검색 종료 시각 기본값 : 현재 unix timestamp
sorting	String	정렬기준 기본값은 -started

200: OK 성공

PaymentListResponse

code * integer

응답코드

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

message * string

응답메세지

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

response (PagedPaymentAnnotation, optional)

PagedPaymentAnnotation

total * integer

총 건수

previous * integer

이전 page숫자

이전 페이지가 없으면 0

next * integer

다음 page숫자

다음 페이지가 없으면 0

list (Array[PaymentAnnotation], optional)

결제 상세정보 배열(최대 20개)

PaymentAnnotation

imp_uid * string

포트원 결제 고유 UID

merchant_uid * string

주문번호

pay_method * string

결제수단 구분코드

channel * string

결제환경 구분코드

pg_provider * string

PG사 구분코드

emb_pg_provider * string

허브형결제 PG사 구분코드

pg_tid * string

pg사 거래번호

pg_id * string

PG사 MID

escrow boolean

에스크로 결제여부

apply_num string

신용카드 승인번호

bank_code string

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

bank_name string

은행 명칭

card_code string

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

card_name string

카드사명

card_quota integer

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

card_number string

마스킹 카드번호

card_type string

카드 구분코드

vbank_code string

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

vbank_name string

입금받을 가상계좌 은행명

vbank_holder string

입금받을 가상계좌 예금주

vbank_date string

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

vbank_issued_at string

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

name string

제품명

amount * integer

주문(결제)금액

cancel_amount integer

결제취소금액

currency string

통화구분코드

buyer_name string

주문자명

buyer_email string

주문자 Email주소

buyer_tel string

주문자 전화번호

buyer_addr string

주문자 주소

buyer_postcode string

주문자 우편번호

custom_data string

echo data JSON string으로 전달

user_agent string

결제를 시작한 단말기의 UserAgent

status * string

결제상태 구분코드

started_at * string

결제시작시점 (UNIX timestamp)

paid_at * string

결제완료시점 (UNIX timestamp)

failed_at * string

결제실패시점 (UNIX timestamp)

cancelled_at * string

결제취소시점 (UNIX timestamp)

fail_reason string

결제실패 사유

cancel_reason string

결제취소 사유

receipt_url string

신용카드 매출전표 확인 URL

cash_receipt_issued boolean

현금영수증 자동발급 여부

customer_uid string

해당 결제처리에 사용된 customer_uid

customer_uid_usage string

customer_uid 사용 구분코드

cancel_history (Array[PaymentCancelAnnotation], optional):

취소/부분취소 내역

PaymentCancelAnnotation

cancel_history array []

pg_tid * string

PG사 승인취소번호

amount * integer

취소 금액

cancelled_at * string

결제취소된 시각 (UNIX timestamp)

reason * string

결제취소 사유

receipt_url * string

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

400: Bad Request 유효하지 않은 payment_status인 경우, 데이터 범위를 넘어선 page인 경우

{
    // Response
}

401: Unauthorized 인증 Token이 전달되지 않았거나 유효하지 않은 경우

{
    // Response
}

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

sorting String

정렬기준 구분코드

마이너스(-) 기호가 앞에 붙으면 내림차순 정렬을 의미합니다.

• -started : 결제시작시각(결제창오픈시각) 기준 내림차순(DESC) 정렬

• started : 결제시작시각(결제창오픈시각) 기준 오름차순(ASC) 정렬

• -paid : 결제완료시각 기준 내림차순(DESC) 정렬

• paid : 결제완료시각 기준 오름차순(ASC) 정렬

• -updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 내림차순(DESC) 정렬

• updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 오름차순(ASC) 정렬

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

Swagger Test Link

https://api.iamport.kr/#!/payments/getPaymentsByStatus