PortOne REST API - V1

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

V1 API hostname: api.iamport.kr

Swagger JSON 내려받기Postman 등에서 import하여 활용할 수 있습니다.

인증 관련 API

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

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

API 키와 API 시크릿 확인하기

관리자 콘솔 상점・계정 관리 화면 접속
내 식별코드・API Keys 버튼 클릭

API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다

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

액세스 토큰 발급 받기

access_token 발급 API post/users/getToken 호출

/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

결제 건과 관련된 기능을 제공합니다.

결제 금액 사전 등록 관련 API

사전 등록하는 결제금액과 관련된 기능을 제공합니다.

비인증 결제 관련 API

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

정기 결제 관련 API

비인증 결제 중 정기 결제를 관리하는 기능을 제공합니다.

customer__uid를 이용하여 비인증 결제 요청을 예약할 수 있는 API입니다.
비 인증 결제(빌링키) API를 포트원이 대신 수행하는 개념)
결제 요청에 대한 결과는 notice_url에 설정한 EndPoint URL로 웹훅을 통해 수신(POST request)받을 수 있습니다.

기존에 빌링키가 등록된 customer_uid가 존재하는 경우 해당 customer_uid와 해당되는 빌링키로 schedule정보가 예약됩니다.(카드정보 선택사항)
등록된 customer_uid가 없는 경우 빌링키 신규 발급을 먼저 진행한 후 schedule정보를 예약합니다.(카드정보 필수사항)
예약건 별로 고유의 merchant_uid를 전달해주셔야 합니다.
schedules의 상세정보(선택정보) buyer_name, buyer_email, buyer_tel, buyer_addr, buyer_postcode 누락시,
customer_uid에 해당되는 customer_name, customer_email, customer_tel, customer_addr, customer_postcode 정보로 대체됩니다.(둘 다 입력시 buyer_* 정보를 우선합니다)

Request

Body

customer_uid: string

구매자의 결제 수단 식별 고유번호

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

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

checking_amount?: integer

유효카드 체크 승인금액

(Optional)

결제 직후 자동으로 취소됩니다. (0원으로 설정할 경우 테스트하지 않음)

card_number?: string

카드번호

(Optional)

결제 예약 요청할 카드번호(dddd-dddd-dddd-dddd)

expiry?: string

카드 유효기간

(Optional)

결제 예약 요청할 카드 유효기간(YYYY-MM)

birth?: string

생년월일 6자리

(Optional)

결제 예약 요청할 카드 소유자의 생년월일6자리(법인카드의 경우 사업자등록번호10자리)

pwd_2digit?: string

카드비밀번호 앞 2자리

(Optional)

결제 예약 요청할 카드비밀번호 앞 2자리

cvc?: string

카드 인증번호

(Optional)

결제 예약 요청할 카드 인증번호 (카드 뒷면 3자리, AMEX의 경우 4자리)

pg?: string

pg 구분코드

(Optional)

신규 customer_uid를 등록하는 경우에만 유효합니다.(기존에 등록된 customer_uid로만 schedule 하는 경우에는 pg파라메터 적용되지 않습니다.)

API 방식 비인증 PG설정이 2개 이상인 경우, 결제가 진행되길 원하는 PG사를 지정하실 수 있습니다. pg 파라메터는 {PG사} 혹은 {PG사}.{PG상점아이디} 형태의 문자열입니다.

지정하지 않거나 유효하지 않은 값이 전달되면 기본PG설정된 값을 이용해 결제하게 됩니다.

나이스페이먼츠, JTNet 2가지 PG설정이 되어있다면, pg 파라메터로 nice 또는 jtnet로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능

schedules: ScheduleAnnotation[]

결제예약 스케쥴

결제예약 스케쥴에 대한 배열

merchant_uid: string

가맹점의 주문번호

결제 예약건의 가맹점 주문번호

schedule_at: integer

예약시각

결제요청 예약시각 UNIX timestamp

currency: string

결제 통화 코드

통화 e.g.) KRW, USD, VND, ... Default: KRW

