개발자센터

결제 관련 API

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

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
Address: OneLineAddress | SeparatedAddress
분리 형식 주소

oneLine(한 줄 형식 주소) 필드는 항상 존재합니다.

AlreadyPaidError: { type, message }
결제가 이미 완료된 경우
ApplyEscrowLogisticsError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
ApplyEscrowLogisticsResponse: { invoiceNumber, sentAt, appliedAt }
에스크로 배송 정보 등록 성공 응답
Bank: "BANK_OF_KOREA" | "KDB" | "IBK" | ...
은행
BeforeRegisteredPaymentEscrow: { status }
배송 정보 등록 전
BillingKeyAlreadyDeletedError: { type, message }
빌링키가 이미 삭제된 경우
BillingKeyNotFoundError: { type, message }
빌링키가 존재하지 않는 경우
BillingKeyPaymentInput: { storeId, billingKey, channelKey, ... }
빌링키 결제 요청 입력 정보
BillingKeyPaymentSummary: { pgTxId, paidAt }
빌링키 결제 완료된 결제 건 요약 정보
CancelAmountExceedsCancellableAmountError: { type, message }
결제 취소 금액이 취소 가능 금액을 초과한 경우
CancelPaymentBody: { storeId, amount, taxFreeAmount, ... }
결제 취소 요청 입력 정보
CancelPaymentBodyRefundAccount: { bank, number, holderName, ... }
고객 정보 입력 형식
CancelPaymentError: CancellableAmountConsistencyBrokenError | CancelAmountExceedsCancellableAmountError | CancelTaxAmountExceedsCancellableTaxAmountError | ...
CancelPaymentResponse: { cancellation }
결제 취소 성공 응답
CancelRequester: "CUSTOMER" | "ADMIN"
결제 취소 요청 주체
CancelTaxAmountExceedsCancellableTaxAmountError: { type, message }
취소 과세 금액이 취소 가능한 과세 금액을 초과한 경우
CancelTaxFreeAmountExceedsCancellableTaxFreeAmountError: { type, message }
취소 면세 금액이 취소 가능한 면세 금액을 초과한 경우
CancellableAmountConsistencyBrokenError: { type, message }
취소 가능 잔액 검증에 실패한 경우
CancelledPayment: { status, id, transactionId, ... }
결제 취소 상태 건
CancelledPaymentCashReceipt: { status, type, pgReceiptId, ... }
취소된 현금영수증
CancelledPaymentEscrow: { status, company, invoiceNumber, ... }
거래 취소
CancelledPaymentEvent: { type, id, paymentId, ... }
결제 취소 상태 이벤트
CancelledPaymentTransaction: { status, id, paymentId, ... }
결제 취소 상태 건
CapturePaymentBody: { storeId }
수동 매입 입력 정보
CapturePaymentError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
CapturePaymentResponse: { }
수동 매입 성공 응답
Card: { publisher, issuer, brand, ... }
카드 상세 정보
CardBrand: "LOCAL" | "MASTER" | "UNIONPAY" | ...
카드 브랜드
CardCredential: { number, expiryYear, expiryMonth, ... }
카드 인증 관련 정보
CardOwnerType: "PERSONAL" | "CORPORATE"
카드 소유주 유형
CardType: "CREDIT" | "DEBIT" | "GIFT"
카드 유형
CashReceiptInput: { type, customerIdentityNumber }
현금영수증 입력 정보
CashReceiptInputType: "PERSONAL" | "CORPORATE" | "NO_RECEIPT"
입력 시 발급 유형
CashReceiptIssuanceStatus: "ISSUED" | "NOT_ISSUED"
현금영수증 발행여부
CashReceiptType: "PERSONAL" | "CORPORATE"
발급 유형
ChannelGroupSummary: { id, name, isForTest }
채널 그룹 정보
ChannelNotFoundError: { type, message }
요청된 채널이 존재하지 않는 경우
CloseVirtualAccountError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
CloseVirtualAccountResponse: { closedAt }
가상계좌 말소 성공 응답
ConfirmEscrowBody: { storeId, fromStore }
에스크로 구매 확정 입력 정보
ConfirmEscrowError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
ConfirmEscrowResponse: { completedAt }
에스크로 구매 확정 성공 응답
ConfirmPaymentBody: { storeId, paymentToken, txId, ... }
결제 승인 입력 정보
ConfirmPaymentError: AlreadyPaidError | ForbiddenError | InformationMismatchError | ...
ConfirmedPaymentEscrow: { status, company, invoiceNumber, ... }
구매 확정
ConfirmedPaymentSummary: { pgTxId, paidAt }
결제 수동 승인 완료된 결제 건 요약 정보
ConvenienceStoreBrand: "LAWSON" | "FAMILY_MART" | "MINI_STOP" | ...
편의점 브랜드
Country: "AD" | "AE" | "AF" | ...
국가
Currency: "KRW" | "USD" | "JPY" | ...
통화
Customer: { id, name, birthYear, ... }
고객 정보
CustomerInput: { id, name, birthYear, ... }
고객 정보 입력 정보
CustomerNameInput: { full, separated }
고객 이름 입력 정보

