개발자센터
V1
V2
파트너 정산 릴리즈 노트 기술 블로그

PortOne REST API - V1

결제완료된 정보, 결제취소, 상태별 결제목록 조회 등의 기능을 하는 REST API를 제공합니다.
비인증 결제, 정기 자동결제 등 부가기능을 위한 REST API도 제공합니다.

V1 API hostname: api.iamport.kr


인증 관련 API

포트원 API를 호출할 때는 액세스 토큰Authorization 헤더에 넣어주어야 합니다.
액세스 토큰은 access_token 발급 API post/users/getToken를 호출해서 발급받을 수 있습니다.

액세스 토큰 발급 API를 호출하려면 API 키API 시크릿을 인자로 넣어주어야 합니다.

API 키와 API 시크릿 확인하기

  1. 관리자 콘솔 상점・계정 관리 화면 접속
  2. 내 식별코드・API Keys 버튼 클릭
API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다
API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다

API 시크릿은 절대로 외부에 노출되어서는 안 되는 값입니다.
실제 구현에서 액세스 토큰 발급은 꼭 서버 사이드에서 해주세요.

액세스 토큰 발급 받기

access_token 발급 API post/users/getToken 호출

/users/getToken API를 호출해서 액세스 토큰을 발급받습니다
/users/getToken API를 호출해서 액세스 토큰을 발급받습니다

포트원 REST API 서버는 Google Public NTP의 시간과 동기화되고 있습니다.

하위 상점 연동을 할 경우 액세스 토큰을 발급받을 때 Agent 계정API 키API 시크릿을 사용해야 합니다.

Agency & Tier 란?

액세스 토큰 사용하기

발급받은 액세스 토큰은 다른 API를 호출할 때
Authorization 헤더에 Bearer <액세스 토큰> 형식의 값을 넣어주면 됩니다.

자세한 내용은 MDN - HTTP 인증 문서를 참고해주세요.

하위 상점 연동을 할 경우 포트원 API 호출시 Tier 헤더에 하위 상점 티어 코드를 입력해야 합니다.

Agency & Tier 란?

액세스 토큰 만료기한 연장

만료된 액세스 토큰으로 API를 호출하면 401 Unauthorized 응답을 받습니다.
액세스 토큰의 만료 기한은 발행시간부터 30분입니다.

  • 기존 액세스 토큰이 만료되기 전 access_token 발급 API post/users/getToken를 다시 호출했을 경우

    • 기존 액세스 토큰이 반환됩니다.
      만료 기한이 1분 안쪽으로 남았을 때 요청했다면 기존 액세스 토큰의 만료 기한이 5분 연장됩니다.
  • 기존 액세스 토큰이 만료된 다음 access_token 발급 API post/users/getToken를 다시 호출했을 경우

    • 새로운 액세스 토큰이 반환됩니다.

액세스 토큰의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 상황을 고려해서 설계되었습니다.

  • 한 고객사에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(/users/getToken)를 호출하는 상황
  • 한 고객사에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황

결제 관련 API

get/payments/{imp_uid}/balance

결제 상세내역 조회 API

포트원 거래고유번호로 결제수단별 금액 상세정보를 확인합니다.(현재, PAYCO결제수단에 한해 제공되고 있습니다. 타 PG사의 경우 파라메터 검증 등 검토/협의 단계에 있습니다.

Request

Path

imp_uid: string
포트원 거래고유번호

상세정보를 조회할 결제건의 포트원 거래고유번호

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

(Optional)
amount: number
결제금액

결제건의 총 결제금액

PaymentBalance이력
(Optional)

결제건의 Balance 이력을 반환합니다.

401

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

404

유효하지 않은 imp_uid

405

허용되지 않는 HTTP METHOD
try
Request
Request Sample
N/A
get/payments/{imp_uid}

결제내역 단건조회 API

포트원 거래고유번호로 결제내역을 확인합니다

Request

Path

imp_uid: string
포트원 거래고유번호

결제내역을 확인할 결제건의 포트원 거래고유번호

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

response?: PaymentAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호

결제건의 포트원 거래고유번호

merchant_uid: string
가맹점 주문번호

결제건의 가맹점 주문번호

pay_method?: string
결제수단 구분코드
(Optional)

결제건의 결제수단을 구분하는 코드

channel?: string
결제환경 구분코드
(Optional)

결제건을 생성한 환경을 구분하는 코드

pg_provider?: string
PG사 구분코드
(Optional)

결제건의 PG사 구분코드

emb_pg_provider?: string
허브형결제 PG사 구분코드
(Optional)

허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드

pg_tid?: string
PG사 거래번호
(Optional)

결제건의 PG사 거래번호

pg_id?: string
PG사 상점아이디
(Optional)

결제건의 PG사 상점아이디

escrow?: boolean
에스크로결제 여부
(Optional)

에스크로 결제건인지 구분하는 코드

apply_num?: string
승인번호
(Optional)

결제건의 신용카드 승인번호

bank_code?: string
은행 표준코드
(Optional)

결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우

bank_name?: string
은행명
(Optional)

결제건의 은행명 - 실시간계좌이체 결제 건의 경우

card_code?: string
카드사 코드번호
(Optional)

결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우

card_name?: string
카드사명
(Optional)

결제건의 카드사명 - 카드 결제 건의 경우

card_issuer_code?: string
카드 발급사 코드
(Optional)

결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우

발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_issuer_name?: string
카드 발급사명
(Optional)

결제한 카드의 발급사명 - 카드 결제 건의 경우

발급사 코드를 지원하는 pg사에 한해 제공됩니다.
card_publisher_code?: string
카드 발행사 코드
(Optional)

결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우

발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_publisher_name?: string
카드 발행사명
(Optional)

결제 한 카드의 발행사명 - (카드 결제 건의 경우)

발행사 코드를 지원하는 pg사에 한해 제공됩니다.
card_quota?: integer
할부개월 수
(Optional)

결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우

card_number?: string
카드번호
(Optional)

7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.

card_type?: integer
카드 구분코드
(Optional)

주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. JTNet, 이니시스-빌링)

  • 0 : 신용카드
  • 1 : 체크카드