amount: number

결제금액

결제 예약을 요청한 결제금액

tax_free?: number

면세공급가액

(Optional)

결제 예약을 요청한 결제금액 중 면세공급가액

vat_amount?: number

부가세

(Optional)

결제 예약을 요청한 결제금액 중 부가세

name?: string

제품명

(Optional)

결제건의 제품명

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)

예약된 결제가 수행될 때 함께 저장할 추가정보

notice_url?: string

Notification URL(Webhook URL)

(Optional)

해당 파리미터를 지정하지 않으면 웹훅은 관리자페이지의 Notification URL로 발송 됩니다

product_type?: string

주문 상품구분

(Optional)

판매 상품에 대한 구분 값

cash_receipt_type?: string

현금영수증 발행대상

(Optional)

현금영수증 발행대상 구분 값

card_quota?: number

카드 할부 개월 수

(Optional)

결제건의 카드 할부 개월 수로 기본값은 **0(일시불)**입니다.

interest_free_by_merchant?: boolean

가맹점부담 무이자 할부여부

(Optional)

카드할부 처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 가맹점이 지불하고자 PG사와 계약한 경우 (Default : false)

use_card_point?: boolean

카드포인트 사용여부

(Optional)

PG사 영업담당자와 계약 당시 사전 협의가 필요하며 기본값은 false입니다.

product_count?: integer

결제 상품의 개수

(Optional)

결제 상품의 개수로 기본값은 1입니다.

extra?: object

추가 파라미터

(Optional)

결제 예약 요청시 필요한 추가 정보

bypass?: string

bypass 데이터

(Optional)

전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요

Response

200

정상적으로 예약 등록이 완료되었습니다

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation[]

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

401

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

try

Request

Response Status: N/A

N/A

post/subscribe/payments/unschedule

예약된 결제가 실행되기전에 해당 예약을 취소할 수 있는 API입니다.

Request

Body

customer_uid: string

구매자의 결제 수단 식별 고유번호

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

merchant_uid?: string

가맹점 주문번호

(Optional)

누락되면 customer_uid에 대한 결제예약정보를 일괄취소합니다.

Response

200

정상적으로 예약 취소가 완료되었습니다

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation[]

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

401

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

try

Request

Response Status: N/A

N/A

get/subscribe/payments/schedule/{merchant_uid}

예약 거래주문번호(merchant_uid)로 결제예약정보를 조회할 수 있습니다. 결제예약 등록시 사용된 merchant_uid로 예약 상태 등 정보를 조회할 수 있습니다.

Request

Path

merchant_uid: string

가맹점 주문번호

결제예약에 사용된 가맹점 거래 고유번호

Response

200

정상적으로 예약 취소가 완료되었습니다

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

401

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

404

merchant_uid로 조회되는 예약결제건이 존재하지 않는 경우

try

Request

Response Status: N/A

N/A

put/subscribe/payments/schedule/{merchant_uid}

결제예약 시 사용한 거래주문번호(merchant_uid)를 이용하여 해당하는 예약 건의 결제요청 예약시각을 수정할 수 있습니다.

Request

Path

merchant_uid: string

가맹점 주문번호

결제예약에 사용된 가맹점 거래 고유번호

Body

schedule_at: integer

수정할 예약시각

수정할 결제요청 예약시각 UNIX timestamp

Response

200

정상적으로 예약 변경이 완료되었습니다.

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

400

필수 파라미터 누락, 이미 실행 혹은 취소된 결제예약, 예약시각이 현재 시각보다 과거인 경우

404

존재하지 않는 결제예약

500

포트원 내부 이슈로 인한 API 호출 실패

try

Request

Response Status: N/A

N/A

post/subscribe/payments/schedule/{merchant_uid}/reschedule

결제 예약 실행 시 실패했던 건, 혹은 예약 취소했던 건에 대해 다른 시각으로 다시 결제 예약을 할 수 있습니다.

Request

Path

merchant_uid: string

가맹점 주문번호

결제예약에 사용된 가맹점 거래 고유번호