두 개의 이름 형식 중 한 가지만 선택하여 입력해주세요.

CustomerSeparatedName: { first, last }
고객 분리형 이름
DateTimeRange: { from, until }
시간 범위
DeliveredPaymentEscrow: { status, company, invoiceNumber, ... }
배송 완료
DiscountAmountExceedsTotalAmountError: { type, message }
프로모션 할인 금액이 결제 시도 금액 이상인 경우
Dispute: { status, pgDisputeId, reason, ... }
분쟁 내역
DisputeStatus: "UNRESOLVED" | "RESOLVED"
분쟁 상태
EasyPayProvider: "SAMSUNGPAY" | "KAKAOPAY" | "NAVERPAY" | ...
간편 결제사
FailedPayment: { status, id, transactionId, ... }
결제 실패 상태 건
FailedPaymentCancellation: { status, id, pgCancellationId, ... }
취소 실패 상태
FailedPaymentTransaction: { status, id, paymentId, ... }
결제 실패 상태 건
ForbiddenError: { type, message }
요청이 거절된 경우
Gender: "MALE" | "FEMALE" | "OTHER"
성별
GetAllPaymentEventsByCursorBody: { storeId, from, until, ... }

결제 이벤트 커서 기반 대용량 다건 조회를 위한 입력 정보

GetAllPaymentEventsByCursorResponse: { items }
결제 이벤트 커서 기반 대용량 다건 조회 성공 응답 정보
GetAllPaymentEventsError: ForbiddenError | InvalidRequestError | UnauthorizedError
GetAllPaymentsByCursorBody: { storeId, from, until, ... }

결제 건 커서 기반 대용량 다건 조회를 위한 입력 정보

GetAllPaymentsByCursorResponse: { items }
결제 건 커서 기반 대용량 다건 조회 성공 응답 정보
GetAllPaymentsError: ForbiddenError | InvalidRequestError | UnauthorizedError
GetPaymentError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
GetPaymentTransactionsError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
GetPaymentTransactionsResponse: { items }
결제 시도 내역 조회 응답 정보
GetPaymentsBody: { page, filter }
결제 다건 조회를 위한 입력 정보
GetPaymentsError: ForbiddenError | InvalidRequestError | UnauthorizedError
GetPaymentsResponse: { items, page }
결제 건 다건 조회 성공 응답 정보
InformationMismatchError: { type, message }
정보가 일치하지 않는 경우
InstantPaymentInput: { storeId, channelKey, channelGroupId, ... }
수기 결제 요청 정보
InstantPaymentMethodInput: { card, virtualAccount }
수기 결제 수단 입력 정보