vbank_code?: string
가상계좌 은행 표준코드
(Optional)

결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우

vbank_name?: string
가상계좌 은행명
(Optional)

결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우

vbank_num?: string
가상계좌 계좌번호
(Optional)

결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우

vbank_holder?: string
가상계좌 예금주
(Optional)

결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우

vbank_date?: integer
가상계좌 입금기한
(Optional)

결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우

vbank_issued_at?: integer
가상계좌 생성시각
(Optional)

결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우

name?: string
제품명
(Optional)

결제건의 제품명

amount: number
결제금액

결제건의 결제금액

cancel_amount: number
취소금액

결제건의 누적 취소금액

currency: string
결제통화 구분코드

외환분호 e.g) KRW, USD, VND, ... Default: KRW

buyer_name?: string
주문자명
(Optional)

결제건의 주문자명

buyer_email?: string
주문자 Email주소
(Optional)

결제건의 주문자의 Email주소

buyer_tel?: string
주문자 전화번호
(Optional)

결제건의 주문자 전화번호

buyer_addr?: string
주문자 주소
(Optional)

결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호
(Optional)

결제건의 주문자 우편번호

custom_data?: string
추가정보
(Optional)

결제 요청시 가맹점에서 전달한 추가정보 (JSON string으로 전달)

user_agent?: string
단말기의 UserAgent 문자열
(Optional)

구매자가 결제시 사용한 단말기의 UserAgent 문자열

status: string
결제상태

결제건의 결제상태

started_at?: integer
요청 시각
(Optional)

결제건의 결제요청 시각 UNIX timestamp

paid_at?: integer
결제 시각
(Optional)

결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.

failed_at?: integer
실패시각
(Optional)

결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.

cancelled_at?: integer
취소시각
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.

fail_reason?: string
결제실패 사유
(Optional)

결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.

cancel_reason?: string
결제취소 사유
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.

receipt_url?: string
매출전표 URL
(Optional)

결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.

cancel_history?: PaymentCancelAnnotation[]
취소 내역
(Optional)

결제건의 취소/부분취소 내역

cancel_receipt_urls?: string[]
(Optional)
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
cash_receipt_issued?: boolean
현금영수증 발급 여부
(Optional)

결제건의 현금영수증 발급 여부

customer_uid?: string
구매자의 결제 수단 식별 고유번호
(Optional)

결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호

customer_uid_usage?: string
구매자의 결제 수단 식별 고유번호 사용 구분코드
(Optional)

결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드

401

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

404

유효하지 않은 imp_uid
try
Request
Request Sample
N/A
get/payments

결제내역 복수조회 API

여러 개의 포트원 거래고유번호 또는 가맹점 주문번호로 결제내역을 한 번에 조회합니다.(최대 100개)
(예시) /payments?imp_uid[]=imp_448280090638&imp_uid[]=imp_448280090639&merchant_uid[]=merchant_143434085216

Request

Query

imp_uid[]?: string[]
포트원 거래고유번호
(Optional)

조회할 결제건의 포트원 거래고유번호 리스트


merchant_uid[]?: string[]
가맹점 주문번호
(Optional)

결제요청 시 가맹점에서 요청한 가맹점 주문번호

Response

200

요청된 모든 imp_uid 에 대한 결제정보 응답완료
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

(Optional)
imp_uid: string
포트원 거래고유번호

결제건의 포트원 거래고유번호

merchant_uid: string
가맹점 주문번호

결제건의 가맹점 주문번호

pay_method?: string
결제수단 구분코드
(Optional)

결제건의 결제수단을 구분하는 코드

channel?: string
결제환경 구분코드
(Optional)

결제건을 생성한 환경을 구분하는 코드

pg_provider?: string
PG사 구분코드
(Optional)

결제건의 PG사 구분코드

emb_pg_provider?: string
허브형결제 PG사 구분코드
(Optional)

허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드

pg_tid?: string
PG사 거래번호
(Optional)

결제건의 PG사 거래번호

pg_id?: string
PG사 상점아이디
(Optional)

결제건의 PG사 상점아이디

escrow?: boolean
에스크로결제 여부
(Optional)

에스크로 결제건인지 구분하는 코드

