PortOne REST API - V2

API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.

V2 API hostname: api.portone.io

요청 및 응답 형식

요청과 응답의 본문은 JSON 형식입니다.

API 매개 변수 중 URL 경로 또는 query에 들어가는 문자열 값이 있는 경우, 그 자리에 들어갈 수 없는 문자는 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent 함수 등을 사용할 수 있습니다.

인증 방식

V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 관리자콘솔 내 결제연동 탭에서 발급받으실 수 있습니다.

인증 관련 API를 제외한 모든 API는 HTTP Authorization 헤더로 아래 형식의 인증 정보를 전달해주셔야 합니다.

• Authorization: PortOne MY_API_SECRET

GET 요청 시 body 대신 query 사용하기

GET 요청 시에 body(content)를 전달하는 것은 HTTP 표준에 부합하지 않아, 클라이언트에 따라 사용 불가능한 경우가 있습니다.

이 경우, body 문자열을 requestBody query 필드에 넣어 주시면 됩니다. query 필드에 들어가는 문자열은 URL 인코드하셔야 합니다.

멱등 키

Idempotency-Key 헤더는 네트워크 장애나 타임아웃 시 동일한 요청이 중복 처리되는 것을 방지합니다. 자세한 표준은 IETF 문서를 참고하세요.

사용 방법

요청 헤더에 고유한 키를 포함하세요. UUID 등 고유한 문자열이어야 합니다. 16~256자의 영문 대소문자, 숫자, -, _을 사용 가능합니다.

• Idempotency-Key: unique-request-id-123

요청 타임아웃이 발생한 경우, 동일한 멱등 키를 사용하여 재시도할 수 있습니다. 이 경우, 서버는 요청을 중복 처리하지 않고, 기존 응답을 반환합니다.

재시도에서 IDEMPOTENCY_OUTSTANDING_REQUEST 에러가 발생한 경우, 시간이 조금 지난 후 다시 재시도해 주세요.

• 지원 메서드: POST, PUT, PATCH, DELETE (GET은 무시됨)
• 처리 중인 요청을 재시도하는 경우: 409 에러 ({"type":"IDEMPOTENCY_OUTSTANDING_REQUEST"}...})
• 완료된 요청을 재시도하는 경우: 기존 응답을 그대로 반환
• 멱등성 보장 기간: 3시간 (추후 변경 가능)
• 서로 다른 요청을 같은 멱등 키로 요청해서는 안 됩니다.

요청 타임아웃 정책

API 호출시 PG 및 결제 원천사의 응답 지연을 고려하여 최소 60초의 읽기 타임아웃 시간을 설정하도록 권장합니다.

서버에서 요청 처리 중에 클라이언트 측에서 연결을 끊은 경우에도 요청이 취소되지 않습니다. 이 경우 같은 멱등 키로 같은 요청을 재시도하면 결과를 확인할 수 있습니다.

하위호환성

포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.

1. 현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.

   • 입력 형식 내 필드 정의가 삭제되지 않습니다.

   • 필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.

     • 오로지 선택 입력 정보만 추가될 수 있습니다.

   • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.

   • enum 타입의 값이 삭제되지 않습니다.

2. 출력 형식이 확장될 수 있지만, 축소되지 않습니다.

   • 출력 형식 내 필드 정의가 삭제되지 않습니다.

   • 사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.

     • 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
     • 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.

   • 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.

   • 단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.

     • 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.

UNSTABLE이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.

타입 정의