하나의 필드만 입력합니다.

InstantPaymentMethodInputCard: { credential, installmentMonth, useFreeInstallmentPlan, ... }
카드 수단 정보 입력 정보
InstantPaymentMethodInputVirtualAccount: { bank, expiry, option, ... }
가상계좌 수단 정보 입력 정보
InstantPaymentMethodInputVirtualAccountCashReceiptInfo: { type, customerIdentityNumber }
가상계좌 결제 시 현금영수증 정보
InstantPaymentMethodInputVirtualAccountExpiry: { validHours, dueDate }
입금 만료 기한

validHours와 dueDate 둘 중 하나의 필드만 입력합니다.

InstantPaymentMethodInputVirtualAccountOption: { type, fixed }
가상계좌 발급 방식
InstantPaymentMethodInputVirtualAccountOptionFixed: { pgAccountId, accountNumber }
고정식 가상계좌 발급 유형

pgAccountId, accountNumber 유형 중 한 개의 필드만 입력합니다.

InstantPaymentMethodInputVirtualAccountOptionType: "NORMAL" | "FIXED"
가상계좌 발급 유형
InstantPaymentSummary: { pgTxId, paidAt }
수기 결제가 완료된 결제 건 요약 정보
InvalidPaymentTokenError: { type, message }
유효하지 않은 결제 토큰인 경우
InvalidRequestError: { type, message }
요청된 입력 정보가 유효하지 않은 경우

허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.

IssuedPaymentCashReceipt: { status, type, pgReceiptId, ... }
발급 완료된 현금영수증
Locale: "KO_KR" | "EN_US" | "ZH_CN" | ...
결제 언어
MaxCancelCountReachedError: { type, message }
취소 시도 횟수가 초과된 경우
MaxTransactionCountReachedError: { type, message }
결제 혹은 본인인증 시도 횟수가 최대에 도달한 경우
MaxWebhookRetryCountReachedError: { type, message }
동일한 webhook id에 대한 수동 재시도 횟수가 최대에 도달한 경우
ModifyEscrowLogisticsBody: { storeId, sender, receiver, ... }
에스크로 배송 정보 수정 입력 정보
ModifyEscrowLogisticsError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
ModifyEscrowLogisticsResponse: { invoiceNumber, sentAt, modifiedAt }
에스크로 배송 정보 수정 성공 응답
NegativePromotionAdjustedCancelAmountError: { type, message }
프로모션에 의해 조정된 취소 금액이 음수인 경우
OneLineAddress: { type, oneLine }
한 줄 형식 주소

한 줄 형식 주소만 존재합니다.