apply_num?: string
승인번호
(Optional)

결제건의 신용카드 승인번호

bank_code?: string
은행 표준코드
(Optional)

결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우

bank_name?: string
은행명
(Optional)

결제건의 은행명 - 실시간계좌이체 결제 건의 경우

card_code?: string
카드사 코드번호
(Optional)

결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우

card_name?: string
카드사명
(Optional)

결제건의 카드사명 - 카드 결제 건의 경우

card_issuer_code?: string
카드 발급사 코드
(Optional)

결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우

발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_issuer_name?: string
카드 발급사명
(Optional)

결제한 카드의 발급사명 - 카드 결제 건의 경우

발급사 코드를 지원하는 pg사에 한해 제공됩니다.
card_publisher_code?: string
카드 발행사 코드
(Optional)

결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우

발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_publisher_name?: string
카드 발행사명
(Optional)

결제 한 카드의 발행사명 - (카드 결제 건의 경우)

발행사 코드를 지원하는 pg사에 한해 제공됩니다.
card_quota?: integer
할부개월 수
(Optional)

결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우

card_number?: string
카드번호
(Optional)

7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.

card_type?: integer
카드 구분코드
(Optional)

주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. JTNet, 이니시스-빌링)

  • 0 : 신용카드
  • 1 : 체크카드
vbank_code?: string
가상계좌 은행 표준코드
(Optional)

결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우

vbank_name?: string
가상계좌 은행명
(Optional)

결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우

vbank_num?: string
가상계좌 계좌번호
(Optional)

결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우

vbank_holder?: string
가상계좌 예금주
(Optional)

결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우

vbank_date?: integer
가상계좌 입금기한
(Optional)

결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우

vbank_issued_at?: integer
가상계좌 생성시각
(Optional)

결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우

name?: string
제품명
(Optional)

결제건의 제품명

amount: number
결제금액

결제건의 결제금액

cancel_amount: number
취소금액

결제건의 누적 취소금액

currency: string
결제통화 구분코드

외환분호 e.g) KRW, USD, VND, ... Default: KRW

buyer_name?: string
주문자명
(Optional)

결제건의 주문자명

buyer_email?: string
주문자 Email주소
(Optional)

결제건의 주문자의 Email주소

buyer_tel?: string
주문자 전화번호
(Optional)

결제건의 주문자 전화번호

buyer_addr?: string
주문자 주소
(Optional)

결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호
(Optional)

결제건의 주문자 우편번호

custom_data?: string
추가정보
(Optional)

결제 요청시 가맹점에서 전달한 추가정보 (JSON string으로 전달)

user_agent?: string
단말기의 UserAgent 문자열
(Optional)

구매자가 결제시 사용한 단말기의 UserAgent 문자열

status: string
결제상태

결제건의 결제상태

started_at?: integer
요청 시각
(Optional)

결제건의 결제요청 시각 UNIX timestamp

paid_at?: integer
결제 시각
(Optional)

결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.

failed_at?: integer
실패시각
(Optional)

결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.

cancelled_at?: integer
취소시각
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.

fail_reason?: string
결제실패 사유
(Optional)

결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.

cancel_reason?: string
결제취소 사유
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.

receipt_url?: string
매출전표 URL
(Optional)

결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.

cancel_history?: PaymentCancelAnnotation[]
취소 내역
(Optional)

결제건의 취소/부분취소 내역

cancel_receipt_urls?: string[]
(Optional)
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
cash_receipt_issued?: boolean
현금영수증 발급 여부
(Optional)

결제건의 현금영수증 발급 여부

customer_uid?: string
구매자의 결제 수단 식별 고유번호
(Optional)

결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호

customer_uid_usage?: string
구매자의 결제 수단 식별 고유번호 사용 구분코드
(Optional)

결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드

207

요청된 imp_uid 중 일부 거래 조회 실패(ex. 접근권한없음 또는 존재하지 않는 imp_uid)
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

(Optional)
imp_uid: string
포트원 거래고유번호

결제건의 포트원 거래고유번호

merchant_uid: string
가맹점 주문번호

결제건의 가맹점 주문번호

pay_method?: string
결제수단 구분코드
(Optional)

결제건의 결제수단을 구분하는 코드

channel?: string
결제환경 구분코드
(Optional)

결제건을 생성한 환경을 구분하는 코드

pg_provider?: string
PG사 구분코드
(Optional)

결제건의 PG사 구분코드

emb_pg_provider?: string
허브형결제 PG사 구분코드
(Optional)

허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드

pg_tid?: string
PG사 거래번호
(Optional)

결제건의 PG사 거래번호

pg_id?: string
PG사 상점아이디
(Optional)

결제건의 PG사 상점아이디

escrow?: boolean
에스크로결제 여부
(Optional)

에스크로 결제건인지 구분하는 코드

apply_num?: string
승인번호
(Optional)

결제건의 신용카드 승인번호

bank_code?: string
은행 표준코드
(Optional)

결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우

bank_name?: string
은행명
(Optional)

결제건의 은행명 - 실시간계좌이체 결제 건의 경우

card_code?: string
카드사 코드번호
(Optional)

결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우

card_name?: string
카드사명
(Optional)

