# 결제 복수조회(주문UQ) API

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

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

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

### 주문번호 기준으로 결제내역을 조회합니다. 주문번호 유일성이 유지됩니다.(정렬조건에 따라 최우선 조회건 기준)

## 주문번호 유일성이 유지되면서 결제내역을 조회할수 있습니다. 

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

정렬조건에 따라 최우선으로 검색되는 거래가 반환됩니다.

payment\_status를 추가로 지정하시면, 해당 status에 해당하는 가장 최신 데이터를 반환합니다.

#### Path Parameters

| Name                                            | Type   | Description                                                                                                                                                      |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| merchant\_uid<mark style="color:red;">\*</mark> | String | <mark style="color:red;">**주문번호**</mark>                                                                                                                         |
| payment\_status                                 | String | <p><strong>거래상태 구분코드</strong></p><p><code>ready(미결제)</code></p><p><code>paid(결제완료)</code></p><p><code>failed(결제실패)</code></p><p><code>cancelled(환불취소)</code></p> |

#### Query Parameters

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| sorting | String | 정렬구분코드      |

{% tabs %}
{% tab title="200: OK 성공" %}
{% tabs %}
{% tab title="PaymentResponse" %}
**`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;">**(PaymentAnnotation, optional)**</mark>
{% 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>

**은행 표준코드**[**(링크보기)**](/docs/tip/pg-1.md)

**`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="401: Unauthorized 인증 Token이 전달되지 않았거나 유효하지 않은 경우" %}

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

{% endtab %}

{% tab title="404: Not Found 거래건이 존재하지 않는 경우" %}

```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": {
    "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/getPaymentByMerchantUid**](https://api.iamport.kr/#!/payments/getPaymentByMerchantUid)
{% 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/uq-api.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.