개발자센터
V1
V2
API & SDK
릴리즈 노트 기술 블로그

PortOne REST API - V2

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

V2 API hostname: api.portone.io

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

요청 및 응답 형식

요청과 응답의 본문은 JSON 형식입니다.
API 응답에 포함된 필드는 별도 안내 없이 추가될 수 있으니, 알지 못하는 필드가 있는 경우에는 무시하도록 개발해 주세요.

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

인증 방식

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

인증 관련 API를 제외한 모든 API는 HTTP Authorization 헤더로 인증 정보를 전달해 주셔야 합니다. Authorization 헤더에 전달하는 형식은 두 가지 중 하나입니다.

  • API Secret 직접 사용 (간편)
    Authorization: PortOne MY_API_SECRET
  • 액세스 토큰 사용
    Authorization: Bearer MY_ACCESS_TOKEN
액세스 토큰을 사용한 인증을 원하는 경우, 인증 관련 API를 이용해 주세요.

GET 요청 시 Body 대신 Query 사용

GET 요청 시에 Body를 사용해야 하는 경우, Body 대신 Query를 사용할 수 있습니다.

이 경우, Body 객체를 requestBody Query 필드에 넣어주시면 됩니다.

인증 관련 API

인증과 관련된 API 기능을 제공합니다.

결제 관련 API

결제와 관련된 API 기능을 제공합니다.

목차

결제 정보 사전 등록
post/payments/{paymentId}/pre-register
결제 단건 조회
get/payments/{paymentId}
결제 다건 조회(페이지 기반)
get/payments
결제 대용량 다건 조회(커서 기반)
get/payments-by-cursor
결제 취소
post/payments/{paymentId}/cancel
빌링키 결제
post/payments/{paymentId}/billing-key
수기 결제
post/payments/{paymentId}/instant
가상계좌 말소
post/payments/{paymentId}/virtual-account/close
에스크로 배송 정보 등록
post/payments/{paymentId}/escrow/logistics
에스크로 배송 정보 수정
patch/payments/{paymentId}/escrow/logistics
에스크로 구매 확정
post/payments/{paymentId}/escrow/complete
웹훅 재발송
post/payments/{paymentId}/resend-webhook
영수증 내 하위 상점 거래 등록 API
post/payments/{paymentId}/register-store-receipt

결제 예약 관련 API

결제 예약과 관련된 API 기능을 제공합니다.

빌링키 관련 API

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

현금 영수증 관련 API

현금 영수증과 관련된 API 기능을 제공합니다.

본인인증 관련 API

본인인증과 관련된 API 기능을 제공합니다.

B2B 서비스 API

B2B 관련 API 기능을 제공합니다. alpha 버전의 API 로서, 사용을 원하실 경우 관리자콘솔 및 홈페이지를 통해 문의해주세요.

목차

연동 사업자 조회
get/b2b-preview/member-companies/{brn}
연동 사업자 정보 수정
patch/b2b-preview/member-companies/{brn}
사업자 연동
post/b2b-preview/member-companies
담당자 조회
get/b2b-preview/member-companies/{brn}/contacts/{contactId}
담당자 정보 수정
patch/b2b-preview/member-companies/{brn}/contacts/{contactId}
사업자 인증서 등록 URL 조회
get/b2b-preview/member-companies/{brn}/certificate/registration-url
인증서 조회
get/b2b-preview/member-companies/{brn}/certificate
담당자 ID 존재 여부 확인
get/b2b-preview/member-companies/contacts/id-existence
예금주 조회
get/b2b-preview/bank-accounts/{bank}/{accountNumber}/holder
사업자 상태 조회
get/b2b-preview/company/{brn}/state
세금계산서 역발행 요청
post/b2b-preview/tax-invoices/request-reverse-issuance
세금 계산서 조회
get/b2b-preview/tax-invoices/{documentKey}
세금계산서 삭제
delete/b2b-preview/tax-invoices/{documentKey}
세금계산서 발행
post/b2b-preview/tax-invoices/issue
세금계산서 역발행 요청 취소
post/b2b-preview/tax-invoices/cancel-request
세금계산서 역발행 취소
post/b2b-preview/tax-invoices/cancel-issuance
세금계산서 역발행 요청 거부
post/b2b-preview/tax-invoices/refuse-request
세금 계산서 다건조회
get/b2b-preview/tax-invoices
세금 계산서 팝업 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/popup-url
세금 계산서 프린트 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/print-url
세금 계산서 PDF 다운로드 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/pdf-download-url
세금계산서 임시 저장
post/b2b-preview/tax-invoices/register
세금계산서 역발행 요청
post/b2b-preview/tax-invoices/request
세금계산서 파일 업로드 링크 생성
post/b2b-preview/tax-invoices/file-upload-link
세금계산서 파일 첨부
post/b2b-preview/tax-invoices/attach-file
세금계산서 첨부파일 목록 조회
get/b2b-preview/tax-invoices/{documentKey}/attachments
세금계산서 첨부파일 삭제
delete/b2b-preview/tax-invoices/{documentKey}/attachments/{attachmentId}

특정 PG사 관련 API

특정 PG사에 국한된 API 기능을 제공합니다.

타입 정의

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