개발자센터
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를 이용해 주세요.

인증 관련 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 기능을 제공합니다.

get/identity-verifications/{identityVerificationId}

본인인증 단건 조회

주어진 아이디에 대응되는 본인인증 내역을 조회합니다.

Request

Path

identityVerificationId: string
조회할 본인인증 아이디

조회할 본인인증 아이디

Query

storeId?: string
상점 아이디
(Optional)

접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.

Response

200

성공 응답으로 본인 인증 객체를 반환합니다.

status: string (Union Tag)
본인인증 상태
필드의 값이 일 때 타입은 FailedIdentityVerification 입니다.
id: string
본인인증 내역 아이디
channel?: SelectedChannel
(결제, 본인인증 등에) 선택된 채널 정보
(Optional)

(결제, 본인인증 등에) 선택된 채널 정보

type: SelectedChannelType
채널 타입

채널 타입

id?: string
채널 아이디
(Optional)
key?: string
채널 키
(Optional)
name?: string
채널 명
(Optional)
pgProvider: PgProvider
PG사 결제 모듈

PG사 결제 모듈

pgMerchantId: string
PG사 가맹점 식별 아이디
requestedCustomer: IdentityVerificationRequestedCustomer
요청 시 고객 정보

요청 시 고객 정보

id?: string
식별 아이디
(Optional)
name?: string
이름
(Optional)
phoneNumber?: string
전화번호
(Optional)

특수 문자(-) 없이 숫자로만 이루어진 번호 형식입니다.

customData?: string
사용자 지정 데이터
(Optional)
requestedAt: string (RFC 3339 date-time)
본인인증 요청 시점
updatedAt: string (RFC 3339 date-time)
업데이트 시점
statusChangedAt: string (RFC 3339 date-time)
상태 업데이트 시점

400

  • InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)

401

  • UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)

404

  • IdentityVerificationNotFoundError: 요청된 본인인증 건이 존재하지 않는 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
post/identity-verifications/{identityVerificationId}/send

본인인증 요청 전송

SMS 또는 APP 방식을 이용하여 본인인증 요청을 전송합니다.

Request

Path

identityVerificationId: string
본인인증 아이디

본인인증 아이디

Body

storeId?: string
상점 아이디
(Optional)

접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.

channelKey: string
채널 키
customer: SendIdentityVerificationBodyCustomer
본인인증 요청을 위한 고객 정보

본인인증 요청을 위한 고객 정보

id?: string
식별 아이디
(Optional)
name: string
이름
phoneNumber: string
전화번호

특수 문자(-) 없이 숫자만 입력합니다.

identityNumber?: string
주민등록번호 앞 7자리
(Optional)

SMS 방식의 경우 필수로 입력합니다.

customData?: string
사용자 지정 데이터
(Optional)
bypass?: object
PG사별 추가 파라미터 ("PG사별 연동 가이드" 참고)
(Optional)
operator: IdentityVerificationOperator
본인인증 통신사

본인인증 통신사

SKTSKT
KTKT
KT_MVNOKT 알뜰폰
LGU_MVNOLGU 알뜰폰
SKT_MVNOSKT 알뜰폰
LGULGU
method: IdentityVerificationMethod
본인인증 방식

본인인증 방식

SMS
APP

Response

200

성공 응답

400

  • InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)

401

  • UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)

404

  • IdentityVerificationNotFoundError: 요청된 본인인증 건이 존재하지 않는 경우
  • ChannelNotFoundError: 요청된 채널이 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 ChannelNotFoundError 입니다.
message?: string
(Optional)

409

  • IdentityVerificationAlreadyVerifiedError: 본인인증 건이 이미 인증 완료된 상태인 경우
  • IdentityVerificationAlreadySentError: 본인인증 건이 이미 API로 요청된 상태인 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 IdentityVerificationAlreadySentError 입니다.
message?: string
(Optional)

502

  • PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Response Status: N/A
N/A
post/identity-verifications/{identityVerificationId}/confirm

본인인증 확인

요청된 본인인증에 대한 확인을 진행합니다.

Request

Path

identityVerificationId: string
본인인증 아이디

본인인증 아이디

Body

storeId?: string
상점 아이디
(Optional)

접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.

otp?: string
OTP (One-Time Password)
(Optional)

SMS 방식에서만 사용됩니다.

Response

200

성공 응답

identityVerification: VerifiedIdentityVerification
완료된 본인인증 내역

완료된 본인인증 내역

status: string
본인인증 상태
id: string
본인인증 내역 아이디
channel?: SelectedChannel
(결제, 본인인증 등에) 선택된 채널 정보
(Optional)

(결제, 본인인증 등에) 선택된 채널 정보

verifiedCustomer: IdentityVerificationVerifiedCustomer
인증된 고객 정보

인증된 고객 정보

customData?: string
사용자 지정 데이터
(Optional)
requestedAt: string (RFC 3339 date-time)
본인인증 요청 시점
updatedAt: string (RFC 3339 date-time)
업데이트 시점
statusChangedAt: string (RFC 3339 date-time)
상태 업데이트 시점
verifiedAt: string (RFC 3339 date-time)
본인인증 완료 시점
pgTxId: string
본인인증 내역 PG사 아이디
pgRawResponse: string
PG사 응답 데이터

400

  • InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)

401

  • UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)

404

  • IdentityVerificationNotFoundError: 요청된 본인인증 건이 존재하지 않는 경우
  • IdentityVerificationNotSentError: 본인인증 건이 API로 요청된 상태가 아닌 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 IdentityVerificationNotFoundError 입니다.
message?: string
(Optional)

409

  • IdentityVerificationAlreadyVerifiedError: 본인인증 건이 이미 인증 완료된 상태인 경우
type: string
message?: string
(Optional)

502

  • PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Response Status: N/A
N/A
post/identity-verifications/{identityVerificationId}/resend

SMS 본인인증 요청 재전송

SMS 본인인증 요청을 재전송합니다.

Request

Path

identityVerificationId: string
본인인증 아이디

본인인증 아이디

Query

storeId?: string
상점 아이디
(Optional)

접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.

Response

200

성공 응답

400

  • InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)

401

  • UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)

404

  • IdentityVerificationNotFoundError: 요청된 본인인증 건이 존재하지 않는 경우
  • IdentityVerificationNotSentError: 본인인증 건이 API로 요청된 상태가 아닌 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 IdentityVerificationNotFoundError 입니다.
message?: string
(Optional)

409

  • IdentityVerificationAlreadyVerifiedError: 본인인증 건이 이미 인증 완료된 상태인 경우
type: string
message?: string
(Optional)

502

  • PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Response Status: N/A
N/A

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 기능을 제공합니다.

타입 정의

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