개발자센터

결제 관련 API

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

기간 내 모든 결제 이벤트를 커서 기반으로 조회합니다. 결제 이벤트의 생성일시를 기준으로 주어진 기간 내 존재하는 모든 결제 이벤트가 조회됩니다.

기간 내 모든 결제 건을 커서 기반으로 조회합니다. 결제 건의 생성일시를 기준으로 주어진 기간 내 존재하는 모든 결제 건이 조회됩니다.

빌링키로 결제를 진행합니다.

결제 취소를 요청합니다.

비동기적으로 수행되는 결제 취소 요청을 취소합니다. Triple-A에서만 사용됩니다.

수동 매입을 요청합니다. PG 및 포트원과의 사전 협의가 필요합니다.

수동 승인으로 설정된 인증 결제에 대해, 결제를 완료 처리합니다.

에스크로 결제를 구매 확정 처리합니다

에스크로 배송 정보를 등록합니다.

에스크로 배송 정보를 수정합니다.

카드 비인증 결제 또는 가상 계좌 발급을 API로 요청합니다.

결제 정보를 사전 등록합니다.

결제 내역 매출전표에 하위 상점의 거래를 등록합니다. 지원되는 PG사: KG이니시스(이용 전 콘솔 -> 결제연동 탭에서 INIApi Key 등록 필요)

웹훅을 재발송합니다.

주어진 아이디에 대응되는 결제 건의 결제 시도 내역을 조회합니다.

발급된 가상계좌를 말소합니다.

주어진 아이디에 대응되는 결제 건을 조회합니다.

주어진 조건에 맞는 결제 건들을 페이지 기반으로 조회합니다.

타입 정의

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 }
웹훅 내역이 존재하지 않는 경우