PageInfo: { number, size, totalCount }
반환된 페이지 결과 정보
PageInput: { number, size }
다건 조회 API 에 사용되는 페이지 입력 정보
PaidPayment: { status, id, transactionId, ... }
결제 완료 상태 건
PaidPaymentEvent: { type, id, paymentId, ... }
결제 완료 이벤트
PaidPaymentTransaction: { status, id, paymentId, ... }
결제 완료 상태 건
PartialCancelledPayment: { status, id, transactionId, ... }
결제 부분 취소 상태 건
PartialCancelledPaymentEvent: { type, id, paymentId, ... }
결제 부분 취소 상태 이벤트
PartialCancelledPaymentTransaction: { status, id, paymentId, ... }
결제 부분 취소 상태 건
PayInstantlyError: AlreadyPaidError | ChannelNotFoundError | DiscountAmountExceedsTotalAmountError | ...
PayInstantlyResponse: { payment }
수기 결제 성공 응답
PayPendingPayment: { status, id, transactionId, ... }
결제 완료 대기 상태 건
PayPendingPaymentTransaction: { status, id, paymentId, ... }
결제 완료 대기 상태 건
PayWithBillingKeyError: AlreadyPaidError | BillingKeyAlreadyDeletedError | BillingKeyNotFoundError | ...
PayWithBillingKeyResponse: { payment }
빌링키 결제 성공 응답
Payment: CancelledPayment | FailedPayment | PaidPayment | ...
결제 건
PaymentAlreadyCancelledError: { type, message }
결제가 이미 취소된 경우
PaymentAmount: { total, taxFree, vat, ... }
결제 금액 세부 정보
PaymentAmountInput: { total, taxFree, vat }
금액 세부 입력 정보
PaymentCancellation: FailedPaymentCancellation | RequestedPaymentCancellation | SucceededPaymentCancellation
결제 취소 내역
PaymentCancellationNotFoundError: { type, message }
결제 취소 내역이 존재하지 않는 경우
PaymentCancellationNotPendingError: { type, message }
결제 취소 내역이 취소 요청 상태가 아닌 경우
PaymentCashReceipt: CancelledPaymentCashReceipt | IssuedPaymentCashReceipt
결제 건 내 현금영수증 정보
PaymentCashReceiptStatus: "ISSUED" | "CANCELLED"
결제건 내 현금영수증 상태
PaymentClientType: "SDK_MOBILE" | "SDK_PC" | "API"
결제가 발생한 클라이언트 환경
PaymentEscrow: BeforeRegisteredPaymentEscrow | CancelledPaymentEscrow | ConfirmedPaymentEscrow | ...
에스크로 정보

V1 결제 건의 경우 타입이 REGISTERED 로 고정됩니다.

PaymentEscrowReceiverInput: { name, phoneNumber, zipcode, ... }
에스크로 수취인 정보
PaymentEscrowSenderInput: { name, phoneNumber, zipcode, ... }
에스크로 발송자 정보
PaymentEvent: CancelledPaymentEvent | PaidPaymentEvent | PartialCancelledPaymentEvent
결제 이벤트
PaymentEventWithCursor: { paymentEvent, cursor }
결제 이벤트 및 커서 정보
PaymentFailure: { reason, pgCode, pgMessage }
결제 실패 정보
PaymentFilterInput: { merchantId, storeId, timestampType, ... }
결제 다건 조회를 위한 입력 정보
PaymentFilterInputEscrowStatus: "REGISTERED" | "DELIVERED" | "CONFIRMED" | ...
에스크로 상태
PaymentInstallment: { month, isInterestFree, isInterestFreeFromMerchant }
할부 정보
PaymentLogistics: { company, invoiceNumber, sentAt, ... }
배송정보
PaymentLogisticsCompany: "LOTTE" | "LOGEN" | "DONGWON" | ...
물류 회사
PaymentMethod: PaymentMethodCard | PaymentMethodConvenienceStore | PaymentMethodCrypto | ...
결제수단 정보
PaymentMethodCard: { type, card, approvalNumber, ... }
결제수단 카드 정보
PaymentMethodConvenienceStore: { type, convenienceStoreBrand, confirmationNumber, ... }
편의점 결제 상세 정보
PaymentMethodCrypto: { type }
암호화폐 결제 상세 정보
PaymentMethodEasyPay: { type, provider, easyPayMethod }
간편 결제 상세 정보
PaymentMethodEasyPayMethod: PaymentMethodCard | PaymentMethodEasyPayMethodCharge | PaymentMethodTransfer
간편 결제 수단
PaymentMethodEasyPayMethodCharge: { type, bank }
충전식 포인트 결제 정보
PaymentMethodGiftCertificate: { type, giftCertificateType, approvalNumber }
상품권 상세 정보
PaymentMethodGiftCertificateType: "BOOKNLIFE" | "SMART_MUNSANG" | "CULTURELAND" | ...
상품권 종류
PaymentMethodMobile: { type, phoneNumber }
모바일 상세 정보
PaymentMethodTransfer: { type, bank, accountNumber }
계좌 이체 상세 정보
PaymentMethodType: "CARD" | "TRANSFER" | "VIRTUAL_ACCOUNT" | ...
PaymentMethodVirtualAccount: { type, bank, accountNumber, ... }
가상계좌 상세 정보
PaymentMethodVirtualAccountRefundStatus: "PENDING" | "PARTIAL_REFUND_FAILED" | "FAILED" | ...
가상계좌 환불 상태
PaymentMethodVirtualAccountType: "FIXED" | "NORMAL"
가상계좌 유형
PaymentNotFoundError: { type, message }
결제 건이 존재하지 않는 경우
PaymentNotPaidError: { type, message }
결제가 완료되지 않은 경우
PaymentNotWaitingForDepositError: { type, message }
결제 건이 입금 대기 상태가 아닌 경우
PaymentOrigin: { platformType, userAgent, url, ... }
결제 출처 정보
PaymentOriginPlatformType: "PC" | "MOBILE" | "API"
플랫폼 타입
PaymentProduct: { id, name, tag, ... }
상품 정보
PaymentProductType: "PHYSICAL" | "DIGITAL"
상품 유형
PaymentScheduleAlreadyExistsError: { type, message }
결제 예약건이 이미 존재하는 경우
PaymentSortBy: "REQUESTED_AT" | "STATUS_CHANGED_AT"
결제 건 정렬 기준
PaymentStatus: "READY" | "PENDING" | "VIRTUAL_ACCOUNT_ISSUED" | ...
결제 건 상태
PaymentTextSearch: { field, value }
통합검색 입력 정보
PaymentTextSearchField: "ALL" | "PAYMENT_ID" | "TX_ID" | ...
통합검색 항목
PaymentTimestampType: "CREATED_AT" | "STATUS_CHANGED_AT"
조회 시점 기준

