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

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를 이용해 주세요.

GET 요청 시 Body 대신 Query 사용

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

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


인증 관련 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)

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

채널 타입

채널 타입

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

PG사 결제 모듈

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

요청 시 고객 정보

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
Request Sample
N/A
post/identity-verifications/{identityVerificationId}/send

본인인증 요청 전송

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

Request

Path

identityVerificationId: string
본인인증 아이디

본인인증 아이디

Body

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

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


channelKey: string
채널 키

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

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

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

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

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

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


customData?: string
사용자 지정 데이터
(Optional)

bypass?: object
PG사별 추가 파라미터 ("PG사별 연동 가이드" 참고)
(Optional)

본인인증 통신사

본인인증 통신사

SKTSKT
KTKT
KT_MVNOKT 알뜰폰
LGU_MVNOLGU 알뜰폰
SKT_MVNOSKT 알뜰폰
LGULGU

본인인증 방식

본인인증 방식

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
Request Sample
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)

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

인증된 고객 정보

인증된 고객 정보

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
Request Sample
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
Request Sample
N/A

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 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
AddressAlreadyPaidErrorAlreadyPaidOrWaitingErrorApplyEscrowLogisticsErrorApplyEscrowLogisticsResponseAttachB2bTaxInvoiceFileErrorB2bBankAccountNotFoundErrorB2bCertificateB2bCertificateTypeB2bCertificateUnregisteredErrorB2bCompanyAlreadyRegisteredErrorB2bCompanyContactB2bCompanyContactInputB2bCompanyNotFoundErrorB2bCompanyStateB2bCompanyStateBusinessStatusB2bCompanyStateTaxationTypeB2bContactNotFoundErrorB2bExternalServiceErrorB2bFileNotFoundErrorB2bFinancialSystemCommunicationErrorB2bFinancialSystemFailureErrorB2bFinancialSystemUnderMaintenanceErrorB2bForeignExchangeAccountErrorB2bHometaxUnderMaintenanceErrorB2bIdAlreadyExistsErrorB2bMemberCompanyB2bMemberCompanyNotFoundErrorB2bModificationB2bNotEnabledErrorB2bRecipientNotFoundErrorB2bRegularMaintenanceTimeErrorB2bSearchDateTypeB2bSupplierNotFoundErrorB2bSuspendedAccountErrorB2bTaxInvoiceB2bTaxInvoiceAdditionalContactB2bTaxInvoiceAttachmentB2bTaxInvoiceAttachmentNotFoundErrorB2bTaxInvoiceBeforeSendingB2bTaxInvoiceCompanyB2bTaxInvoiceContactB2bTaxInvoiceDocumentKeyTypeB2bTaxInvoiceInputB2bTaxInvoiceIssuanceCancelledB2bTaxInvoiceIssuedB2bTaxInvoiceItemB2bTaxInvoiceModificationTypeB2bTaxInvoiceNoRecipientDocumentKeyErrorB2bTaxInvoiceNoSupplierDocumentKeyErrorB2bTaxInvoiceNonDeletableStatusErrorB2bTaxInvoiceNotFoundErrorB2bTaxInvoiceNotIssuedStatusErrorB2bTaxInvoiceNotRegisteredStatusErrorB2bTaxInvoiceNotRequestedStatusErrorB2bTaxInvoicePurposeTypeB2bTaxInvoiceRegisteredB2bTaxInvoiceRequestCancelledB2bTaxInvoiceRequestRefusedB2bTaxInvoiceRequestedB2bTaxInvoiceSendingB2bTaxInvoiceSendingCompletedB2bTaxInvoiceSendingFailedB2bTaxInvoiceStatusB2bTaxInvoiceSummaryB2bTaxInvoiceWaitingSendingB2bTaxTypeBankBeforeRegisteredPaymentEscrowBillingKeyAlreadyDeletedErrorBillingKeyInfoBillingKeyInfoSummaryBillingKeyNotFoundErrorBillingKeyNotIssuedErrorBillingKeyPaymentInputBillingKeyPaymentMethodBillingKeyPaymentMethodCardBillingKeyPaymentMethodEasyPayBillingKeyPaymentMethodEasyPayChargeBillingKeyPaymentMethodEasyPayMethodBillingKeyPaymentMethodMobileBillingKeyPaymentMethodPaypalBillingKeyPaymentMethodTransferBillingKeyPaymentSummaryCancelAmountExceedsCancellableAmountErrorCancelB2bTaxInvoiceIssuanceErrorCancelB2bTaxInvoiceRequestErrorCancelCashReceiptErrorCancelCashReceiptResponseCancelPaymentBodyRefundAccountCancelPaymentErrorCancelPaymentResponseCancelRequesterCancelTaxAmountExceedsCancellableTaxAmountErrorCancelTaxFreeAmountExceedsCancellableTaxFreeAmountErrorCancellableAmountConsistencyBrokenErrorCancelledCashReceiptCancelledPaymentCancelledPaymentCashReceiptCancelledPaymentEscrowCardCardBrandCardCredentialCardOwnerTypeCardTypeCashReceiptCashReceiptAlreadyIssuedErrorCashReceiptInputCashReceiptInputTypeCashReceiptNotFoundErrorCashReceiptNotIssuedErrorCashReceiptSummaryCashReceiptTypeChannelNotFoundErrorCloseVirtualAccountErrorCloseVirtualAccountResponseConfirmEscrowErrorConfirmEscrowResponseConfirmIdentityVerificationErrorConfirmIdentityVerificationResponseConfirmedPaymentEscrowCountryCreateB2bTaxInvoiceFileUploadLinkCreateErrorCreateB2bTaxInvoiceFileUploadLinkResponseCreatePaymentScheduleErrorCreatePaymentScheduleResponseCurrencyCustomerCustomerInputCustomerNameInputCustomerSeparatedNameDateTimeRangeDeleteB2bTaxInvoiceAttachmentErrorDeleteB2bTaxInvoiceErrorDeleteBillingKeyErrorDeleteBillingKeyResponseDeliveredPaymentEscrowEasyPayProviderFailedIdentityVerificationFailedPaymentFailedPaymentCancellationFailedPaymentScheduleForbiddenErrorGenderGetAllPaymentsByCursorResponseGetAllPaymentsErrorGetB2bAccountHolderErrorGetB2bBankAccountHolderResponseGetB2bCertificateErrorGetB2bCertificateRegistrationUrlErrorGetB2bCertificateRegistrationUrlResponseGetB2bCompanyStateErrorGetB2bContactIdExistenceResponseGetB2bMemberCompanyContactErrorGetB2bMemberCompanyErrorGetB2bTaxInvoiceAttachmentsErrorGetB2bTaxInvoiceAttachmentsResponseGetB2bTaxInvoiceErrorGetB2bTaxInvoicePdfDownloadUrlErrorGetB2bTaxInvoicePdfDownloadUrlResponseGetB2bTaxInvoicePopupUrlErrorGetB2bTaxInvoicePopupUrlResponseGetB2bTaxInvoicePrintUrlErrorGetB2bTaxInvoicePrintUrlResponseGetB2bTaxInvoicesErrorGetB2bTaxInvoicesResponseGetBillingKeyInfoErrorGetCashReceiptErrorGetIdentityVerificationErrorGetKakaopayPaymentOrderErrorGetKakaopayPaymentOrderResponseGetPaymentErrorGetPaymentScheduleErrorGetPaymentSchedulesErrorGetPaymentSchedulesResponseGetPaymentsErrorGetPaymentsResponseIdentityVerificationIdentityVerificationAlreadySentErrorIdentityVerificationAlreadyVerifiedErrorIdentityVerificationMethodIdentityVerificationNotFoundErrorIdentityVerificationNotSentErrorIdentityVerificationOperatorIdentityVerificationRequestedCustomerIdentityVerificationVerifiedCustomerInstantBillingKeyPaymentMethodInputInstantBillingKeyPaymentMethodInputCardInstantPaymentMethodInputInstantPaymentMethodInputCardInstantPaymentMethodInputVirtualAccountInstantPaymentMethodInputVirtualAccountCashReceiptInfoInstantPaymentMethodInputVirtualAccountExpiryInstantPaymentMethodInputVirtualAccountOptionInstantPaymentMethodInputVirtualAccountOptionFixedInstantPaymentMethodInputVirtualAccountOptionTypeInstantPaymentSummaryInvalidRequestErrorIssueB2bTaxInvoiceErrorIssueBillingKeyErrorIssueBillingKeyResponseIssueCashReceiptCustomerInputIssueCashReceiptErrorIssueCashReceiptResponseIssueFailedCashReceiptIssuedCashReceiptIssuedPaymentCashReceiptLoginViaApiSecretErrorLoginViaApiSecretResponseModifyEscrowLogisticsErrorModifyEscrowLogisticsResponseOneLineAddressPageInfoPageInputPaidPaymentPartialCancelledPaymentPayInstantlyErrorPayInstantlyResponsePayPendingPaymentPayWithBillingKeyErrorPayWithBillingKeyResponsePaymentPaymentAlreadyCancelledErrorPaymentAmountPaymentAmountInputPaymentCancellationPaymentCashReceiptPaymentCashReceiptStatusPaymentClientTypePaymentEscrowPaymentEscrowReceiverInputPaymentEscrowSenderInputPaymentFilterInputPaymentFilterInputEscrowStatusPaymentInstallmentPaymentLogisticsPaymentLogisticsCompanyPaymentMethodPaymentMethodCardPaymentMethodEasyPayPaymentMethodEasyPayMethodPaymentMethodEasyPayMethodChargePaymentMethodGiftCertificatePaymentMethodGiftCertificateTypePaymentMethodMobilePaymentMethodTransferPaymentMethodTypePaymentMethodVirtualAccountPaymentMethodVirtualAccountRefundStatusPaymentMethodVirtualAccountTypePaymentNotFoundErrorPaymentNotPaidErrorPaymentNotWaitingForDepositErrorPaymentProductPaymentProductTypePaymentSchedulePaymentScheduleAlreadyExistsErrorPaymentScheduleAlreadyProcessedErrorPaymentScheduleAlreadyRevokedErrorPaymentScheduleFilterInputPaymentScheduleNotFoundErrorPaymentScheduleSortByPaymentScheduleSortInputPaymentScheduleStatusPaymentScheduleSummaryPaymentSortByPaymentStatusPaymentTextSearchPaymentTextSearchFieldPaymentTimestampTypePaymentWebhookPaymentWebhookPaymentStatusPaymentWebhookRequestPaymentWebhookResponsePaymentWebhookStatusPaymentWebhookTriggerPaymentWithCursorPendingPaymentSchedulePgProviderPgProviderErrorPortOneVersionPreRegisterPaymentErrorPreRegisterPaymentResponseReadyIdentityVerificationReadyPaymentRefreshTokenErrorRefreshTokenResponseRefuseB2bTaxInvoiceRequestErrorRegisterB2bMemberCompanyErrorRegisterB2bMemberCompanyResponseRegisterStoreReceiptBodyItemRegisterStoreReceiptErrorRegisterStoreReceiptResponseRegisteredPaymentEscrowRejectConfirmedPaymentEscrowRejectedPaymentEscrowRequestB2bTaxInvoiceRegisterErrorRequestB2bTaxInvoiceReverseIssuanceErrorRequestedPaymentCancellationResendIdentityVerificationErrorResendIdentityVerificationResponseResendWebhookErrorResendWebhookResponseRevokePaymentScheduleErrorRevokePaymentScheduleResponseRevokedPaymentScheduleScheduledPaymentScheduleSelectedChannelSelectedChannelTypeSendIdentityVerificationBodyCustomerSendIdentityVerificationErrorSendIdentityVerificationResponseSeparatedAddressSeparatedAddressInputSortOrderStartedPaymentScheduleSucceededPaymentCancellationSucceededPaymentScheduleSumOfPartsExceedsCancelAmountErrorSumOfPartsExceedsTotalAmountErrorUnauthorizedErrorUpdateB2bMemberCompanyContactErrorUpdateB2bMemberCompanyContactResponseUpdateB2bMemberCompanyErrorUpdateB2bMemberCompanyResponseVerifiedIdentityVerificationVirtualAccountIssuedPaymentWebhookNotFoundErrorgetB2bContactIdExistenceErrorrequestB2bTaxInvoiceError