PortOne REST API - V2
API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.
V2 API hostname: api.portone.io
요청 및 응답 형식
요청과 응답의 본문은 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
인증과 관련된 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
B2B 서비스 API
B2B 관련 API 기능을 제공합니다. alpha 버전의 API 로서, 사용을 원하실 경우 관리자콘솔 및 홈페이지를 통해 문의해주세요.
목차
연동 사업자 조회
get/b2b-preview/member-companies/{brn}사업자 연동
post/b2b-preview/member-companies담당자 조회
get/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특정 PG사 관련 API
특정 PG사에 국한된 API 기능을 제공합니다.
get/kakaopay/payment/order
카카오페이 주문 조회 API
주어진 아이디에 대응되는 카카오페이 주문 건을 조회합니다. 해당 API 사용이 필요한 경우 포트원 기술지원팀으로 문의 주시길 바랍니다.
Request
Query
pgTxId: string
카카오페이 주문 번호 (tid)
카카오페이 주문 번호 (tid)
channelKey: string
채널키
채널키
Response
200
성공 응답으로 카카오페이 주문 조회 응답 객체를 반환합니다.
statusCode: integer (32 bit)
HTTP 상태 코드
body: string
HTTP 응답 본문 (JSON)
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
타입 정의
API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
AddressAlreadyPaidErrorAlreadyPaidOrWaitingErrorApplyEscrowLogisticsErrorApplyEscrowLogisticsResponseB2bBankAccountNotFoundErrorB2bCertificateB2bCertificateTypeB2bCertificateUnregisteredErrorB2bCompanyAlreadyRegisteredErrorB2bCompanyContactB2bCompanyContactInputB2bCompanyNotFoundErrorB2bCompanyStateB2bCompanyStateBusinessStatusB2bCompanyStateTaxationTypeB2bContactNotFoundErrorB2bExternalServiceErrorB2bFinancialSystemCommunicationErrorB2bFinancialSystemFailureErrorB2bFinancialSystemUnderMaintenanceErrorB2bForeignExchangeAccountErrorB2bHometaxUnderMaintenanceErrorB2bIdAlreadyExistsErrorB2bMemberCompanyB2bMemberCompanyNotFoundErrorB2bModificationB2bNotEnabledErrorB2bRecipientNotFoundErrorB2bRegularMaintenanceTimeErrorB2bSearchDateTypeB2bSupplierNotFoundErrorB2bSuspendedAccountErrorB2bTaxInvoiceB2bTaxInvoiceAdditionalContactB2bTaxInvoiceBeforeSendingB2bTaxInvoiceCompanyB2bTaxInvoiceContactB2bTaxInvoiceDocumentKeyTypeB2bTaxInvoiceInputB2bTaxInvoiceIssuanceCancelledB2bTaxInvoiceIssuedB2bTaxInvoiceItemB2bTaxInvoiceModificationTypeB2bTaxInvoiceNoRecipientDocumentKeyErrorB2bTaxInvoiceNoSupplierDocumentKeyErrorB2bTaxInvoiceNonDeletableStatusErrorB2bTaxInvoiceNotFoundErrorB2bTaxInvoiceNotIssuedStatusErrorB2bTaxInvoiceNotRegisteredStatusErrorB2bTaxInvoiceNotRequestedStatusErrorB2bTaxInvoicePurposeTypeB2bTaxInvoiceRegisteredB2bTaxInvoiceRequestCancelledB2bTaxInvoiceRequestRefusedB2bTaxInvoiceRequestedB2bTaxInvoiceSendingB2bTaxInvoiceSendingCompletedB2bTaxInvoiceSendingFailedB2bTaxInvoiceStatusB2bTaxInvoiceSummaryB2bTaxInvoiceWaitingSendingB2bTaxTypeBankBeforeRegisteredPaymentEscrowBillingKeyAlreadyDeletedErrorBillingKeyInfoBillingKeyInfoSummaryBillingKeyNotFoundErrorBillingKeyNotIssuedErrorBillingKeyPaymentInputBillingKeyPaymentMethodBillingKeyPaymentMethodCardBillingKeyPaymentMethodEasyPayBillingKeyPaymentMethodEasyPayChargeBillingKeyPaymentMethodEasyPayMethodBillingKeyPaymentMethodMobileBillingKeyPaymentMethodPaypalBillingKeyPaymentMethodTransferBillingKeyPaymentSummaryCancelAmountExceedsCancellableAmountErrorCancelB2bTaxInvoiceIssuanceErrorCancelB2bTaxInvoiceRequestErrorCancelCashReceiptErrorCancelCashReceiptResponseCancelPaymentBodyRefundAccountCancelPaymentErrorCancelPaymentResponseCancelTaxAmountExceedsCancellableTaxAmountErrorCancelTaxFreeAmountExceedsCancellableTaxFreeAmountErrorCancellableAmountConsistencyBrokenErrorCancelledCashReceiptCancelledPaymentCancelledPaymentCashReceiptCancelledPaymentEscrowCardCardBrandCardCredentialCardOwnerTypeCardTypeCashReceiptCashReceiptAlreadyIssuedErrorCashReceiptInputCashReceiptInputTypeCashReceiptNotFoundErrorCashReceiptNotIssuedErrorCashReceiptSummaryCashReceiptTypeChannelNotFoundErrorCloseVirtualAccountErrorCloseVirtualAccountResponseConfirmEscrowErrorConfirmEscrowResponseConfirmIdentityVerificationErrorConfirmIdentityVerificationResponseConfirmedPaymentEscrowCountryCreatePaymentScheduleErrorCreatePaymentScheduleResponseCurrencyCustomerCustomerInputCustomerNameInputCustomerSeparatedNameDateTimeRangeDeleteB2bTaxInvoiceErrorDeleteBillingKeyErrorDeleteBillingKeyResponseDeliveredPaymentEscrowEasyPayProviderFailedIdentityVerificationFailedPaymentFailedPaymentCancellationFailedPaymentScheduleForbiddenErrorGenderGetAllPaymentsByCursorResponseGetAllPaymentsErrorGetB2bAccountHolderErrorGetB2bBankAccountHolderResponseGetB2bCertificateErrorGetB2bCertificateRegistrationUrlErrorGetB2bCertificateRegistrationUrlResponseGetB2bCompanyStateErrorGetB2bContactIdExistenceResponseGetB2bMemberCompanyContactErrorGetB2bMemberCompanyErrorGetB2bTaxInvoiceErrorGetB2bTaxInvoicePdfDownloadUrlErrorGetB2bTaxInvoicePdfDownloadUrlResponseGetB2bTaxInvoicePopupUrlErrorGetB2bTaxInvoicePopupUrlResponseGetB2bTaxInvoicePrintUrlErrorGetB2bTaxInvoicePrintUrlResponseGetB2bTaxInvoicesErrorGetB2bTaxInvoicesResponseGetBillingKeyInfoErrorGetCashReceiptErrorGetIdentityVerificationErrorGetKakaopayPaymentOrderErrorGetKakaopayPaymentOrderResponseGetPaymentErrorGetPaymentScheduleErrorGetPaymentSchedulesErrorGetPaymentSchedulesResponseGetPaymentsErrorGetPaymentsResponseIdentityVerificationIdentityVerificationAlreadySentErrorIdentityVerificationAlreadyVerifiedErrorIdentityVerificationMethodIdentityVerificationNotFoundErrorIdentityVerificationNotSentErrorIdentityVerificationOperatorIdentityVerificationRequestedCustomerIdentityVerificationVerifiedCustomerInstantBillingKeyPaymentMethodInputInstantBillingKeyPaymentMethodInputCardInstantPaymentMethodInputInstantPaymentMethodInputCardInstantPaymentMethodInputVirtualAccountInstantPaymentMethodInputVirtualAccountCashReceiptInfoInstantPaymentMethodInputVirtualAccountExpiryInstantPaymentMethodInputVirtualAccountOptionInstantPaymentMethodInputVirtualAccountOptionFixedInstantPaymentMethodInputVirtualAccountOptionTypeInstantPaymentSummaryInvalidRequestErrorIssueB2bTaxInvoiceErrorIssueBillingKeyErrorIssueBillingKeyResponseIssueCashReceiptCustomerInputIssueCashReceiptErrorIssueCashReceiptResponseIssueFailedCashReceiptIssuedCashReceiptIssuedPaymentCashReceiptLoginViaApiSecretErrorLoginViaApiSecretResponseModifyEscrowLogisticsErrorModifyEscrowLogisticsResponseOneLineAddressPageInfoPageInputPaidPaymentPartialCancelledPaymentPastPaymentScheduleErrorPayInstantlyErrorPayInstantlyResponsePayPendingPaymentPayWithBillingKeyErrorPayWithBillingKeyResponsePaymentPaymentAlreadyCancelledErrorPaymentAmountPaymentAmountInputPaymentCancellationPaymentCashReceiptPaymentCashReceiptStatusPaymentClientTypePaymentEscrowPaymentEscrowReceiverInputPaymentEscrowSenderInputPaymentFilterInputPaymentFilterInputEscrowStatusPaymentInstallmentPaymentLogisticsPaymentLogisticsCompanyPaymentMethodPaymentMethodCardPaymentMethodEasyPayPaymentMethodEasyPayMethodPaymentMethodEasyPayMethodChargePaymentMethodGiftCertificatePaymentMethodGiftCertificateTypePaymentMethodMobilePaymentMethodTransferPaymentMethodTypePaymentMethodVirtualAccountPaymentMethodVirtualAccountRefundStatusPaymentMethodVirtualAccountTypePaymentNotFoundErrorPaymentNotPaidErrorPaymentNotWaitingForDepositErrorPaymentProductPaymentProductTypePaymentSchedulePaymentScheduleAlreadyExistsErrorPaymentScheduleAlreadyProcessedErrorPaymentScheduleAlreadyRevokedErrorPaymentScheduleFilterInputPaymentScheduleNotFoundErrorPaymentScheduleStatusPaymentScheduleSummaryPaymentSortByPaymentSortOrderPaymentStatusPaymentTextSearchPaymentTextSearchFieldPaymentTimestampTypePaymentWebhookPaymentWebhookPaymentStatusPaymentWebhookRequestPaymentWebhookResponsePaymentWebhookStatusPaymentWebhookTriggerPaymentWithCursorPgProviderPgProviderErrorPortOneVersionPreRegisterPaymentErrorPreRegisterPaymentResponseReadyIdentityVerificationReadyPaymentRefreshTokenErrorRefreshTokenResponseRefuseB2bTaxInvoiceRequestErrorRegisterB2bMemberCompanyErrorRegisterB2bMemberCompanyResponseRegisterStoreReceiptBodyItemRegisterStoreReceiptErrorRegisterStoreReceiptResponseRegisteredPaymentEscrowRejectConfirmedPaymentEscrowRejectedPaymentEscrowRequestB2bTaxInvoiceRegisterErrorRequestB2bTaxInvoiceReverseIssuanceErrorRequestedPaymentCancellationResendIdentityVerificationErrorResendIdentityVerificationResponseResendWebhookErrorResendWebhookResponseRevokePaymentScheduleErrorRevokePaymentScheduleResponseRevokedPaymentScheduleScheduledPaymentScheduleSelectedChannelSelectedChannelTypeSendIdentityVerificationBodyCustomerSendIdentityVerificationErrorSendIdentityVerificationResponseSeparatedAddressSeparatedAddressInputStartedPaymentScheduleSucceededPaymentCancellationSucceededPaymentScheduleSumOfPartsExceedsCancelAmountErrorSumOfPartsExceedsTotalAmountErrorUnauthorizedErrorVerifiedIdentityVerificationVirtualAccountIssuedPaymentWebhookNotFoundErrorgetB2bContactIdExistenceErrorrequestB2bTaxInvoiceError