Body

schedule_at: integer

예약 시각

실패한 예약건을 다시 처리할 시각 UNIX timestamp

Response

200

정상적으로 재예약이 완료되었습니다.

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

400

필수 파라미터 누락, 아직 실행되지 않거나 이미 실행 중 혹은 승인된 결제예약, 예약시각이 현재 시각보다 과거인 경우

404

존재하지 않는 결제예약

500

포트원 내부 이슈로 인한 API 호출 실패

try

Request

Response Status: N/A

N/A

post/subscribe/payments/schedule/{merchant_uid}/retry

결제 예약 실행 시 실패했던 건, 혹은 예약 취소했던 건을 즉시 결제 재시도 할 수 있습니다.

Request

Path

merchant_uid: string

가맹점 주문번호

결제예약에 사용된 가맹점 거래 고유번호

Response

200

정상적으로 재시도가 완료되었습니다. (결제 성공/실패 여부는 결제 상태(status)로 확인 필요)

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)

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

400

필수 파라미터 누락, 아직 실행되지 않거나 이미 실행중 혹은 승인된 결제예약

404

존재하지 않는 결제예약 혹은 빌링키

500

미지원 PG사, 포트원 내부 이슈 등으로 인한 API 호출 실패

try

Request

Response Status: N/A

N/A

get/subscribe/payments/schedule/customers/{customer_uid}

빌링키 결제예약 조회 API 와 동일한 동작을 하는 API입니다.

customer_uid별 결제예약목록을 조회할 수 있습니다. 결제예약정보가 (페이징된)목록으로 전달되며, 최대 3개월 단위로 조회가 가능합니다.

결제예약정보가 예약된 시각 기준으로 최신순으로 정렬되어 전달됩니다.

Request

Path

customer_uid: string

빌링키

string 타입의 고객의 결제 수단 식별 고유번호

Query

page?: integer

조회목록 페이징

(Optional)

조회목록 페이징으로 기본값은 1입니다.

from: integer

조회 시작시각

조회 시작시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. from <= '예약시각')

to: integer

조회 종료시각

조회 종료시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. '예약시각' < to)

schedule-status?: string

예약상태

(Optional)

조회할 결제건의 예약상태

Response

200

결제예약목록 조회완료

code?: integer

응답코드

(Optional)

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

message?: string

응답메세지

(Optional)

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

response?: ScheduleResultAnnotation[]

(Optional)

customer_uid?: string

구매자의 결제 수단 식별 고유번호

(Optional)

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

merchant_uid?: string

가맹점 주문번호

(Optional)

예약 결제건의 가맹점 주문번호

imp_uid?: string

포트원 거래고유번호

(Optional)

예약된 결제가 실행 전 철회되거나 아직 실행 전 예약 상태에 있으면 imp_uid는 null입니다.

customer_id?: string

구매자 ID

(Optional)

string 타입의 구매자 식별 고유번호

schedule_at?: integer

결제 예정 시각

(Optional)

결제 예약시 요청한 결제 예정 시각 UNIX timestamp

executed_at?: integer

결제 실행 시각

(Optional)

실제 결제가 실행된 시각 UNIX timestamp

revoked_at?: integer

결제 실행 철회 시각

(Optional)

예약 결제 실행을 철회한 시각 UNIX timestamp

amount?: number

결제금액

(Optional)

결제 예약시 요청한 결제금액

currency?: string

결제 통화 코드

(Optional)

통화 e.g.) KRW, USD, VND, ... Default: KRW

name?: string

제품명

(Optional)

예약 결제건의 제품명

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)

예약된 결제가 수행될 때 결제정보와 함께 저장할 추가정보

schedule_status?: string

예약상태

(Optional)

결제건의 예약상태

payment_status?: string

결제상태

(Optional)

예약 결제건의 승인 상태

fail_reason?: string

실패사유

(Optional)

예약 결제건이 결제 승인에 실패한 경우, 실패사유

400

검색 파라메터가 유효하지 않은 경우

401

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

try

Request