결제건의 카드사명 - 카드 결제 건의 경우

card_issuer_code?: string
카드 발급사 코드
(Optional)

결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우

발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_issuer_name?: string
카드 발급사명
(Optional)

결제한 카드의 발급사명 - 카드 결제 건의 경우

발급사 코드를 지원하는 pg사에 한해 제공됩니다.
card_publisher_code?: string
카드 발행사 코드
(Optional)

결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우

발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_publisher_name?: string
카드 발행사명
(Optional)

결제 한 카드의 발행사명 - (카드 결제 건의 경우)

발행사 코드를 지원하는 pg사에 한해 제공됩니다.
card_quota?: integer
할부개월 수
(Optional)

결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우

card_number?: string
카드번호
(Optional)

7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.

card_type?: integer
카드 구분코드
(Optional)

주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. JTNet, 이니시스-빌링)

  • 0 : 신용카드
  • 1 : 체크카드
vbank_code?: string
가상계좌 은행 표준코드
(Optional)

결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우

vbank_name?: string
가상계좌 은행명
(Optional)

결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우

vbank_num?: string
가상계좌 계좌번호
(Optional)

결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우

vbank_holder?: string
가상계좌 예금주
(Optional)

결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우

vbank_date?: integer
가상계좌 입금기한
(Optional)

결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우

vbank_issued_at?: integer
가상계좌 생성시각
(Optional)

결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우

name?: string
제품명
(Optional)

결제건의 제품명

amount: number
결제금액

결제건의 결제금액

cancel_amount: number
취소금액

결제건의 누적 취소금액

currency: string
결제통화 구분코드

외환분호 e.g) KRW, USD, VND, ... Default: KRW

buyer_name?: string
주문자명
(Optional)

결제건의 주문자명

buyer_email?: string
주문자 Email주소
(Optional)

결제건의 주문자의 Email주소

buyer_tel?: string
주문자 전화번호
(Optional)

결제건의 주문자 전화번호

buyer_addr?: string
주문자 주소
(Optional)

결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호
(Optional)

결제건의 주문자 우편번호

custom_data?: string
추가정보
(Optional)

결제 요청시 가맹점에서 전달한 추가정보 (JSON string으로 전달)

user_agent?: string
단말기의 UserAgent 문자열
(Optional)

구매자가 결제시 사용한 단말기의 UserAgent 문자열

status: string
결제상태

결제건의 결제상태

started_at?: integer
요청 시각
(Optional)

결제건의 결제요청 시각 UNIX timestamp

paid_at?: integer
결제 시각
(Optional)

결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.

failed_at?: integer
실패시각
(Optional)

결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.

cancelled_at?: integer
취소시각
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.

fail_reason?: string
결제실패 사유
(Optional)

결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.

cancel_reason?: string
결제취소 사유
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.

receipt_url?: string
매출전표 URL
(Optional)

결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.

cancel_history?: PaymentCancelAnnotation[]
취소 내역
(Optional)

결제건의 취소/부분취소 내역

cancel_receipt_urls?: string[]
(Optional)
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
cash_receipt_issued?: boolean
현금영수증 발급 여부
(Optional)

결제건의 현금영수증 발급 여부

customer_uid?: string
구매자의 결제 수단 식별 고유번호
(Optional)

결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호

customer_uid_usage?: string
구매자의 결제 수단 식별 고유번호 사용 구분코드
(Optional)

결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드

401

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

404

해당되는 결제건을 찾지 못하였습니다.
try
Request
Request Sample
N/A
get/payments/find/{merchant_uid}/{payment_status}

결제 단건조회(고유 가맹점 주문번호 조회) API

가맹점지정 고유번호로 결제내역을 확인합니다
동일한 merchant_uid가 여러 건 존재하는 경우, 정렬 기준에 따라 가장 첫 번째 해당되는 건을 반환합니다. (모든 내역에 대한 조회가 필요하시면 GET 결제 복수조회(가맹점 주문번호 중복 포함) API를 사용해주세요.)

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

Request

Path

merchant_uid: string
가맹점 주문번호

결제요청 시 가맹점에서 요청한 가맹점 주문번호


payment_status?: string
거래상태 구분코드
(Optional)

특정 status상태의 값만 필터링하고 싶은 경우에 사용하는 파라미터로 지정하지 않으면 모든 상태를 대상으로 조회합니다

Query

sorting?: string
정렬구분코드
(Optional)

정렬 기준을 설정하는 파라미터로 기본값은 -started입니다.

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

response?: PaymentAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호

결제건의 포트원 거래고유번호

merchant_uid: string
가맹점 주문번호

결제건의 가맹점 주문번호

pay_method?: string
결제수단 구분코드
(Optional)

결제건의 결제수단을 구분하는 코드

channel?: string
결제환경 구분코드
(Optional)

결제건을 생성한 환경을 구분하는 코드

pg_provider?: string
PG사 구분코드
(Optional)

결제건의 PG사 구분코드

emb_pg_provider?: string
허브형결제 PG사 구분코드
(Optional)

허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드

pg_tid?: string
PG사 거래번호
(Optional)

결제건의 PG사 거래번호

