PortOne REST API - V2
API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.
V2 API hostname: api.portone.io
요청 및 응답 형식
요청과 응답의 본문은 JSON 형식입니다.
API 매개 변수 중 URL 경로에 들어가는 문자열 값이 있는 경우, URL 경로에 들어갈 수 없는 문자열은 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent
함수 등을 사용할 수 있습니다.
인증 방식
V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 관리자콘솔 내 결제연동 탭에서 발급받으실 수 있습니다.
인증 관련 API를 제외한 모든 API는 HTTP Authorization
헤더로 아래 형식의 인증 정보를 전달해주셔야 합니다.
Authorization: PortOne MY_API_SECRET
GET 요청 시 Body 대신 Query 사용하기
GET 요청 시에 Body를 전달해야 하는 경우, Body 대신 Query를 사용할 수 있습니다.
이 경우, Body 객체를 requestBody
Query 필드에 넣어주시면 됩니다.
하위호환성
포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.
현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
- 입력 형식 내 필드 정의가 삭제되지 않습니다.
필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
- 오로지 선택 입력 정보만 추가될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
- enum 타입의 값이 삭제되지 않습니다.
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
- 출력 형식 내 필드 정의가 삭제되지 않습니다.
사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
- 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
- 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
- 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.
UNSTABLE
이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.
인증 관련 API
결제 관련 API
목차
결제 예약 관련 API
빌링키 관련 API
현금 영수증 관련 API
프로모션 관련 API
본인인증 관련 API
파트너 정산 관련 API
정책 관련 API
목차
파트너 관련 API
정산 상세내역 관련 API
정산건 조회
Request
Path
조회하고 싶은 정산건 아이디
Response
200
성공 응답으로 정산건 객체가 반환됩니다.
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
파트너 담당자에게 연락하기 위한 정보들 입니다.
currency
가 KRW 일 경우 예금주 조회 API 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
정산 상태
SCHEDULED
정산 예약IN_PROCESS
정산 중SETTLED
정산 완료IN_PAYOUT
지급 중PAID_OUT
지급 완료날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
KRW
대한민국 원화USD
미국 달러JPY
일본 엔화AED
UAE DirhamAFN
AfghaniALL
LekAMD
Armenian DramANG
Netherlands Antillean GuilderAOA
KwanzaARS
Argentine PesoAUD
Australian DollarAWG
Aruban FlorinAZN
Azerbaijan ManatBAM
Convertible MarkBBD
Barbados DollarBDT
TakaBGN
Bulgarian LevBHD
Bahraini DinarBIF
Burundi FrancBMD
Bermudian DollarBND
Brunei DollarBOB
BolivianoBOV
MvdolBRL
Brazilian RealBSD
Bahamian DollarBTN
NgultrumBWP
PulaBYN
Belarusian RubleBZD
Belize DollarCAD
Canadian DollarCDF
Congolese FrancCHE
WIR EuroCHF
Swiss FrancCHW
WIR FrancCLF
Unidad de FomentoCLP
Chilean PesoCNY
Yuan RenminbiCOP
Colombian PesoCOU
Unidad de Valor RealCRC
Costa Rican ColonCUC
Peso ConvertibleCUP
Cuban PesoCVE
Cabo Verde EscudoCZK
Czech KorunaDJF
Djibouti FrancDKK
Danish KroneDOP
Dominican PesoDZD
Algerian DinarEGP
Egyptian PoundERN
NakfaETB
Ethiopian BirrEUR
EuroFJD
Fiji DollarFKP
Falkland Islands PoundGBP
Pound SterlingGEL
LariGHS
Ghana CediGIP
Gibraltar PoundGMD
DalasiGNF
Guinean FrancGTQ
QuetzalGYD
Guyana DollarHKD
Hong Kong DollarHNL
LempiraHRK
Kuna (Replaced by EUR)HTG
GourdeHUF
ForintIDR
RupiahILS
New Israeli SheqelINR
Indian RupeeIQD
Iraqi DinarIRR
Iranian RialISK
Iceland KronaJMD
Jamaican DollarJOD
Jordanian DinarKES
Kenyan ShillingKGS
SomKHR
RielKMF
Comorian Franc KPW
North Korean WonKWD
Kuwaiti DinarKYD
Cayman Islands DollarKZT
TengeLAK
Lao KipLBP
Lebanese PoundLKR
Sri Lanka RupeeLRD
Liberian DollarLSL
LotiLYD
Libyan DinarMAD
Moroccan DirhamMDL
Moldovan LeuMGA
Malagasy AriaryMKD
DenarMMK
KyatMNT
TugrikMOP
PatacaMRU
OuguiyaMUR
Mauritius RupeeMVR
RufiyaaMWK
Malawi KwachaMXN
Mexican PesoMXV
Mexican Unidad de Inversion (UDI)MYR
Malaysian RinggitMZN
Mozambique MeticalNAD
Namibia DollarNGN
NairaNIO
Cordoba OroNOK
Norwegian KroneNPR
Nepalese RupeeNZD
New Zealand DollarOMR
Rial OmaniPAB
BalboaPEN
SolPGK
KinaPHP
Philippine PesoPKR
Pakistan RupeePLN
ZlotyPYG
GuaraniQAR
Qatari RialRON
Romanian LeuRSD
Serbian DinarRUB
Russian RubleRWF
Rwanda FrancSAR
Saudi RiyalSBD
Solomon Islands DollarSCR
Seychelles RupeeSDG
Sudanese PoundSEK
Swedish KronaSGD
Singapore DollarSHP
Saint Helena PoundSLE
LeoneSLL
LeoneSOS
Somali ShillingSRD
Surinam DollarSSP
South Sudanese PoundSTN
DobraSVC
El Salvador ColonSYP
Syrian PoundSZL
LilangeniTHB
BahtTJS
SomoniTMT
Turkmenistan New ManatTND
Tunisian DinarTOP
Pa’angaTRY
Turkish LiraTTD
Trinidad and Tobago DollarTWD
New Taiwan DollarTZS
Tanzanian ShillingUAH
HryvniaUGX
Uganda ShillingUSN
US Dollar (Next day)UYI
Uruguay Peso en Unidades Indexadas (UI)UYU
Peso UruguayoUYW
Unidad PrevisionalUZS
Uzbekistan SumVED
Bolívar SoberanoVES
Bolívar SoberanoVND
DongVUV
VatuWST
TalaXAF
CFA Franc BEACXAG
SilverXAU
GoldXBA
Bond Markets Unit European Composite Unit (EURCO)XBB
Bond Markets Unit European Monetary Unit (E.M.U.-6)XBC
Bond Markets Unit European Unit of Account 9 (E.U.A.-9)XBD
Bond Markets Unit European Unit of Account 17 (E.U.A.-17)XCD
East Caribbean DollarXDR
SDR (Special Drawing Right)XOF
CFA Franc BCEAOXPD
PalladiumXPF
CFP FrancXPT
PlatinumXSU
SucreXTS
Codes specifically reserved for testing purposesXUA
ADB Unit of AccountXXX
The codes assigned for transactions where no currency is involvedYER
Yemeni RialZAR
RandZMW
Zambian KwachaZWL
Zimbabwe Dollar400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformTransferNotFoundError
정산건 삭제
Request
Path
정산건 아이디
Response
200
400
PlatformCancelOrderTransfersExistsError
PlatformTransferNonDeletableStatusError
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformTransferNotFoundError
정산건 다건 조회
Request
body를 쿼리 문자열에 포함시켜 보낼 수 있습니다. 자세히 보기
Body
다건 조회 API 에 사용되는 페이지 입력 정보
정산 시작일 범위와 정산 일 범위는 둘 중 하나만 입력 가능합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 태그를 하나 이상 가지는 파트너에 대한 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 계약 아이디를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 할인 분담 정책 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 추가 수수료 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 결제 수단을 가지는 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 채널 키를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 방식의 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 상태인 정산건만 조회합니다.
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 정산건만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
Response
200
정산 상태
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
반환된 페이지 결과 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
주문 정산건 생성
Request
Body
기본값은 파트너의 기본 계약 아이디 입니다.
주문 금액 또는 주문 항목 하나만 입력 가능합니다.
주문 항목과 면세 금액을 같이 전달하시면 최종 면세 금액은 주문 항목의 면세 금액이 아닌 전달해주신 면세 금액으로 적용됩니다.
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
외부 결제 상세 정보
통화 단위
결제 수단 입력 정보
기본값은 false 입니다.
플랫폼 정산 파라미터 값
Response
200
주문 정산건
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
정산 상태
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
정산 금액과 정산 금액 계산에 사용된 금액 정보들 입니다.
계약은 플랫폼 고객사가 파트너에게 정산해줄 대금과 정산일을 계산하는 데 적용되는 정보입니다. 고객사의 플랫폼에서 재화 및 서비스를 판매하기 위한 중개수수료와 판매금에 대한 정산일로 구성되어 있습니다.
결제 정보
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우PlatformProductIdDuplicatedError
PlatformSettlementPaymentAmountExceededPortOnePaymentError
: 정산 요청 결제 금액이 포트원 결제 내역의 결제 금액을 초과한 경우PlatformSettlementTaxFreeAmountExceededPortOnePaymentError
: 정산 요청 면세 금액이 포트원 결제 내역의 면세 금액을 초과한 경우PlatformSettlementSupplyWithVatAmountExceededPortOnePaymentError
: 정산 요청 공급대가가 포트원 결제 내역의 공급대가를 초과한 경우PlatformSettlementAmountExceededError
: 정산 가능한 금액을 초과한 경우PlatformContractPlatformFixedAmountFeeCurrencyAndSettlementCurrencyMismatchedError
PlatformAdditionalFixedAmountFeeCurrencyAndSettlementCurrencyMismatchedError
PlatformCurrencyNotSupportedError
: 지원 되지 않는 통화를 선택한 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError
PlatformContractNotFoundError
PlatformAdditionalFeePoliciesNotFoundError
PlatformDiscountSharePoliciesNotFoundError
PlatformPaymentNotFoundError
PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우PlatformSettlementParameterNotFoundError
: 정산 파라미터가 존재하지 않는 경우
409
PlatformTransferAlreadyExistsError
주문 취소 정산건 생성
Request
Body
orderAmount, orderLines, all 중에서 하나만 입력하여야 합니다.
전체 금액 취소
주문 취소 항목과 취소 면세 금액을 같이 전달하시면 최종 취소 면세 금액은 주문 취소 항목의 면세 금액이 아닌 전달해주신 취소 면세 금액으로 적용됩니다.
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
외부 결제 상세 정보
기본값은 false 입니다.
Response
200
주문 취소 정산건
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
정산 상태
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
정산 금액과 정산 금액 계산에 사용된 금액 정보들 입니다.
계약은 플랫폼 고객사가 파트너에게 정산해줄 대금과 정산일을 계산하는 데 적용되는 정보입니다. 고객사의 플랫폼에서 재화 및 서비스를 판매하기 위한 중개수수료와 판매금에 대한 정산일로 구성되어 있습니다.
결제 정보
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
주문 취소 정보
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우PlatformOrderDetailMismatchedError
PlatformDiscountSharePolicyIdDuplicatedError
PlatformCancellableAmountExceededError
: 취소 가능한 금액이 초과한 경우PlatformCancellableDiscountAmountExceededError
PlatformCancellableDiscountTaxFreeAmountExceededError
PlatformProductIdDuplicatedError
PlatformCancellableProductQuantityExceededError
PlatformOrderTransferAlreadyCancelledError
PlatformSettlementAmountExceededError
: 정산 가능한 금액을 초과한 경우PlatformCancellationAndPaymentTypeMismatchedError
PlatformSettlementCancelAmountExceededPortOneCancelError
: 정산 취소 요청 금액이 포트원 결제 취소 내역의 취소 금액을 초과한 경우PlatformCannotSpecifyTransferError
: 정산 건 식별에 실패한 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformTransferNotFoundError
PlatformCancellationNotFoundError
PlatformPaymentNotFoundError
PlatformProductIdNotFoundError
PlatformTransferDiscountSharePolicyNotFoundError
PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우
409
PlatformTransferAlreadyExistsError
수기 정산건 생성
Request
Body
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
기본값은 false 입니다.
Response
200
수기 정산건
파트너는 고객사가 정산해주어야 할 대상입니다. 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.
정산 상태
날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우
403
PlatformNotEnabledError
: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우ForbiddenError
: 요청이 거절된 경우
404
PlatformPartnerNotFoundError
PlatformUserDefinedPropertyNotFoundError
: 사용자 정의 속성이 존재 하지 않는 경우
정산 상세 내역 다운로드
Request
body를 쿼리 문자열에 포함시켜 보낼 수 있습니다. 자세히 보기
Body
정산 시작일 범위와 정산 일 범위는 둘 중 하나만 입력 가능합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 태그를 하나 이상 가지는 파트너에 대한 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 계약 아이디를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 할인 분담 정책 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 추가 수수료 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 결제 수단을 가지는 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 채널 키를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 방식의 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 상태인 정산건만 조회합니다.
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 정산건만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
STATUS
정산 건 상태TRANSFER_ID
정산 건 아이디PARTNER_NAME
파트너 이름SETTLEMENT_DATE
정산 일SETTLEMENT_START_DATE
정산 시작 일TYPE
정산 구분PAYMENT_ID
결제 내역 아이디ORDER_NAME
주문 명PAYMENT_METHOD
결제 수단SETTLEMENT_AMOUNT
정산 금액SETTLEMENT_ORDER_AMOUNT
주문 금액SETTLEMENT_ORDER_TAX_FREE_AMOUNT
면세 주문 금액SETTLEMENT_PAYMENT_AMOUNT
결제 금액SETTLEMENT_PAYMENT_VAT_AMOUNT
결제 금액 부가세SETTLEMENT_PAYMENT_VAT_BURDEN_AMOUNT
결제 금액 부가세 부담금SETTLEMENT_PAYMENT_SUPPLY_AMOUNT
결제 공급가액SETTLEMENT_PAYMENT_TAX_FREE_AMOUNT
결제 면세액SETTLEMENT_PLATFORM_FEE_AMOUNT
중개 수수료SETTLEMENT_PLATFORM_FEE_VAT_AMOUNT
중개 수수료 부가세SETTLEMENT_DISCOUNT_AMOUNT
할인 금액SETTLEMENT_DISCOUNT_TAX_FREE_AMOUNT
면세 할인 금액SETTLEMENT_DISCOUNT_SHARE_AMOUNT
할인 분담금SETTLEMENT_DISCOUNT_SHARE_TAX_FREE_AMOUNT
면세 할인 분담금SETTLEMENT_ADDITIONAL_FEE_AMOUNT
추가 수수료SETTLEMENT_ADDITIONAL_FEE_VAT_AMOUNT
추가 수수료 부가세SETTLEMENT_CURRENCY
정산 통화PARTNER_TYPE
파트너 유형PARTNER_TAXATION_TYPE
파트너 과세 유형PARTNER_INCOME_TYPE
파트너 소득 유형PARTNER_TAXATION_TYPE_OR_INCOME_TYPE
파트너 과세 유형 또는 소득 유형파트너 유형이 사업자인 경우 과세 유형, 원천징수 대상자인 소득 유형입니다.
PARTNER_ID
파트너 아이디MEMO
메모Response
200
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우