Response Status: N/A

N/A

빌링키 관련 API

빌링키 관리와 관련된 기능을 제공합니다.

가상계좌 관련 API

가상계좌 결제와 관련된 기능을 제공합니다.

PG사 관련 API

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

카카오 관련 API

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

KCP 퀵페이 관련 API

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

네이버페이 관련 API

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

페이코 관련 API

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

페이먼트월 관련 API

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

본인인증 관련 API

본인인증 요청 및 결과 조회와 관련된 기능을 제공합니다.

현금영수증 관련 API

포트원 결제건 및 외부 결제 건의 현금영수증 관리와 관련된 기능을 제공합니다.

에스크로 관련 API

에스크로 결제 건의 배송 정보와 관련된 기능을 제공합니다.

가맹점 정보 관련 API

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

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

대표가맹점에 대한 하위가맹점 관리와 관련된 기능을 제공합니다.

하위 상점 관련 API

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

기타 API

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

베네피아 포인트 관련 API

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

결제기관 관련 API

금융결제원 기준 카드사, 은행의 표준 코드와 기관정보 조회 기능을 제공합니다.

편의점 결제 관련 API

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

타입 정의

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

AuthAnnotation AuthResponse BenepiaPointAnnotation BenepiaPointResponse CertificationAnnotation CertificationOTPAnnotation CertificationOTPResponse CertificationResponse CustomerAnnotation CustomerResponse EscrowLogisAnnotation EscrowLogisInfoAnnotation EscrowLogisProductsAnnotation EscrowLogisReceiverAnnotation EscrowLogisResponse EscrowLogisSenderAnnotation ExternalReceiptAnnotation ExternalReceiptResponse KakaoOrderAnnotation KakaoOrderResponse KcpQuickMemberAnnotation KcpQuickMemberResponse MultipleCustomersResponse MultiplePaymentsResponse MultiplePgSettingResponse NaverAddress NaverCashAmountAnnotation NaverCashAmountResponse NaverOrderer NaverProductOrderAnnotation NaverProductOrderArrayResponse NaverProductOrderResponse NaverReviewAnnotation NaverReviewsResponse PagedPaymentAnnotation PartnerReceiptResponse PartnerReceiptResultAnnotation PartnerReceiptsAnnotation PaycoStatusAnnotation PaycoStatusResponse PaymentAnnotation PaymentBalanceAnnotation PaymentBalanceHistoriesAnnotation PaymentBalanceResponse PaymentBalanceResponseAnnotation PaymentCancelAnnotation PaymentListResponse PaymentPrepareAnnotation PaymentPrepareResponse PaymentResponse PaymentwallDeliveryAnnotation PaymentwallDeliveryDetailAnnotation PgSettingAnnotation ReceiptAnnotation ReceiptResponse ResponseAnnotation ScheduleAnnotation ScheduleResponse ScheduleResultAnnotation SingleScheduleResponse StandardCodeAnnotation StandardCodeListResponse StandardCodeResponse SubscribePaymentExtra TierAnnotation TierResponse VbankHolderAnnotation VbankHolderResponse

PortOne REST API - V1

인증 관련 API

목차

결제 관련 API

목차

결제 금액 사전 등록 관련 API

목차

비인증 결제 관련 API

목차

정기 결제 관련 API

목차

결제예약 복수조회 API

Request

Query

Response

200

400

401

결제 예약 API

Request

Body

Response

200

401

결제 예약취소 API

Request

Body

Response

200

401

결제예약 단건조회 API

Request

Path

Response

200

401

404

결제요청 예약시각 수정 API

Request

Path

Body

Response

200

400

404

500

결제 실패 재예약 API

Request

Path

Body

Response

200

400

404

500

결제 실패 재시도 API

Request

Path

Response

200

400

404

500

결제예약 복수조회(빌링키) API

Request

Path

Query

Response

200

400

401

빌링키 관련 API

목차

가상계좌 관련 API

목차

PG사 관련 API

카카오 관련 API

목차

KCP 퀵페이 관련 API

목차