어떤 시점을 기준으로 조회를 할 것인지 선택합니다. CREATED_AT: 결제 건 생성 시점을 기준으로 조회합니다. STATUS_CHANGED_AT: 상태 승인 시점을 기준으로 조회합니다. 결제 건의 최종 상태에 따라 검색 기준이 다르게 적용됩니다. ready -> 결제 요청 시점 기준 paid -> 결제 완료 시점 기준 cancelled -> 결제 취소 시점 기준 failed -> 결제 실패 시점 기준 값을 입력하지 않으면 STATUS_CHANGED_AT 으로 자동 적용됩니다.

PaymentTransaction: CancelledPaymentTransaction | FailedPaymentTransaction | PaidPaymentTransaction | ...
결제 시도
PaymentWebhook: { paymentStatus, id, status, ... }
성공 웹훅 내역
PaymentWebhookPaymentStatus: "READY" | "VIRTUAL_ACCOUNT_ISSUED" | "PAID" | ...
웹훅 발송 시 결제 건 상태
PaymentWebhookRequest: { header, body, requestedAt }
웹훅 요청 정보
PaymentWebhookResponse: { code, header, body, ... }
웹훅 응답 정보
PaymentWebhookStatus: "SUCCEEDED" | "FAILED_NOT_OK_RESPONSE" | "FAILED_UNEXPECTED_ERROR"
웹훅 전송 상태
PaymentWebhookTrigger: "MANUAL" | "VIRTUAL_ACCOUNT_DEPOSIT" | "ASYNC_CANCEL_APPROVED" | ...
웹훅 실행 트리거

수동 웹훅 재발송, 가상계좌 입금, 비동기 취소 승인 시 발생한 웹훅일 때 필드의 값이 존재합니다.

