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
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 기능을 제공합니다.
get/billing-keys/{billingKey}
빌링키 단건 조회
주어진 빌링키에 대응되는 빌링키 정보를 조회합니다.
Request
Path
billingKey: string
조회할 빌링키
조회할 빌링키
Query
storeId?: string
상점 아이디
(Optional)
접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.
Response
200
성공 응답으로 빌링키 정보를 반환합니다.
billingKey: string
빌링키
merchantId: string
가맹점 아이디
storeId: string
상점 아이디
빌링키 결제수단 상세 정보
(Optional)
추후 슈퍼빌링키 기능 제공 시 여러 결제수단 정보가 담길 수 있습니다.
type: string (Union Tag)
필드의 값이 일 때 타입은 BillingKeyPaymentMethodCard 입니다.
카드 상세 정보
(Optional)
카드 상세 정보
빌링키 발급 시 사용된 채널
추후 슈퍼빌링키 기능 제공 시 여러 채널 정보가 담길 수 있습니다.
채널 타입
채널 타입
id?: string
채널 아이디
(Optional)
key?: string
채널 키
(Optional)
name?: string
채널 명
(Optional)
PG사 결제 모듈
PG사 결제 모듈
pgMerchantId: string
PG사 가맹점 식별 아이디
고객 정보
고객 정보
id?: string
고객 아이디
(Optional)
가맹점이 지정한 고객의 고유 식별자입니다.
name?: string
이름
(Optional)
birthYear?: string
출생 연도
(Optional)
성별
(Optional)
성별
email?: string
이메일
(Optional)
phoneNumber?: string
전화번호
(Optional)
분리 형식 주소
(Optional)
oneLine(한 줄 형식 주소) 필드는 항상 존재합니다.
zipcode?: string
우편번호
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
issueId?: string
가맹점이 채번하는 빌링키 발급 건 고유 아이디
(Optional)
issueName?: string
빌링키 발급 건 이름
(Optional)
발급 시점
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)
403
ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)
404
BillingKeyNotFoundError: 빌링키가 존재하지 않는 경우
type: string
message?: string
(Optional)
try
Request
Request Sample
delete/billing-keys/{billingKey}
빌링키 삭제
빌링키를 삭제합니다.
Request
Path
billingKey: 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
BillingKeyNotIssuedErrorBillingKeyNotFoundError: 빌링키가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 BillingKeyNotFoundError 입니다.
message?: string
(Optional)
409
BillingKeyAlreadyDeletedError: 빌링키가 이미 삭제된 경우PaymentScheduleAlreadyExistsError: 결제 예약건이 이미 존재하는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 BillingKeyAlreadyDeletedError 입니다.
message?: string
(Optional)
502
PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Request Sample
post/billing-keys
빌링키 발급
빌링키 발급을 요청합니다.
Request
Body
storeId?: string
상점 아이디
(Optional)
접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다.
빌링키 발급 시 결제 수단 입력 양식
빌링키 발급 시 결제 수단 입력 양식
카드 수단 정보 입력 양식
(Optional)
카드 수단 정보 입력 양식
channelKey: string
채널키
고객 정보 입력 정보
(Optional)
고객 정보 입력 정보
id?: string
고객 아이디
(Optional)
가맹점이 지정한 고객의 고유 식별자입니다.
고객 이름 입력 정보
(Optional)
두 개의 이름 형식 중 한 가지만 선택하여 입력해주세요.
birthYear?: string
출생 연도
(Optional)
birthMonth?: string
출생월
(Optional)
birthDay?: string
출생일
(Optional)
국가
(Optional)
국가
성별
(Optional)
성별
email?: string
이메일
(Optional)
phoneNumber?: string
전화번호
(Optional)
분리 형식 주소 입력 정보
(Optional)
분리 형식 주소 입력 정보
zipcode?: string
우편번호
(Optional)
businessRegistrationNumber?: string
사업자 등록 번호
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
bypass?: object
PG사별 추가 파라미터 ("PG사별 연동 가이드" 참고)
(Optional)
noticeUrls?: string[]
웹훅 주소
(Optional)
빌링키 발급 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다. 입력된 값이 없을 경우에는 빈 배열로 해석됩니다.
Response
200
성공 응답
billingKey: string
발급된 빌링키
빌링크 발급 완료 시점
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string
message?: string
(Optional)
403
ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)
404
ChannelNotFoundError: 요청된 채널이 존재하지 않는 경우
type: string
message?: string
(Optional)
502
PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Request Sample
현금 영수증 관련 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 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
AddressAlreadyPaidErrorAlreadyPaidOrWaitingErrorApplyEscrowLogisticsErrorApplyEscrowLogisticsResponseAttachB2bTaxInvoiceFileErrorB2bBankAccountNotFoundErrorB2bCertificateB2bCertificateTypeB2bCertificateUnregisteredErrorB2bCompanyAlreadyRegisteredErrorB2bCompanyContactB2bCompanyContactInputB2bCompanyNotFoundErrorB2bCompanyStateB2bCompanyStateBusinessStatusB2bCompanyStateTaxationTypeB2bContactNotFoundErrorB2bExternalServiceErrorB2bFileNotFoundErrorB2bFinancialSystemCommunicationErrorB2bFinancialSystemFailureErrorB2bFinancialSystemUnderMaintenanceErrorB2bForeignExchangeAccountErrorB2bHometaxUnderMaintenanceErrorB2bIdAlreadyExistsErrorB2bMemberCompanyB2bMemberCompanyNotFoundErrorB2bModificationB2bNotEnabledErrorB2bRecipientNotFoundErrorB2bRegularMaintenanceTimeErrorB2bSearchDateTypeB2bSupplierNotFoundErrorB2bSuspendedAccountErrorB2bTaxInvoiceB2bTaxInvoiceAdditionalContactB2bTaxInvoiceAttachmentB2bTaxInvoiceAttachmentNotFoundErrorB2bTaxInvoiceBeforeSendingB2bTaxInvoiceCompanyB2bTaxInvoiceContactB2bTaxInvoiceDocumentKeyTypeB2bTaxInvoiceInputB2bTaxInvoiceIssuanceCancelledB2bTaxInvoiceIssuedB2bTaxInvoiceItemB2bTaxInvoiceModificationTypeB2bTaxInvoiceNoRecipientDocumentKeyErrorB2bTaxInvoiceNoSupplierDocumentKeyErrorB2bTaxInvoiceNonDeletableStatusErrorB2bTaxInvoiceNotFoundErrorB2bTaxInvoiceNotIssuedStatusErrorB2bTaxInvoiceNotRegisteredStatusErrorB2bTaxInvoiceNotRequestedStatusErrorB2bTaxInvoicePurposeTypeB2bTaxInvoiceRegisteredB2bTaxInvoiceRequestCancelledB2bTaxInvoiceRequestRefusedB2bTaxInvoiceRequestedB2bTaxInvoiceSendingB2bTaxInvoiceSendingCompletedB2bTaxInvoiceSendingFailedB2bTaxInvoiceStatusB2bTaxInvoiceSummaryB2bTaxInvoiceWaitingSendingB2bTaxTypeBankBeforeRegisteredPaymentEscrowBillingKeyAlreadyDeletedErrorBillingKeyInfoBillingKeyInfoSummaryBillingKeyNotFoundErrorBillingKeyNotIssuedErrorBillingKeyPaymentInputBillingKeyPaymentMethodBillingKeyPaymentMethodCardBillingKeyPaymentMethodEasyPayBillingKeyPaymentMethodEasyPayChargeBillingKeyPaymentMethodEasyPayMethodBillingKeyPaymentMethodMobileBillingKeyPaymentMethodPaypalBillingKeyPaymentMethodTransferBillingKeyPaymentSummaryCancelAmountExceedsCancellableAmountErrorCancelB2bTaxInvoiceIssuanceErrorCancelB2bTaxInvoiceRequestErrorCancelCashReceiptErrorCancelCashReceiptResponseCancelPaymentBodyRefundAccountCancelPaymentErrorCancelPaymentResponseCancelRequesterCancelTaxAmountExceedsCancellableTaxAmountErrorCancelTaxFreeAmountExceedsCancellableTaxFreeAmountErrorCancellableAmountConsistencyBrokenErrorCancelledCashReceiptCancelledPaymentCancelledPaymentCashReceiptCancelledPaymentEscrowCardCardBrandCardCredentialCardOwnerTypeCardTypeCashReceiptCashReceiptAlreadyIssuedErrorCashReceiptInputCashReceiptInputTypeCashReceiptNotFoundErrorCashReceiptNotIssuedErrorCashReceiptSummaryCashReceiptTypeChannelNotFoundErrorCloseVirtualAccountErrorCloseVirtualAccountResponseConfirmEscrowErrorConfirmEscrowResponseConfirmIdentityVerificationErrorConfirmIdentityVerificationResponseConfirmedPaymentEscrowCountryCreateB2bTaxInvoiceFileUploadLinkCreateErrorCreateB2bTaxInvoiceFileUploadLinkResponseCreatePaymentScheduleErrorCreatePaymentScheduleResponseCurrencyCustomerCustomerInputCustomerNameInputCustomerSeparatedNameDateTimeRangeDeleteB2bTaxInvoiceAttachmentErrorDeleteB2bTaxInvoiceErrorDeleteBillingKeyErrorDeleteBillingKeyResponseDeliveredPaymentEscrowEasyPayProviderFailedIdentityVerificationFailedPaymentFailedPaymentCancellationFailedPaymentScheduleForbiddenErrorGenderGetAllPaymentsByCursorResponseGetAllPaymentsErrorGetB2bAccountHolderErrorGetB2bBankAccountHolderResponseGetB2bCertificateErrorGetB2bCertificateRegistrationUrlErrorGetB2bCertificateRegistrationUrlResponseGetB2bCompanyStateErrorGetB2bContactIdExistenceResponseGetB2bMemberCompanyContactErrorGetB2bMemberCompanyErrorGetB2bTaxInvoiceAttachmentsErrorGetB2bTaxInvoiceAttachmentsResponseGetB2bTaxInvoiceErrorGetB2bTaxInvoicePdfDownloadUrlErrorGetB2bTaxInvoicePdfDownloadUrlResponseGetB2bTaxInvoicePopupUrlErrorGetB2bTaxInvoicePopupUrlResponseGetB2bTaxInvoicePrintUrlErrorGetB2bTaxInvoicePrintUrlResponseGetB2bTaxInvoicesErrorGetB2bTaxInvoicesResponseGetBillingKeyInfoErrorGetCashReceiptErrorGetIdentityVerificationErrorGetKakaopayPaymentOrderErrorGetKakaopayPaymentOrderResponseGetPaymentErrorGetPaymentScheduleErrorGetPaymentSchedulesErrorGetPaymentSchedulesResponseGetPaymentsErrorGetPaymentsResponseIdentityVerificationIdentityVerificationAlreadySentErrorIdentityVerificationAlreadyVerifiedErrorIdentityVerificationMethodIdentityVerificationNotFoundErrorIdentityVerificationNotSentErrorIdentityVerificationOperatorIdentityVerificationRequestedCustomerIdentityVerificationVerifiedCustomerInstantBillingKeyPaymentMethodInputInstantBillingKeyPaymentMethodInputCardInstantPaymentMethodInputInstantPaymentMethodInputCardInstantPaymentMethodInputVirtualAccountInstantPaymentMethodInputVirtualAccountCashReceiptInfoInstantPaymentMethodInputVirtualAccountExpiryInstantPaymentMethodInputVirtualAccountOptionInstantPaymentMethodInputVirtualAccountOptionFixedInstantPaymentMethodInputVirtualAccountOptionTypeInstantPaymentSummaryInvalidRequestErrorIssueB2bTaxInvoiceErrorIssueBillingKeyErrorIssueBillingKeyResponseIssueCashReceiptCustomerInputIssueCashReceiptErrorIssueCashReceiptResponseIssueFailedCashReceiptIssuedCashReceiptIssuedPaymentCashReceiptLoginViaApiSecretErrorLoginViaApiSecretResponseModifyEscrowLogisticsErrorModifyEscrowLogisticsResponseOneLineAddressPageInfoPageInputPaidPaymentPartialCancelledPaymentPayInstantlyErrorPayInstantlyResponsePayPendingPaymentPayWithBillingKeyErrorPayWithBillingKeyResponsePaymentPaymentAlreadyCancelledErrorPaymentAmountPaymentAmountInputPaymentCancellationPaymentCashReceiptPaymentCashReceiptStatusPaymentClientTypePaymentEscrowPaymentEscrowReceiverInputPaymentEscrowSenderInputPaymentFilterInputPaymentFilterInputEscrowStatusPaymentInstallmentPaymentLogisticsPaymentLogisticsCompanyPaymentMethodPaymentMethodCardPaymentMethodEasyPayPaymentMethodEasyPayMethodPaymentMethodEasyPayMethodChargePaymentMethodGiftCertificatePaymentMethodGiftCertificateTypePaymentMethodMobilePaymentMethodTransferPaymentMethodTypePaymentMethodVirtualAccountPaymentMethodVirtualAccountRefundStatusPaymentMethodVirtualAccountTypePaymentNotFoundErrorPaymentNotPaidErrorPaymentNotWaitingForDepositErrorPaymentProductPaymentProductTypePaymentSchedulePaymentScheduleAlreadyExistsErrorPaymentScheduleAlreadyProcessedErrorPaymentScheduleAlreadyRevokedErrorPaymentScheduleFilterInputPaymentScheduleNotFoundErrorPaymentScheduleSortByPaymentScheduleSortInputPaymentScheduleStatusPaymentScheduleSummaryPaymentSortByPaymentStatusPaymentTextSearchPaymentTextSearchFieldPaymentTimestampTypePaymentWebhookPaymentWebhookPaymentStatusPaymentWebhookRequestPaymentWebhookResponsePaymentWebhookStatusPaymentWebhookTriggerPaymentWithCursorPendingPaymentSchedulePgProviderPgProviderErrorPortOneVersionPreRegisterPaymentErrorPreRegisterPaymentResponseReadyIdentityVerificationReadyPaymentRefreshTokenErrorRefreshTokenResponseRefuseB2bTaxInvoiceRequestErrorRegisterB2bMemberCompanyErrorRegisterB2bMemberCompanyResponseRegisterStoreReceiptBodyItemRegisterStoreReceiptErrorRegisterStoreReceiptResponseRegisteredPaymentEscrowRejectConfirmedPaymentEscrowRejectedPaymentEscrowRequestB2bTaxInvoiceRegisterErrorRequestB2bTaxInvoiceReverseIssuanceErrorRequestedPaymentCancellationResendIdentityVerificationErrorResendIdentityVerificationResponseResendWebhookErrorResendWebhookResponseRevokePaymentScheduleErrorRevokePaymentScheduleResponseRevokedPaymentScheduleScheduledPaymentScheduleSelectedChannelSelectedChannelTypeSendIdentityVerificationBodyCustomerSendIdentityVerificationErrorSendIdentityVerificationResponseSeparatedAddressSeparatedAddressInputSortOrderStartedPaymentScheduleSucceededPaymentCancellationSucceededPaymentScheduleSumOfPartsExceedsCancelAmountErrorSumOfPartsExceedsTotalAmountErrorUnauthorizedErrorUpdateB2bMemberCompanyContactErrorUpdateB2bMemberCompanyContactResponseUpdateB2bMemberCompanyErrorUpdateB2bMemberCompanyResponseVerifiedIdentityVerificationVirtualAccountIssuedPaymentWebhookNotFoundErrorgetB2bContactIdExistenceErrorrequestB2bTaxInvoiceError