# 결제상태기준 복수조회 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 %}