PaymentWithCursor: { payment, cursor }
결제 건 및 커서 정보
PgProvider: "HTML5_INICIS" | "PAYPAL" | "PAYPAL_V2" | ...
PG사 결제 모듈
PgProviderError: { type, message, pgCode, ... }
PG사에서 오류를 전달한 경우
PortOneVersion: "V1" | "V2"
포트원 버전
PreRegisterPaymentBody: { storeId, totalAmount, taxFreeAmount, ... }
결제 정보 사전 등록 입력 정보
PreRegisterPaymentError: AlreadyPaidError | ForbiddenError | InvalidRequestError | ...
PreRegisterPaymentResponse: { }
결제 사전 등록 성공 응답
PromotionDiscountRetainOption: "RETAIN" | "RELEASE"
PromotionDiscountRetainOptionShouldNotBeChangedError: { type, message }
프로모션 혜택 유지 옵션을 이전 부분 취소와 다른 것으로 입력한 경우
PromotionPayMethodDoesNotMatchError: { type, message }
결제수단이 프로모션에 지정된 것과 일치하지 않는 경우
ReadyPayment: { status, id, transactionId, ... }
준비 상태 건
ReadyPaymentTransaction: { status, id, paymentId, ... }
준비 상태 건
RegisterEscrowLogisticsBody: { storeId, sender, receiver, ... }
에스크로 배송 정보 등록 입력 정보
RegisterStoreReceiptBody: { items, storeId }
영수증 내 하위 상점 거래 등록 정보
RegisterStoreReceiptBodyItem: { storeBusinessRegistrationNumber, storeName, totalAmount, ... }
하위 상점 거래 정보
RegisterStoreReceiptError: ForbiddenError | InvalidRequestError | PaymentNotFoundError | ...
RegisterStoreReceiptResponse: { receiptUrl }
영수증 내 하위 상점 거래 등록 응답
RegisteredPaymentEscrow: { status, company, invoiceNumber, ... }
배송 정보 등록 완료
RejectConfirmedPaymentEscrow: { status, company, invoiceNumber, ... }
구매 거절 확정
RejectedPaymentEscrow: { status, company, invoiceNumber, ... }
구매 거절
RequestedPaymentCancellation: { status, id, pgCancellationId, ... }
취소 요청 상태
ResendWebhookBody: { storeId, webhookId }

웹훅 재발송을 위한 입력 정보

ResendWebhookError: ForbiddenError | InvalidRequestError | MaxWebhookRetryCountReachedError | ...
ResendWebhookResponse: { webhook }
웹훅 재발송 응답 정보
SelectedChannel: { type, id, key, ... }
(결제, 본인인증 등에) 선택된 채널 정보
SelectedChannelType: "LIVE" | "TEST"
채널 타입
SeparatedAddress: { type, oneLine, addressLine1, ... }
분리 형식 주소

한 줄 형식 주소와 분리 형식 주소 모두 존재합니다. 한 줄 형식 주소는 분리 형식 주소를 이어 붙인 형태로 생성됩니다.

SeparatedAddressInput: { addressLine1, addressLine2, city, ... }
분리 형식 주소 입력 정보
SortOrder: "DESC" | "ASC"
정렬 방식
StopPaymentCancellationBody: { storeId }
결제 취소 요청 취소 입력 정보
StopPaymentCancellationError: ForbiddenError | InvalidRequestError | PaymentCancellationNotFoundError | ...
StopPaymentCancellationResponse: { stoppedAt }
결제 취소 요청 취소 성공 응답
SucceededPaymentCancellation: { status, id, pgCancellationId, ... }
취소 완료 상태
SumOfPartsExceedsCancelAmountError: { type, message }
면세 금액 등 하위 항목들의 합이 전체 취소 금액을 초과한 경우
SumOfPartsExceedsTotalAmountError: { type, message }
면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
Trigger: "CONSOLE" | "API" | "PORTONE_ADMIN" | ...
UnauthorizedError: { type, message }
인증 정보가 올바르지 않은 경우
VirtualAccountIssuedPayment: { status, id, transactionId, ... }
가상계좌 발급 완료 상태 건
VirtualAccountIssuedPaymentTransaction: { status, id, paymentId, ... }
가상계좌 발급 완료 상태 건
WebhookNotFoundError: { type, message }
웹훅 내역이 존재하지 않는 경우