pg_id?: string
PG사 상점아이디
(Optional)

결제건의 PG사 상점아이디

escrow?: boolean
에스크로결제 여부
(Optional)

에스크로 결제건인지 구분하는 코드

apply_num?: string
승인번호
(Optional)

결제건의 신용카드 승인번호

bank_code?: string
은행 표준코드
(Optional)

결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우

bank_name?: string
은행명
(Optional)

결제건의 은행명 - 실시간계좌이체 결제 건의 경우

card_code?: string
카드사 코드번호
(Optional)

결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우

card_name?: string
카드사명
(Optional)

결제건의 카드사명 - 카드 결제 건의 경우

card_issuer_code?: string
카드 발급사 코드
(Optional)

결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우

발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_issuer_name?: string
카드 발급사명
(Optional)

결제한 카드의 발급사명 - 카드 결제 건의 경우

발급사 코드를 지원하는 pg사에 한해 제공됩니다.
card_publisher_code?: string
카드 발행사 코드
(Optional)

결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우

발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_publisher_name?: string
카드 발행사명
(Optional)

결제 한 카드의 발행사명 - (카드 결제 건의 경우)

발행사 코드를 지원하는 pg사에 한해 제공됩니다.
card_quota?: integer
할부개월 수
(Optional)

결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우

card_number?: string
카드번호
(Optional)

7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.

card_type?: integer
카드 구분코드
(Optional)

주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. JTNet, 이니시스-빌링)

  • 0 : 신용카드
  • 1 : 체크카드
vbank_code?: string
가상계좌 은행 표준코드
(Optional)

결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우

vbank_name?: string
가상계좌 은행명
(Optional)

결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우

vbank_num?: string
가상계좌 계좌번호
(Optional)

결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우

vbank_holder?: string
가상계좌 예금주
(Optional)

결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우

vbank_date?: integer
가상계좌 입금기한
(Optional)

결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우

vbank_issued_at?: integer
가상계좌 생성시각
(Optional)

결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우

name?: string
제품명
(Optional)

결제건의 제품명

amount: number
결제금액

결제건의 결제금액

cancel_amount: number
취소금액

결제건의 누적 취소금액

currency: string
결제통화 구분코드

외환분호 e.g) KRW, USD, VND, ... Default: KRW

buyer_name?: string
주문자명
(Optional)

결제건의 주문자명

buyer_email?: string
주문자 Email주소
(Optional)

결제건의 주문자의 Email주소

buyer_tel?: string
주문자 전화번호
(Optional)

결제건의 주문자 전화번호

buyer_addr?: string
주문자 주소
(Optional)

결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호
(Optional)

결제건의 주문자 우편번호

custom_data?: string
추가정보
(Optional)

결제 요청시 가맹점에서 전달한 추가정보 (JSON string으로 전달)

user_agent?: string
단말기의 UserAgent 문자열
(Optional)

구매자가 결제시 사용한 단말기의 UserAgent 문자열

status: string
결제상태

결제건의 결제상태

started_at?: integer
요청 시각
(Optional)

결제건의 결제요청 시각 UNIX timestamp

paid_at?: integer
결제 시각
(Optional)

결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.

failed_at?: integer
실패시각
(Optional)

결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.

cancelled_at?: integer
취소시각
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.

fail_reason?: string
결제실패 사유
(Optional)

결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.

cancel_reason?: string
결제취소 사유
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.

receipt_url?: string
매출전표 URL
(Optional)

결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.

cancel_history?: PaymentCancelAnnotation[]
취소 내역
(Optional)

결제건의 취소/부분취소 내역

cancel_receipt_urls?: string[]
(Optional)
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
cash_receipt_issued?: boolean
현금영수증 발급 여부
(Optional)

결제건의 현금영수증 발급 여부

customer_uid?: string
구매자의 결제 수단 식별 고유번호
(Optional)

결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호

customer_uid_usage?: string
구매자의 결제 수단 식별 고유번호 사용 구분코드
(Optional)

결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드

401

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

404

거래건이 존재하지 않는 경우
try
Request
Request Sample
N/A
get/payments/findAll/{merchant_uid}/{payment_status}

결제 복수조회(가맹점 주문번호 중복 포함) API

가맹점지정 고유번호 및 상태기준으로 결제내역을 확인합니다
동일한 merchant_uid가 여러 건 존재하는 경우, 존재하는 모든 거래가 조회됩니다.

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

Request

Path

merchant_uid: string
가맹점 주문번호

결제요청 시 가맹점에서 요청한 가맹점 주문번호


payment_status?: string
결제상태코드
(Optional)

특정 status상태의 값만 필터링하고 싶은 경우에 사용하는 파라미터로 지정하지 않으면 모든 상태를 조회합니다.

Query

page?: integer
페이지번호
(Optional)

1부터 시작하며 기본값은 1입니다.


limit?: integer
페이지당 조회건수
(Optional)

한 번에 조회할 결제건수.(최대 1000건, 기본값 20건)


sorting?: string
정렬기준
(Optional)

정렬기준을 나타내는 파라미터로 기본값은 -started입니다.

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

(Optional)
total: integer
전체 건수

조회한 결제 상태에 대한 전체 건수

