# 결제상태기준 복수조회 API

{% hint style="warning" %}
**Deprecated**

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

[PortOne 개발자센터](https://developers.portone.io/)를 이용해주세요.
{% endhint %}

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

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

<mark style="color:blue;">`GET`</mark> `https://api.iamport.kr/payments/status/{payment_status}`

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

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

#### Path Parameters

| Name                                              | Type   | Description                                                                                                                                                                                                                                |
| ------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| payment\_status<mark style="color:red;">\*</mark> | String | <p><mark style="color:red;"><strong>결제상태코드</strong></mark></p><p><strong>-전체 : all</strong><br>-<strong>미결제 : ready</strong><br>-<strong>결제완료 : paid</strong><br>-<strong>결제취소 : cancelled</strong><br>-<strong>결제실패 : failed</strong></p> |

#### Query Parameters

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

{% tabs %}
{% tab title="200: OK 성공" %}
{% tabs %}
{% tab title="PaymentListResponse" %}
**`code`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**응답코드**

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

**`message`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**응답메세지**

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

**`response`** <mark style="color:red;">**(PagedPaymentAnnotation, optional)**</mark>
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PagedPaymentAnnotation" %}
**`total`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**`integer`**</mark>

**`총 건수`**

**`previous`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**`integer`**</mark>

**`이전 page숫자`**

이전 페이지가 없으면 0

**`next`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**`integer`**</mark>

**`다음 page숫자`**

다음 페이지가 없으면 0

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

결제 상세정보 배열(최대 20개)
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PaymentAnnotation" %}
**`imp_uid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**포트원 결제 고유 UID**

**`merchant_uid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**주문번호**

**`pay_method`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제수단 구분코드**

**`channel`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제환경 구분코드**

**`pg_provider`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**PG사 구분코드**

**`emb_pg_provider`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**허브형결제 PG사 구분코드**

**`pg_tid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**pg사 거래번호**

**`pg_id`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**PG사 MID**

**`escrow`** <mark style="color:orange;">**boolean**</mark>

**에스크로 결제여부**

**`apply_num`** <mark style="color:green;">**string**</mark>

**신용카드 승인번호**

**`bank_code`** <mark style="color:green;">**string**</mark>

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

**`bank_name`** <mark style="color:green;">**string**</mark>

**은행 명칭**

**`card_code`** <mark style="color:green;">**string**</mark>

**카드사 코드번호(금융결제원 표준코드번호 :** [<mark style="color:red;">**링크**</mark>](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) )

**`card_name`** <mark style="color:green;">**string**</mark>

**카드사명**

**`card_quota`** <mark style="color:purple;">**integer**</mark>

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

**`card_number`** <mark style="color:green;">**string**</mark>

**마스킹 카드번호**

**`card_type`** <mark style="color:green;">**string**</mark>

**카드 구분코드**

**`vbank_code`** <mark style="color:green;">**string**</mark>

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

**`vbank_name`** <mark style="color:green;">**string**</mark>

**입금받을 가상계좌 은행명**

**`vbank_holder`** <mark style="color:green;">**string**</mark>

**입금받을 가상계좌 예금주**

**`vbank_date`** <mark style="color:green;">**string**</mark>

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

**`vbank_issued_at`** <mark style="color:green;">**string**</mark>

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

**`name`** <mark style="color:green;">**string**</mark>

**제품명**

**`amount`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**주문(결제)금액**

**`cancel_amount`** <mark style="color:purple;">**integer**</mark>

**결제취소금액**

**`currency`** <mark style="color:green;">**string**</mark>

**통화구분코드**

**`buyer_name`** <mark style="color:green;">**string**</mark>

**주문자명**

**`buyer_email`** <mark style="color:green;">**string**</mark>

**주문자 Email주소**

**`buyer_tel`** <mark style="color:green;">**string**</mark>

**주문자 전화번호**

**`buyer_addr`** <mark style="color:green;">**string**</mark>

**주문자 주소**

**`buyer_postcode`** <mark style="color:green;">**string**</mark>

**주문자 우편번호**

**`custom_data`** <mark style="color:green;">**string**</mark>

**echo data JSON string으로 전달**

**`user_agent`** <mark style="color:green;">**string**</mark>

**결제를 시작한 단말기의 UserAgent**

**`status`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제상태 구분코드**

**`started_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제시작시점 (UNIX timestamp)**

**`paid_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제완료시점 (UNIX timestamp)**

**`failed_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제실패시점 (UNIX timestamp)**

**`cancelled_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제취소시점 (UNIX timestamp)**

**`fail_reason`** <mark style="color:green;">**string**</mark>

**결제실패 사유**

**`cancel_reason`** <mark style="color:green;">**string**</mark>

**결제취소 사유**

**`receipt_url`** <mark style="color:green;">**string**</mark>

**신용카드 매출전표 확인 URL**

**`cash_receipt_issued`** <mark style="color:orange;">**boolean**</mark>

**현금영수증 자동발급 여부**

**`customer_uid`** <mark style="color:green;">**string**</mark>

**해당 결제처리에 사용된 customer\_uid**

**`customer_uid_usage`** <mark style="color:green;">**string**</mark>

**customer\_uid 사용 구분코드**

**`cancel_history`** <mark style="color:red;">**(Array\[PaymentCancelAnnotation], optional):**</mark>

**`취소/부분취소 내역`**
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PaymentCancelAnnotation" %}
**cancel\_history array \[]**

**`pg_tid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**PG사 승인취소번호**

**`amount`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**취소 금액**

**`cancelled_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제취소된 시각 (UNIX timestamp)**

**`reason`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제취소 사유**

**`receipt_url`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

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

{% tab title="400: Bad Request 유효하지 않은 payment\_status인 경우, 데이터 범위를 넘어선 page인 경우" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized 인증 Token이 전달되지 않았거나 유효하지 않은 경우" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

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

> **`sorting`** <mark style="color:green;">**String**</mark>
>
> **`정렬기준 구분코드`**
>
> 마이너스(-) 기호가 앞에 붙으면 내림차순 정렬을 의미합니다.
>
> * -started : 결제시작시각(결제창오픈시각) 기준 내림차순(DESC) 정렬
> * started : 결제시작시각(결제창오픈시각) 기준 오름차순(ASC) 정렬
> * -paid : 결제완료시각 기준 내림차순(DESC) 정렬
> * paid : 결제완료시각 기준 오름차순(ASC) 정렬
> * -updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 내림차순(DESC) 정렬
> * updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 오름차순(ASC) 정렬

<details>

<summary>Response Model Schema</summary>

```json
{
  "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"
      }
    ]
  }
}
```

</details>

{% hint style="success" %}
**Swagger Test Link**

[**https://api.iamport.kr/#!/payments/getPaymentsByStatus**](https://api.iamport.kr/#!/payments/getPaymentsByStatus)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://portone.gitbook.io/docs/api/api-1/api-3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.