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 를 통해 올바른 계좌인지 검증합니다. 그 외의 화폐일 경우 따로 검증하지는 않습니다.
플랫폼 파트너 상태
파트너 유형별 추가 정보
정산 상태
SETTLED
정산 완료SCHEDULED
정산 예약PAID_OUT
지급 완료IN_PROCESS
정산 중IN_PAYOUT
지급 중날짜를 나타내는 문자열로, yyyy-MM-dd
형식을 따릅니다.
통화 단위
OMR
Rial OmaniCUC
Peso ConvertibleBBD
Barbados DollarPLN
ZlotySVC
El Salvador ColonBMD
Bermudian DollarTJS
SomoniTND
Tunisian DinarGNF
Guinean FrancSDG
Sudanese PoundMRU
OuguiyaXBB
Bond Markets Unit European Monetary Unit (E.M.U.-6)PKR
Pakistan RupeeFKP
Falkland Islands PoundMUR
Mauritius RupeeXAF
CFA Franc BEACSAR
Saudi RiyalCAD
Canadian DollarHKD
Hong Kong DollarPYG
GuaraniMGA
Malagasy AriaryUYI
Uruguay Peso en Unidades Indexadas (UI)AUD
Australian DollarAMD
Armenian DramYER
Yemeni RialCHE
WIR EuroMMK
KyatSEK
Swedish KronaTRY
Turkish LiraXBC
Bond Markets Unit European Unit of Account 9 (E.U.A.-9)KES
Kenyan ShillingGEL
LariGTQ
QuetzalTZS
Tanzanian ShillingCUP
Cuban PesoALL
LekERN
NakfaBRL
Brazilian RealUGX
Uganda ShillingXUA
ADB Unit of AccountGIP
Gibraltar PoundMZN
Mozambique MeticalKRW
대한민국 원화JOD
Jordanian DinarIQD
Iraqi DinarVUV
VatuXXX
The codes assigned for transactions where no currency is involvedUZS
Uzbekistan SumBOV
MvdolUAH
HryvniaPEN
SolKMF
Comorian Franc DOP
Dominican PesoBDT
TakaLKR
Sri Lanka RupeeFJD
Fiji DollarLSL
LotiBSD
Bahamian DollarSRD
Surinam DollarXTS
Codes specifically reserved for testing purposesSHP
Saint Helena PoundLRD
Liberian DollarQAR
Qatari RialBND
Brunei DollarCDF
Congolese FrancSLE
LeoneUSN
US Dollar (Next day)VES
Bolívar SoberanoTMT
Turkmenistan New ManatCHW
WIR FrancBGN
Bulgarian LevJMD
Jamaican DollarSZL
LilangeniCZK
Czech KorunaZMW
Zambian KwachaUYU
Peso UruguayoNPR
Nepalese RupeeEGP
Egyptian PoundAZN
Azerbaijan ManatCLP
Chilean PesoMOP
PatacaSCR
Seychelles RupeeHTG
GourdeVND
DongLAK
Lao KipBTN
NgultrumGBP
Pound SterlingSSP
South Sudanese PoundXPD
PalladiumTWD
New Taiwan DollarDZD
Algerian DinarMXN
Mexican PesoXDR
SDR (Special Drawing Right)ZWL
Zimbabwe DollarAWG
Aruban FlorinTHB
BahtISK
Iceland KronaLBP
Lebanese PoundSGD
Singapore DollarMWK
Malawi KwachaKZT
TengeCRC
Costa Rican ColonWST
TalaDJF
Djibouti FrancLYD
Libyan DinarNGN
NairaBIF
Burundi FrancAED
UAE DirhamCHF
Swiss FrancRWF
Rwanda FrancXBD
Bond Markets Unit European Unit of Account 17 (E.U.A.-17)INR
Indian RupeeCLF
Unidad de FomentoXOF
CFA Franc BCEAOCOU
Unidad de Valor RealMXV
Mexican Unidad de Inversion (UDI)PGK
KinaCNY
Yuan RenminbiSYP
Syrian PoundVED
Bolívar SoberanoRON
Romanian LeuAFN
AfghaniPHP
Philippine PesoMDL
Moldovan LeuKHR
RielXPT
PlatinumCOP
Colombian PesoDKK
Danish KroneKYD
Cayman Islands DollarXPF
CFP FrancGMD
DalasiMVR
RufiyaaSTN
DobraTTD
Trinidad and Tobago DollarPAB
BalboaXAU
GoldXAG
SilverJPY
일본 엔화TOP
Pa’angaBWP
PulaMKD
DenarARS
Argentine PesoHUF
ForintMYR
Malaysian RinggitUSD
미국 달러SLL
LeoneMAD
Moroccan DirhamRUB
Russian RubleMNT
TugrikBOB
BolivianoGYD
Guyana DollarSBD
Solomon Islands DollarXBA
Bond Markets Unit European Composite Unit (EURCO)BHD
Bahraini DinarHNL
LempiraUYW
Unidad PrevisionalNZD
New Zealand DollarXCD
East Caribbean DollarXSU
SucreKGS
SomAOA
KwanzaBZD
Belize DollarIDR
RupiahSOS
Somali ShillingNIO
Cordoba OroGHS
Ghana CediANG
Netherlands Antillean GuilderRSD
Serbian DinarILS
New Israeli SheqelNOK
Norwegian KroneKWD
Kuwaiti DinarNAD
Namibia DollarETB
Ethiopian BirrBYN
Belarusian RubleKPW
North Korean WonEUR
EuroCVE
Cabo Verde EscudoZAR
RandIRR
Iranian RialHRK
Kuna (Replaced by EUR)BAM
Convertible Mark400
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
정산 시작일 범위와 정산 일 범위는 둘 중 하나만 입력 가능합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 태그를 하나 이상 가지는 파트너에 대한 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 계약 아이디를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 할인 분담 정책 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 추가 수수료 아이디를 하나 이상 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 결제 수단을 가지는 파트너만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 채널 키를 가지는 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 방식의 정산건만 조회합니다.
하나 이상의 값이 존재하는 경우 해당 리스트에 포함되는 정산 상태인 정산건만 조회합니다.
검색 키워드 적용을 위한 옵션으로, 명시된 키워드를 포함하는 정산건만 조회합니다. 하나의 하위 필드에만 값을 명시하여 요청합니다.
TAXATION_TYPE_OR_INCOME_TYPE
과세 유형 또는 소득 유형파트너 유형이 사업자인 경우 과세 유형, 원천징수 대상자인 소득 유형입니다.
SETTLEMENT_DISCOUNT_SHARE_AMOUNT
할인 분담금PAYMENT_ID
결제 내역 아이디SETTLEMENT_DISCOUNT_AMOUNT
할인 금액INCOME_TYPE
소득 유형SETTLEMENT_PAYMENT_SUPPLY_AMOUNT
결제 공급가액STATUS
정산 건 상태SETTLEMENT_DISCOUNT_SHARE_TAX_FREE_AMOUNT
면세 할인 분담금SETTLEMENT_ORDER_AMOUNT
주문 금액TRANSFER_ID
정산 건 아이디PARTNER_TYPE
파트너 유형SETTLEMENT_DISCOUNT_TAX_FREE_AMOUNT
면세 할인 금액ORDER_NAME
주문 명SETTLEMENT_TAX_FREE_AMOUNT
결제 면세액해당 필드는 deprecated되어 9월까지만 유지되고 이후 삭제될 예정입니다. 대신 SETTLEMENT_PAYMENT_TAX_FREE_AMOUNT 필드를 사용해주세요.
SETTLEMENT_ADDITIONAL_FEE_VAT_AMOUNT
추가 수수료 부가세SETTLEMENT_CURRENCY
정산 통화PARTNER_NAME
파트너 이름SETTLEMENT_PLATFORM_FEE_VAT_AMOUNT
중개 수수료 부가세PAYMENT_METHOD
결제 수단SETTLEMENT_PAYMENT_AMOUNT
결제 금액SETTLEMENT_START_DATE
정산 시작 일SETTLEMENT_ORDER_TAX_FREE_AMOUNT
면세 주문 금액SETTLEMENT_PAYMENT_VAT_BURDEN_AMOUNT
결제 금액 부가세 부담금SETTLEMENT_PAYMENT_TAX_FREE_AMOUNT
결제 면세액SETTLEMENT_DATE
정산 일SETTLEMENT_SUPPLY_AMOUNT
결제 공급가액해당 필드는 deprecated되어 9월까지만 유지되고 이후 삭제될 예정입니다. 대신 SETTLEMENT_PAYMENT_SUPPLY_AMOUNT 필드를 사용해주세요.
SETTLEMENT_ADDITIONAL_FEE_AMOUNT
추가 수수료SETTLEMENT_PAYMENT_VAT_AMOUNT
결제 금액 부가세SETTLEMENT_AMOUNT
정산 금액SETTLEMENT_PLATFORM_FEE_AMOUNT
중개 수수료TAXATION_TYPE
과세 유형TYPE
정산 구분Response
200
400
InvalidRequestError
: 요청된 입력 정보가 유효하지 않은 경우
401
UnauthorizedError
: 인증 정보가 올바르지 않은 경우