previous: integer
이전 page숫자

이전 page숫자로 이전 페이지가 없는 경우 0을 반환합니다.

next: integer
다음 page숫자

다음 page숫자로 다음 페이지가 없는 경우 0을 반환합니다.

결제 상세정보 배열
(Optional)

결제 상세정보 배열로 최대 20개를 반환합니다. 바로 아래 Payment structure를 확인해주세요.

400

merchant_uid누락, 올바르지 않은 status 등 파라메터가 잘못된 경우

401

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

404

유효하지 않은 merchant_uid
try
Request
Request Sample
N/A
get/payments/status/{payment_status}

결제상태기준 복수조회 API

미결제/결제완료/결제취소/결제실패 상태 별로 검색할 수 있습니다.(20건씩 최신순 페이징)

검색기간은 최대 90일까지이며 to파라메터의 기본값은 현재 unix timestamp이고 from파라메터의 기본값은 to파라메터 기준으로 90일 전입니다. 때문에, from/to 파라메터가 없이 호출되면 현재 시점 기준으로 최근 90일 구간에 대한 데이터를 검색하게 됩니다.
from, to 파라메터를 지정하여 90일 단위로 과거 데이터 조회는 가능합니다.

Request

Path

payment_status: string
결제상태코드

조회할 결제건의 결제상태 코드

Query

page?: integer
페이지번호
(Optional)

1부터 시작하며 기본값 1입니다.


limit?: integer
페이지 당 조회건수
(Optional)

한 번에 조회할 결제건수.(최대 1000건, 기본값 20건)


from?: integer
검색 시작 시각
(Optional)

기본값은 to 파라메터 기준으로 90일 전 unix timestamp입니다. (시간별 검색 시작 시각(>=) UNIX TIMESTAMP)


to?: integer
검색 종료 시각
(Optional)

기본값은 현재 unix timestamp입니다. (시간별 검색 종료 시각(<=) UNIX TIMESTAMP)


sorting?: string
정렬기준
(Optional)

정렬기준을 나타내는 파라미터로 기본값은 -started입니다.

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

(Optional)
total: integer
전체 건수

조회한 결제 상태에 대한 전체 건수

previous: integer
이전 page숫자

이전 page숫자로 이전 페이지가 없는 경우 0을 반환합니다.

next: integer
다음 page숫자

다음 page숫자로 다음 페이지가 없는 경우 0을 반환합니다.

결제 상세정보 배열
(Optional)

결제 상세정보 배열로 최대 20개를 반환합니다. 바로 아래 Payment structure를 확인해주세요.

400

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

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우
try
Request
Request Sample
N/A
post/payments/cancel

결제취소 API

승인된 결제를 취소합니다.
신용카드/실시간계좌이체/휴대폰소액결제의 경우 즉시 취소처리가 이뤄지게 되며, 가상계좌와 휴대폰소액결제 익월 환불(KCP)의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다. (가상계좌 환불, 휴대폰소액결제 익월 환불(KCP)의 경우 관련 특약계약 필요)

Request

Body

imp_uid?: string
포트원 거래고유번호
(Optional)

취소할 거래의 포트원 거래고유번호


merchant_uid?: string
가맹점 주문번호
(Optional)

가맹점에서 전달한 거래 고유번호로 imp_uid, merchant_uid 중 하나는 필수이어야 합니다. (두 값이 모두 넘어오면 imp_uid를 우선 적용합니다.)


amount?: number
(부분)취소 요청금액
(Optional)

(부분)취소요청 금액으로 (누락하거나 0을 입력하는 경우 전액 취소 요청합니다.)


tax_free?: number
(부분)취소요청 금액 중 면세금액
(Optional)

단, 아래 PG사의 경우 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다.


vat_amount?: number
(부분)취소요청금액 중 부가세 금액
(Optional)

단, 결제 시 부가세를 지정했던 경우 필수 입력 바랍니다.


checksum?: number
현재시점의 취소 가능한 잔액
(Optional)

API요청자가 기록하고 있는 취소가능 잔액과 포트원이 기록하고 있는 취소가능 잔액이 일치하는지 사전에 검증하고, 검증에 실패하면 트랜잭션을 수행하지 않습니다. null인 경우에는 검증 프로세스를 생략합니다.


reason?: string
취소 사유
(Optional)

결제건을 취소하려는 사유


refund_holder?: string
환불계좌 예금주
(Optional)

환불받을 계좌의 예금주


refund_bank?: string
환금계좌 은행코드
(Optional)

refund_account?: string
환불계좌 계좌번호
(Optional)

환불받을 계좌번호


refund_tel?: string
환불계좌 예금주 연락처
(Optional)

환불받을 계좌의 예금주 연락처 (가상계좌 취소인 경우 필수)


extra?: array
추가 파라미터
(Optional)

결제 취소 요청시 필요한 추가 정보

Response

200

정상 조회
code?: integer
응답코드
(Optional)

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

message?: string
응답메세지
(Optional)

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

response?: PaymentAnnotation
(Optional)
imp_uid: string
포트원 거래고유번호

결제건의 포트원 거래고유번호

merchant_uid: string
가맹점 주문번호

결제건의 가맹점 주문번호

pay_method?: string
결제수단 구분코드
(Optional)

결제건의 결제수단을 구분하는 코드

channel?: string
결제환경 구분코드
(Optional)

결제건을 생성한 환경을 구분하는 코드

pg_provider?: string
PG사 구분코드
(Optional)

결제건의 PG사 구분코드

emb_pg_provider?: string
허브형결제 PG사 구분코드
(Optional)

허브형 결제인 경우 결제건의 허브형 결제 PG사를 구분하는 코드

pg_tid?: string
PG사 거래번호
(Optional)

결제건의 PG사 거래번호

pg_id?: string
PG사 상점아이디
(Optional)

결제건의 PG사 상점아이디

escrow?: boolean
에스크로결제 여부
(Optional)

에스크로 결제건인지 구분하는 코드

apply_num?: string
승인번호
(Optional)

결제건의 신용카드 승인번호

bank_code?: string
은행 표준코드
(Optional)

결제건의 은행 표준코드 (금융결제원기준) - 실시간계좌이체 결제건의 경우

bank_name?: string
은행명
(Optional)

결제건의 은행명 - 실시간계좌이체 결제 건의 경우

card_code?: string
카드사 코드번호
(Optional)

결제건의 카드사 코드번호 (금융결제원 표준코드번호) - 카드 결제 건의 경우

card_name?: string
카드사명
(Optional)

결제건의 카드사명 - 카드 결제 건의 경우

card_issuer_code?: string
카드 발급사 코드
(Optional)

결제건의 카드 발급사 코드번호 (금융결제원 표준코드 번호) - 카드 결제 건의 경우

발급사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_issuer_name?: string
카드 발급사명
(Optional)

결제한 카드의 발급사명 - 카드 결제 건의 경우

발급사 코드를 지원하는 pg사에 한해 제공됩니다.
card_publisher_code?: string
카드 발행사 코드
(Optional)

결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우

발행사 코드 지원 pg사
- (신) 토스페이먼츠
- KSNET사
- 페이팔 RT
- (신) 스마트로
- (신) 나이스페이먼츠
- 웰컴페이먼츠
- 토스페이먼츠 브랜드페이
- (신) 토스페이
card_publisher_name?: string
카드 발행사명
(Optional)

결제 한 카드의 발행사명 - (카드 결제 건의 경우)

발행사 코드를 지원하는 pg사에 한해 제공됩니다.
card_quota?: integer
할부개월 수
(Optional)

결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우

card_number?: string
카드번호
(Optional)

7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 상이할 수 있습니다.

card_type?: integer
카드 구분코드
(Optional)

주의 : 해당 정보를 제공하지 않는 일부 PG사의 경우 null로 응답됩니다.(ex. JTNet, 이니시스-빌링)

  • 0 : 신용카드
  • 1 : 체크카드
vbank_code?: string
가상계좌 은행 표준코드
(Optional)

결제건의 가상계좌 은행 표준코드(금융결제원기준)- 가상계좌 결제 건의 경우

vbank_name?: string
가상계좌 은행명
(Optional)

결제건의 입금받을 가상계좌 은행명 - 가상계좌 결제 건의 경우

vbank_num?: string
가상계좌 계좌번호
(Optional)

결제건의 입금받을 가상계좌 계좌번호 - 가상계좌 결제 건의 경우

vbank_holder?: string
가상계좌 예금주
(Optional)

결제건의 입금받을 가상계좌 예금주 - 가상계좌 결제 건의 경우

vbank_date?: integer
가상계좌 입금기한
(Optional)

결제건의 가상계좌 입금기한 - 가상계좌 결제 건의 경우

vbank_issued_at?: integer
가상계좌 생성시각
(Optional)

결제건의 가상계좌 생성시각 UNIX timestamp - 가상계좌 결제 건의 경우

name?: string
제품명
(Optional)

결제건의 제품명

amount: number
결제금액

결제건의 결제금액

cancel_amount: number
취소금액

결제건의 누적 취소금액

currency: string
결제통화 구분코드

외환분호 e.g) KRW, USD, VND, ... Default: KRW

buyer_name?: string
주문자명
(Optional)

결제건의 주문자명

buyer_email?: string
주문자 Email주소
(Optional)

결제건의 주문자의 Email주소

buyer_tel?: string
주문자 전화번호
(Optional)

결제건의 주문자 전화번호

buyer_addr?: string
주문자 주소
(Optional)

결제건의 주문자 주소

buyer_postcode?: string
주문자 우편번호
(Optional)

결제건의 주문자 우편번호

custom_data?: string
추가정보
(Optional)

결제 요청시 가맹점에서 전달한 추가정보 (JSON string으로 전달)

user_agent?: string
단말기의 UserAgent 문자열
(Optional)

구매자가 결제시 사용한 단말기의 UserAgent 문자열

status: string
결제상태

결제건의 결제상태

started_at?: integer
요청 시각
(Optional)

결제건의 결제요청 시각 UNIX timestamp

paid_at?: integer
결제 시각
(Optional)

결제상태가 결제완료(paid)가 아닌 경우 0으로 표시됩니다.

failed_at?: integer
실패시각
(Optional)

결제상태가 결제실패(failed)가 아닌경우 0으로 표시됩니다.

cancelled_at?: integer
취소시각
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 0으로 표시됩니다.

fail_reason?: string
결제실패 사유
(Optional)

결제상태가 결제실패(failed)가 아닐 경우 null로 표시됩니다.

cancel_reason?: string
결제취소 사유
(Optional)

결제상태가 결제취소(cancelled)가 아닐 경우 null로 표시됩니다.

receipt_url?: string
매출전표 URL
(Optional)

결제건의 매출전표 URL로 PG사 또는 결제 수단에 따라 매출전표가 없을 수 있습니다.

cancel_history?: PaymentCancelAnnotation[]
취소 내역
(Optional)

결제건의 취소/부분취소 내역

cancel_receipt_urls?: string[]
(Optional)
(Deprecated : cancel_history 사용 권장) 취소/부분취소 시 생성되는 취소 매출전표 확인 URL. 부분취소 횟수만큼 매출전표가 별도로 생성됨
cash_receipt_issued?: boolean
현금영수증 발급 여부
(Optional)

결제건의 현금영수증 발급 여부

customer_uid?: string
구매자의 결제 수단 식별 고유번호
(Optional)

결제건에 사용된 빌링키와 매핑되며 가맹점에서 채번하는 구매자의 결제 수단 식별 고유번호

customer_uid_usage?: string
구매자의 결제 수단 식별 고유번호 사용 구분코드
(Optional)

결제처리에 사용된 구매자의 결제 수단 식별 고유번호의 사용 구분코드

401

인증 Token이 전달되지 않았거나 유효하지 않은 경우
try
Request
Request Sample
N/A

결제 금액 사전 등록 관련 API

비인증 결제 관련 API

별도 결제창 호출없이 결제를 진행할 수 있는 비인증 결제 기능을 제공합니다.

정기 결제 관련 API

빌링키 관련 API

가상계좌 관련 API

PG사 관련 API

PG사 별 추가로 지원하는 기능을 제공합니다.

카카오 관련 API

카카오페이에서 지원하는 기능을 제공합니다.

KCP 퀵페이 관련 API

KCP 퀵페이에서 지원하는 기능을 제공합니다.

네이버페이 관련 API

네이버페이에서 지원하는 기능을 제공합니다.

목차

(주문형-네이버페이) 네이버페이 주문환불 API
post/payments/{imp_uid}/naver/cancel
(주문형-네이버페이) 구매자의 환불요청 승인처리 API
post/payments/{imp_uid}/naver/approve-cancel
(주문형-네이버페이) 상품주문 발송처리 API
post/payments/{imp_uid}/naver/ship
(주문형-네이버페이) 교환승인된 상품 재발송처리 API
post/payments/{imp_uid}/naver/ship-exchanged
(주문형-네이버페이) 교환승인된 상품 수거완료처리 API
post/payments/{imp_uid}/naver/collect-exchanged
(주문형-네이버페이) 상품발주처리 API
post/payments/{imp_uid}/naver/place
(주문형-네이버페이) 상품반품요청 API
post/payments/{imp_uid}/naver/request-return
(주문형-네이버페이) 상품 반품승인 처리 API
post/payments/{imp_uid}/naver/approve-return
(주문형-네이버페이) 상품 반품거절 처리 API
post/payments/{imp_uid}/naver/reject-return
(주문형-네이버페이) 상품 반품보류 처리 API
post/payments/{imp_uid}/naver/withhold-return
(주문형-네이버페이) 반품보류상품 반품보류해제 처리 API
post/payments/{imp_uid}/naver/resolve-return
(결제형-네이버페이) 네이버페이 포인트 적립 API
post/payments/{imp_uid}/naver/point
(결제형-네이버페이) 에스크로 주문 확정 API
post/payments/{imp_uid}/naver/confirm
(주문형-네이버페이) 포트원 거래고유번호 기준 네이버페이 상품주문 조회 API
get/payments/{imp_uid}/naver/product-orders
(주문형-네이버페이) 네이버페이 상품주문번호로 상품주문 상세 조회 API
get/naver/product-orders/{product_order_id}
(주문형-네이버페이) 네이버페이 구매평 조회 API
get/naver/reviews
(결제형-네이버페이) 현금영수증 발급 가용액 조회 API
get/payments/{imp_uid}/naver/cash-amount

페이코 관련 API

페이코에서 지원하는 기능을 제공합니다.

페이먼트월 관련 API

페이먼트월에서 지원하는 기능을 제공합니다.

본인인증 관련 API

현금영수증 관련 API

에스크로 관련 API

가맹점 정보 관련 API

가맹점 정보를 관리하는 기능을 제공합니다.

가맹점의 하위가맹점 관련 API

하위 상점 관련 API

하위 상점과 관련된 기능을 제공합니다.

기타 API

부가적인 기능을 제공합니다.

베네피아 포인트 관련 API

베네피아 포인트(복지 포인트)와 관련된 기능을 제공합니다.

결제기관 관련 API

편의점 결제 관련 API

편의점 결제를 위한 수납 번호(barcode)와 관련된 기능을 제공합니다.

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다