개발자센터
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
post/payments/{paymentId}/pre-register

결제 정보 사전 등록

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

totalAmount?: integer (64 bit)
결제 총 금액
(Optional)
taxFreeAmount?: integer (64 bit)
결제 면세 금액
(Optional)
currency?: Currency
통화 단위
(Optional)

통화 단위

OMRRial Omani
CUCPeso Convertible
BBDBarbados Dollar
PLNZloty
SVCEl Salvador Colon
BMDBermudian Dollar
TJSSomoni
TNDTunisian Dinar
GNFGuinean Franc
SDGSudanese Pound
MRUOuguiya
XBBBond Markets Unit European Monetary Unit (E.M.U.-6)
PKRPakistan Rupee
FKPFalkland Islands Pound
MURMauritius Rupee
XAFCFA Franc BEAC
SARSaudi Riyal
CADCanadian Dollar
HKDHong Kong Dollar
PYGGuarani
MGAMalagasy Ariary
UYIUruguay Peso en Unidades Indexadas (UI)
AUDAustralian Dollar
AMDArmenian Dram
YERYemeni Rial
CHEWIR Euro
MMKKyat
SEKSwedish Krona
TRYTurkish Lira
XBCBond Markets Unit European Unit of Account 9 (E.U.A.-9)
KESKenyan Shilling
GELLari
GTQQuetzal
TZSTanzanian Shilling
CUPCuban Peso
ALLLek
ERNNakfa
BRLBrazilian Real
UGXUganda Shilling
XUAADB Unit of Account
GIPGibraltar Pound
MZNMozambique Metical
KRW대한민국 원화
JODJordanian Dinar
IQDIraqi Dinar
VUVVatu
XXXThe codes assigned for transactions where no currency is involved
UZSUzbekistan Sum
BOVMvdol
UAHHryvnia
PENSol
KMFComorian Franc
DOPDominican Peso
BDTTaka
LKRSri Lanka Rupee
FJDFiji Dollar
LSLLoti
BSDBahamian Dollar
SRDSurinam Dollar
XTSCodes specifically reserved for testing purposes
SHPSaint Helena Pound
LRDLiberian Dollar
QARQatari Rial
BNDBrunei Dollar
CDFCongolese Franc
SLELeone
USNUS Dollar (Next day)
VESBolívar Soberano
TMTTurkmenistan New Manat
CHWWIR Franc
BGNBulgarian Lev
JMDJamaican Dollar
SZLLilangeni
CZKCzech Koruna
ZMWZambian Kwacha
UYUPeso Uruguayo
NPRNepalese Rupee
EGPEgyptian Pound
AZNAzerbaijan Manat
CLPChilean Peso
MOPPataca
SCRSeychelles Rupee
HTGGourde
VNDDong
LAKLao Kip
BTNNgultrum
GBPPound Sterling
SSPSouth Sudanese Pound
XPDPalladium
TWDNew Taiwan Dollar
DZDAlgerian Dinar
MXNMexican Peso
XDRSDR (Special Drawing Right)
ZWLZimbabwe Dollar
AWGAruban Florin
THBBaht
ISKIceland Krona
LBPLebanese Pound
SGDSingapore Dollar
MWKMalawi Kwacha
KZTTenge
CRCCosta Rican Colon
WSTTala
DJFDjibouti Franc
LYDLibyan Dinar
NGNNaira
BIFBurundi Franc
AEDUAE Dirham
CHFSwiss Franc
RWFRwanda Franc
XBDBond Markets Unit European Unit of Account 17 (E.U.A.-17)
INRIndian Rupee
CLFUnidad de Fomento
XOFCFA Franc BCEAO
COUUnidad de Valor Real
MXVMexican Unidad de Inversion (UDI)
PGKKina
CNYYuan Renminbi
SYPSyrian Pound
VEDBolívar Soberano
RONRomanian Leu
AFNAfghani
PHPPhilippine Peso
MDLMoldovan Leu
KHRRiel
XPTPlatinum
COPColombian Peso
DKKDanish Krone
KYDCayman Islands Dollar
XPFCFP Franc
GMDDalasi
MVRRufiyaa
STNDobra
TTDTrinidad and Tobago Dollar
PABBalboa
XAUGold
XAGSilver
JPY일본 엔화
TOPPa’anga
BWPPula
MKDDenar
ARSArgentine Peso
HUFForint
MYRMalaysian Ringgit
USD미국 달러
SLLLeone
MADMoroccan Dirham
RUBRussian Ruble
MNTTugrik
BOBBoliviano
GYDGuyana Dollar
SBDSolomon Islands Dollar
XBABond Markets Unit European Composite Unit (EURCO)
BHDBahraini Dinar
HNLLempira
UYWUnidad Previsional
NZDNew Zealand Dollar
XCDEast Caribbean Dollar
XSUSucre
KGSSom
AOAKwanza
BZDBelize Dollar
IDRRupiah
SOSSomali Shilling
NIOCordoba Oro
GHSGhana Cedi
ANGNetherlands Antillean Guilder
RSDSerbian Dinar
ILSNew Israeli Sheqel
NOKNorwegian Krone
KWDKuwaiti Dinar
NADNamibia Dollar
ETBEthiopian Birr
BYNBelarusian Ruble
KPWNorth Korean Won
EUREuro
CVECabo Verde Escudo
ZARRand
IRRIranian Rial
HRKKuna (Replaced by EUR)
BAMConvertible Mark

Response

200

성공 응답

400

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

401

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

403

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

409

  • AlreadyPaidError: 결제가 이미 완료된 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
get/payments/{paymentId}

결제 단건 조회

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

Request

Path

paymentId: string
조회할 결제 아이디

조회할 결제 아이디

Query

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

상점 아이디

Response

200

성공 응답으로 결제 건 객체를 반환합니다.

status: string (Union Tag)
결제 건 상태
필드의 값이 일 때 타입은 CancelledPayment 입니다.
id: string
결제 건 아이디
transactionId: string
결제 건 포트원 채번 아이디

V1 결제 건의 경우 imp_uid에 해당합니다.

merchantId: string
가맹점 아이디
storeId: string
상점 아이디
method?: PaymentMethod
결제수단 정보
(Optional)

결제수단 정보

type: string (Union Tag)
필드의 값이 일 때 타입은 PaymentMethodCard 입니다.
card?: Card
카드 상세 정보
(Optional)

카드 상세 정보

approvalNumber?: string
승인 번호
(Optional)
installment?: PaymentInstallment
할부 정보
(Optional)

할부 정보

pointUsed?: boolean
카드 포인트 사용여부
(Optional)
channel: SelectedChannel
(결제, 본인인증 등에) 선택된 채널 정보

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

type: SelectedChannelType
채널 타입

채널 타입

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

PG사 결제 모듈

pgMerchantId: string
PG사 가맹점 식별 아이디
version: PortOneVersion
포트원 버전

포트원 버전

V1
V2
scheduleId?: string
결제 예약 건 아이디
(Optional)

결제 예약을 이용한 경우에만 존재

billingKey?: string
결제 시 사용된 빌링키
(Optional)

빌링키 결제인 경우에만 존재

webhooks?: PaymentWebhook[]
웹훅 발송 내역
(Optional)
paymentStatus?: PaymentWebhookPaymentStatus
웹훅 발송 시 결제 건 상태
(Optional)

웹훅 발송 시 결제 건 상태

id: string
웹훅 아이디
status?: PaymentWebhookStatus
웹훅 전송 상태
(Optional)

웹훅 전송 상태

url: string
웹훅이 발송된 url

V1 결제 건인 경우, 값이 존재하지 않습니다.

isAsync?: boolean
비동기 웹훅 여부
(Optional)

V1 결제 건인 경우, 값이 존재하지 않습니다.

currentExecutionCount?: integer (32 bit)
현재 발송 횟수
(Optional)
maxExecutionCount?: integer (32 bit)
최대 발송 횟수
(Optional)
trigger?: PaymentWebhookTrigger
웹훅 실행 트리거
(Optional)

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

request?: PaymentWebhookRequest
웹훅 요청 정보
(Optional)

웹훅 요청 정보

response?: PaymentWebhookResponse
웹훅 응답 정보
(Optional)

웹훅 응답 정보

triggeredAt?: string (RFC 3339 date-time)
웹훅 처리 시작 시점
(Optional)
requestedAt: string (RFC 3339 date-time)
결제 요청 시점
updatedAt: string (RFC 3339 date-time)
업데이트 시점
statusChangedAt: string (RFC 3339 date-time)
상태 업데이트 시점
orderName: string
주문명
amount: PaymentAmount
결제 금액 세부 정보

결제 금액 세부 정보

total: integer (64 bit)
총 결제금액
taxFree: integer (64 bit)
면세액
vat?: integer (64 bit)
부가세액
(Optional)
supply?: integer (64 bit)
공급가액
(Optional)
discount: integer (64 bit)
할인금액

카드사 프로모션, 아임포트 프로모션, 적립형 포인트 결제, 쿠폰 할인 등을 포함합니다.

paid: integer (64 bit)
실제 결제금액
cancelled: integer (64 bit)
취소금액
cancelledTaxFree: integer (64 bit)
취소금액 중 면세액
currency: Currency
통화 단위

통화 단위

OMRRial Omani
CUCPeso Convertible
BBDBarbados Dollar
PLNZloty
SVCEl Salvador Colon
BMDBermudian Dollar
TJSSomoni
TNDTunisian Dinar
GNFGuinean Franc
SDGSudanese Pound
MRUOuguiya
XBBBond Markets Unit European Monetary Unit (E.M.U.-6)
PKRPakistan Rupee
FKPFalkland Islands Pound
MURMauritius Rupee
XAFCFA Franc BEAC
SARSaudi Riyal
CADCanadian Dollar
HKDHong Kong Dollar
PYGGuarani
MGAMalagasy Ariary
UYIUruguay Peso en Unidades Indexadas (UI)
AUDAustralian Dollar
AMDArmenian Dram
YERYemeni Rial
CHEWIR Euro
MMKKyat
SEKSwedish Krona
TRYTurkish Lira
XBCBond Markets Unit European Unit of Account 9 (E.U.A.-9)
KESKenyan Shilling
GELLari
GTQQuetzal
TZSTanzanian Shilling
CUPCuban Peso
ALLLek
ERNNakfa
BRLBrazilian Real
UGXUganda Shilling
XUAADB Unit of Account
GIPGibraltar Pound
MZNMozambique Metical
KRW대한민국 원화
JODJordanian Dinar
IQDIraqi Dinar
VUVVatu
XXXThe codes assigned for transactions where no currency is involved
UZSUzbekistan Sum
BOVMvdol
UAHHryvnia
PENSol
KMFComorian Franc
DOPDominican Peso
BDTTaka
LKRSri Lanka Rupee
FJDFiji Dollar
LSLLoti
BSDBahamian Dollar
SRDSurinam Dollar
XTSCodes specifically reserved for testing purposes
SHPSaint Helena Pound
LRDLiberian Dollar
QARQatari Rial
BNDBrunei Dollar
CDFCongolese Franc
SLELeone
USNUS Dollar (Next day)
VESBolívar Soberano
TMTTurkmenistan New Manat
CHWWIR Franc
BGNBulgarian Lev
JMDJamaican Dollar
SZLLilangeni
CZKCzech Koruna
ZMWZambian Kwacha
UYUPeso Uruguayo
NPRNepalese Rupee
EGPEgyptian Pound
AZNAzerbaijan Manat
CLPChilean Peso
MOPPataca
SCRSeychelles Rupee
HTGGourde
VNDDong
LAKLao Kip
BTNNgultrum
GBPPound Sterling
SSPSouth Sudanese Pound
XPDPalladium
TWDNew Taiwan Dollar
DZDAlgerian Dinar
MXNMexican Peso
XDRSDR (Special Drawing Right)
ZWLZimbabwe Dollar
AWGAruban Florin
THBBaht
ISKIceland Krona
LBPLebanese Pound
SGDSingapore Dollar
MWKMalawi Kwacha
KZTTenge
CRCCosta Rican Colon
WSTTala
DJFDjibouti Franc
LYDLibyan Dinar
NGNNaira
BIFBurundi Franc
AEDUAE Dirham
CHFSwiss Franc
RWFRwanda Franc
XBDBond Markets Unit European Unit of Account 17 (E.U.A.-17)
INRIndian Rupee
CLFUnidad de Fomento
XOFCFA Franc BCEAO
COUUnidad de Valor Real
MXVMexican Unidad de Inversion (UDI)
PGKKina
CNYYuan Renminbi
SYPSyrian Pound
VEDBolívar Soberano
RONRomanian Leu
AFNAfghani
PHPPhilippine Peso
MDLMoldovan Leu
KHRRiel
XPTPlatinum
COPColombian Peso
DKKDanish Krone
KYDCayman Islands Dollar
XPFCFP Franc
GMDDalasi
MVRRufiyaa
STNDobra
TTDTrinidad and Tobago Dollar
PABBalboa
XAUGold
XAGSilver
JPY일본 엔화
TOPPa’anga
BWPPula
MKDDenar
ARSArgentine Peso
HUFForint
MYRMalaysian Ringgit
USD미국 달러
SLLLeone
MADMoroccan Dirham
RUBRussian Ruble
MNTTugrik
BOBBoliviano
GYDGuyana Dollar
SBDSolomon Islands Dollar
XBABond Markets Unit European Composite Unit (EURCO)
BHDBahraini Dinar
HNLLempira
UYWUnidad Previsional
NZDNew Zealand Dollar
XCDEast Caribbean Dollar
XSUSucre
KGSSom
AOAKwanza
BZDBelize Dollar
IDRRupiah
SOSSomali Shilling
NIOCordoba Oro
GHSGhana Cedi
ANGNetherlands Antillean Guilder
RSDSerbian Dinar
ILSNew Israeli Sheqel
NOKNorwegian Krone
KWDKuwaiti Dinar
NADNamibia Dollar
ETBEthiopian Birr
BYNBelarusian Ruble
KPWNorth Korean Won
EUREuro
CVECabo Verde Escudo
ZARRand
IRRIranian Rial
HRKKuna (Replaced by EUR)
BAMConvertible Mark
customer: Customer
고객 정보

고객 정보

id?: string
고객 아이디
(Optional)

가맹점이 지정한 고객의 고유 식별자입니다.

name?: string
이름
(Optional)
birthYear?: string
출생 연도
(Optional)
gender?: Gender
성별
(Optional)

성별

email?: string
이메일
(Optional)
phoneNumber?: string
전화번호
(Optional)
address?: Address
분리 형식 주소
(Optional)

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

zipcode?: string
우편번호
(Optional)
promotionId?: string
프로모션 아이디
(Optional)
isCulturalExpense?: boolean
문화비 지출 여부
(Optional)
escrow?: PaymentEscrow
에스크로 정보
(Optional)

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

status: string (Union Tag)
에스크로 상태
필드의 값이 일 때 타입은 BeforeRegisteredPaymentEscrow 입니다.
products?: PaymentProduct[]
상품 정보
(Optional)
id: string
상품 고유 식별자

가맹점이 직접 부여한 식별자입니다.

name: string
상품명
tag?: string
상품 태그
(Optional)

카테고리 등으로 활용될 수 있습니다.

code?: string
상품 코드
(Optional)
amount: integer (64 bit)
상품 단위가격
quantity: integer (32 bit)
주문 수량
productCount?: integer (32 bit)
상품 갯수
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
country?: Country
국가
(Optional)

국가

CVCabo Verde
MAMorocco
AOAngola
VNViet Nam
INIndia
KWKuwait
MLMali
IDIndonesia
JEJersey
HMHeard Island and McDonald Islands
EGEgypt
BGBulgaria
SGSingapore
SVEl Salvador
BDBangladesh
TCTurks and Caicos Islands (the)
THThailand
ATAustria
GQEquatorial Guinea
TRTürkiye
HTHaiti
UMUnited States Minor Outlying Islands (the)
MHMarshall Islands (the)
MYMalaysia
RURussian Federation (the)
NINicaragua
BZBelize
KPKorea (the Democratic People's Republic of)
VEVenezuela (Bolivarian Republic of)
ILIsrael
GDGrenada
GIGibraltar
TNTunisia
DMDominica
MOMacao
PRPuerto Rico
NFNorfolk Island
TWTaiwan (Province of China)
KNSaint Kitts and Nevis
PHPhilippines (the)
WFWallis and Futuna
JOJordan
MEMontenegro
ESSpain
AZAzerbaijan
MRMauritania
SMSan Marino
BLSaint Barthélemy
PKPakistan
NZNew Zealand
GPGuadeloupe
NANamibia
JMJamaica
AXÅland Islands
CMCameroon
USUnited States of America (the)
GUGuam
SBSolomon Islands
MVMaldives
SISlovenia
CWCuraçao
BHBahrain
VGVirgin Islands (British)
HKHong Kong
SDSudan (the)
ADAndorra
RORomania
LULuxembourg
VCSaint Vincent and the Grenadines
FOFaroe Islands (the)
GLGreenland
BWBotswana
CFCentral African Republic (the)
CICôte d'Ivoire
KGKyrgyzstan
BVBouvet Island
KYCayman Islands (the)
LYLibya
MMMyanmar
MZMozambique
IRIran (Islamic Republic of)
EHWestern Sahara
IQIraq
BBBarbados
SZEswatini
IEIreland
FKFalkland Islands (the) [Malvinas]
NPNepal
BEBelgium
AUAustralia
TZTanzania, the United Republic of
UYUruguay
SASaudi Arabia
ZWZimbabwe
MDMoldova (the Republic of)
HUHungary
PGPapua New Guinea
AFAfghanistan
MUMauritius
SLSierra Leone
GTGuatemala
BOBolivia (Plurinational State of)
TMTurkmenistan
NENiger (the)
CLChile
FIFinland
MNMongolia
NONorway
GGGuernsey
EEEstonia
KMComoros (the)
LTLithuania
EREritrea
SHSaint Helena, Ascension and Tristan da Cunha
SYSyrian Arab Republic (the)
LCSaint Lucia
CCCocos (Keeling) Islands (the)
PLPoland
CHSwitzerland
STSao Tome and Principe
NGNigeria
TFFrench Southern Territories (the)
KIKiribati
LVLatvia
UGUganda
CYCyprus
MWMalawi
CGCongo (the)
MFSaint Martin (French part)
PMSaint Pierre and Miquelon
ISIceland
BIBurundi
TKTokelau
SESweden
AEUnited Arab Emirates (the)
KZKazakhstan
LBLebanon
ARArgentina
GSSouth Georgia and the South Sandwich Islands
BFBurkina Faso
DJDjibouti
BABosnia and Herzegovina
SJSvalbard and Jan Mayen
FRFrance
GMGambia (the)
HRCroatia
BSBahamas (the)
RSSerbia
WSSamoa
GBUnited Kingdom of Great Britain and Northern Ireland (the)
LSLesotho
UZUzbekistan
PFFrench Polynesia
AGAntigua and Barbuda
GWGuinea-Bissau
FJFiji
COColombia
ZMZambia
AQAntarctica
GFFrench Guiana
NUNiue
BNBrunei Darussalam
RWRwanda
PTPortugal
SOSomalia
MTMalta
PWPalau
KHCambodia
SXSint Maarten (Dutch part)
TJTajikistan
KRKorea (the Republic of)
SSSouth Sudan
PYParaguay
AMArmenia
MCMonaco
CXChristmas Island
TTTrinidad and Tobago
UAUkraine
LILiechtenstein
BRBrazil
PAPanama
MQMartinique
NRNauru
PNPitcairn
GAGabon
TGTogo
FMMicronesia (Federated States of)
GNGuinea
YTMayotte
CDCongo (the Democratic Republic of the)
MGMadagascar
AIAnguilla
YEYemen
HNHonduras
ITItaly
RERéunion
DODominican Republic (the)
IOBritish Indian Ocean Territory (the)
GRGreece
ASAmerican Samoa
ZASouth Africa
GYGuyana
BYBelarus
LKSri Lanka
BTBhutan
OMOman
CKCook Islands (the)
KEKenya
CZCzechia
GHGhana
MXMexico
SKSlovakia
MKNorth Macedonia
DZAlgeria
QAQatar
CUCuba
BJBenin
LALao People's Democratic Republic (the)
TLTimor-Leste
DKDenmark
VIVirgin Islands (U.S.)
NLNetherlands (Kingdom of the)
CACanada
BMBermuda
JPJapan
AWAruba
TOTonga
CNChina
VUVanuatu
ALAlbania
ETEthiopia
IMIsle of Man
SNSenegal
PEPeru
BQBonaire, Sint Eustatius and Saba
NCNew Caledonia
MPNorthern Mariana Islands (the)
GEGeorgia
CRCosta Rica
VAHoly See (the)
PSPalestine, State of
ECEcuador
TVTuvalu
LRLiberia
MSMontserrat
TDChad
SCSeychelles
DEGermany
SRSuriname
paidAt?: string (RFC 3339 date-time)
결제 완료 시점
(Optional)
cashReceipt?: PaymentCashReceipt
결제 건 내 현금영수증 정보
(Optional)

결제 건 내 현금영수증 정보

status: string (Union Tag)
결제 건 내 현금영수증 상태
필드의 값이 일 때 타입은 CancelledPaymentCashReceipt 입니다.
type?: CashReceiptType
발급 유형
(Optional)

발급 유형

pgReceiptId?: string
PG사 영수증 발급 아이디
(Optional)
issueNumber: string
승인 번호
totalAmount: integer (64 bit)
총 금액
taxFreeAmount?: integer (64 bit)
면세액
(Optional)
currency: Currency
통화 단위

통화 단위

url?: string
현금영수증 URL
(Optional)
issuedAt: string (RFC 3339 date-time)
발급 시점
cancelledAt: string (RFC 3339 date-time)
취소 시점
receiptUrl?: string
거래 영수증 URL
(Optional)
cancellations: PaymentCancellation[]
결제 취소 내역
status: string (Union Tag)
결제 취소 내역 상태
필드의 값이 일 때 타입은 FailedPaymentCancellation 입니다.
id: string
취소 내역 아이디
pgCancellationId?: string
PG사 결제 취소 내역 아이디
(Optional)
totalAmount: integer (64 bit)
취소 총 금액
taxFreeAmount: integer (64 bit)
취소 금액 중 면세 금액
vatAmount: integer (64 bit)
취소 금액 중 부가세액
easyPayDiscountAmount?: integer (64 bit)
적립형 포인트의 환불 금액
(Optional)
reason: string
취소 사유
cancelledAt?: string (RFC 3339 date-time)
취소 시점
(Optional)
requestedAt: string (RFC 3339 date-time)
취소 요청 시점
cancelledAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
get/payments

결제 다건 조회(페이지 기반)

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

Request

Query

requestBody?:
(Optional)

Body

page?: PageInput
다건 조회 API 에 사용되는 페이지 입력 정보
(Optional)

다건 조회 API 에 사용되는 페이지 입력 정보

number?: integer (32 bit)
0부터 시작하는 페이지 번호
(Optional)
size?: integer (32 bit)
각 페이지 당 포함할 객체 수
(Optional)
filter?: PaymentFilterInput
결제 건 다건 조회를 위한 입력 정보
(Optional)

결제 건 다건 조회를 위한 입력 정보

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

Merchant 사용자만 사용가능하며, 지정되지 않은 경우 가맹점 전체 결제 건을 조회합니다.

timestampType?: PaymentTimestampType
조회 시점 기준
(Optional)

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

from?: string (RFC 3339 date-time)
결제 요청/상태 승인 시점 범위의 시작
(Optional)

값을 입력하지 않으면 end의 90일 전으로 설정됩니다.

until?: string (RFC 3339 date-time)
결제 요청/상태 승인 시점 범위의 끝
(Optional)

값을 입력하지 않으면 현재 시점으로 설정됩니다.

status?: PaymentStatus[]
결제 상태 리스트
(Optional)

값을 입력하지 않으면 결제상태 필터링이 적용되지 않습니다.

methods?: PaymentMethodType[]
결제수단 리스트
(Optional)

값을 입력하지 않으면 결제수단 필터링이 적용되지 않습니다.

pgProvider?: PgProvider[]
PG사 리스트
(Optional)

값을 입력하지 않으면 결제대행사 필터링이 적용되지 않습니다.

isTest?: boolean
테스트 결제 필터링
(Optional)
isScheduled?: boolean
결제 예약 건 필터링
(Optional)
sortBy?: PaymentSortBy
결제 건 정렬 기준
(Optional)

결제 건 정렬 기준

sortOrder?: PaymentSortOrder
결제 건 정렬 방식
(Optional)

결제 건 정렬 방식

version?: PortOneVersion
포트원 버전
(Optional)

포트원 버전

webhookStatus?: PaymentWebhookStatus
웹훅 전송 상태
(Optional)

웹훅 전송 상태

platformType?: PaymentClientType
결제가 발생한 클라이언트 환경
(Optional)

결제가 발생한 클라이언트 환경

currency?: Currency
통화 단위
(Optional)

통화 단위

isEscrow?: boolean
에스크로 결제 여부
(Optional)
escrowStatus?: PaymentFilterInputEscrowStatus
에스크로 상태
(Optional)

에스크로 상태

cardBrand?: CardBrand
카드 브랜드
(Optional)

카드 브랜드

cardType?: CardType
카드 유형
(Optional)

카드 유형

cardOwnerType?: CardOwnerType
카드 소유주 유형
(Optional)

카드 소유주 유형

giftCertificateType?: PaymentMethodGiftCertificateType
상품권 종류
(Optional)

상품권 종류

cashReceiptType?: CashReceiptInputType
입력 시 발급 유형
(Optional)

입력 시 발급 유형

cashReceiptStatus?: PaymentCashReceiptStatus
결제건 내 현금영수증 상태
(Optional)

결제건 내 현금영수증 상태

cashReceiptIssuedAtRange?: DateTimeRange
시간 범위
(Optional)

시간 범위

cashReceiptCancelledAtRange?: DateTimeRange
시간 범위
(Optional)

시간 범위

textSearch?: PaymentTextSearch[]
통합 검색 리스트 필터
(Optional)

Response

200

성공 응답으로 조회된 결제 건 리스트와 페이지 정보가 반환됩니다.

items: Payment[]
조회된 결제 건 리스트
status: string (Union Tag)
결제 건 상태
필드의 값이 일 때 타입은 CancelledPayment 입니다.
id: string
결제 건 아이디
transactionId: string
결제 건 포트원 채번 아이디

V1 결제 건의 경우 imp_uid에 해당합니다.

merchantId: string
가맹점 아이디
storeId: string
상점 아이디
method?: PaymentMethod
결제수단 정보
(Optional)

결제수단 정보

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

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

version: PortOneVersion
포트원 버전

포트원 버전

scheduleId?: string
결제 예약 건 아이디
(Optional)

결제 예약을 이용한 경우에만 존재

billingKey?: string
결제 시 사용된 빌링키
(Optional)

빌링키 결제인 경우에만 존재

webhooks?: PaymentWebhook[]
웹훅 발송 내역
(Optional)
requestedAt: string (RFC 3339 date-time)
결제 요청 시점
updatedAt: string (RFC 3339 date-time)
업데이트 시점
statusChangedAt: string (RFC 3339 date-time)
상태 업데이트 시점
orderName: string
주문명
amount: PaymentAmount
결제 금액 세부 정보

결제 금액 세부 정보

currency: Currency
통화 단위

통화 단위

customer: Customer
고객 정보

고객 정보

promotionId?: string
프로모션 아이디
(Optional)
isCulturalExpense?: boolean
문화비 지출 여부
(Optional)
escrow?: PaymentEscrow
에스크로 정보
(Optional)

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

products?: PaymentProduct[]
상품 정보
(Optional)
productCount?: integer (32 bit)
상품 갯수
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
country?: Country
국가
(Optional)

국가

paidAt?: string (RFC 3339 date-time)
결제 완료 시점
(Optional)
cashReceipt?: PaymentCashReceipt
결제 건 내 현금영수증 정보
(Optional)

결제 건 내 현금영수증 정보

receiptUrl?: string
거래 영수증 URL
(Optional)
cancellations: PaymentCancellation[]
결제 취소 내역
cancelledAt: string (RFC 3339 date-time)
결제 취소 시점
page: PageInfo
반환된 페이지 결과 정보

반환된 페이지 결과 정보

number: integer (32 bit)
요청된 페이지 번호
size: integer (32 bit)
요청된 페이지 당 객체 수
totalCount: integer (32 bit)
실제 반환된 객체 수

400

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

401

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

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
get/payments-by-cursor

결제 대용량 다건 조회(커서 기반)unstable

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

Request

Query

requestBody?:
(Optional)

Body

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

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

from?: string (RFC 3339 date-time)
결제 건 생성시점 범위 조건의 시작
(Optional)

값을 입력하지 않으면 end의 90일 전으로 설정됩니다.

until?: string (RFC 3339 date-time)
결제 건 생성시점 범위 조건의 끝
(Optional)

값을 입력하지 않으면 현재 시점으로 설정됩니다.

cursor?: string
커서
(Optional)

결제 건 리스트 중 어디서부터 읽어야 할지 가리키는 값입니다. 최초 요청일 경우 값을 입력하지 마시되, 두번째 요청 부터는 이전 요청 응답값의 cursor를 입력해주시면 됩니다.

size?: integer (32 bit)
페이지 크기
(Optional)

미입력 시 기본값은 10 이며 최대 1000까지 허용

Response

200

성공 응답으로 조회된 결제 건 리스트와 커서 정보가 반환됩니다.

items: PaymentWithCursor[]
조회된 결제 건 및 커서 정보 리스트
payment: Payment
결제 건

결제 건

cursor: string
해당 결제 건의 커서 정보

400

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

401

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

403

  • ForbiddenError: 요청이 거절된 경우
type: string
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
post/payments/{paymentId}/cancel

결제 취소

결제 취소를 요청합니다.

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

amount?: integer (64 bit)
취소 총 금액
(Optional)

값을 입력하지 않으면 전액 취소됩니다.

taxFreeAmount?: integer (64 bit)
취소 금액 중 면세 금액
(Optional)

값을 입력하지 않으면 전액 과세 취소됩니다.

vatAmount?: integer (64 bit)
취소 금액 중 부가세액
(Optional)

값을 입력하지 않으면 자동 계산됩니다.

reason: string
취소 사유
currentCancellableAmount?: integer (64 bit)
결제 건의 취소 가능 잔액
(Optional)

본 취소 요청 이전의 취소 가능 잔액으로써, 값을 입력하면 잔액이 일치하는 경우에만 취소가 진행됩니다. 값을 입력하지 않으면 별도의 검증 처리를 수행하지 않습니다.

refundAccount?: CancelPaymentBodyRefundAccount
고객 정보 입력 형식
(Optional)

고객 정보 입력 형식

bank: Bank
은행

은행

number: string
계좌번호
holderName: string
예금주
holderPhoneNumber?: string
예금주 연락처 - 스마트로 가상계좌 결제인 경우에 필요합니다.
(Optional)

Response

200

성공 응답

cancellation: PaymentCancellation
결제 취소 내역

결제 취소 내역

status: string (Union Tag)
결제 취소 내역 상태
필드의 값이 일 때 타입은 FailedPaymentCancellation 입니다.
id: string
취소 내역 아이디
pgCancellationId?: string
PG사 결제 취소 내역 아이디
(Optional)
totalAmount: integer (64 bit)
취소 총 금액
taxFreeAmount: integer (64 bit)
취소 금액 중 면세 금액
vatAmount: integer (64 bit)
취소 금액 중 부가세액
easyPayDiscountAmount?: integer (64 bit)
적립형 포인트의 환불 금액
(Optional)
reason: string
취소 사유
cancelledAt?: string (RFC 3339 date-time)
취소 시점
(Optional)
requestedAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotPaidError: 결제가 완료되지 않은 경우
  • PaymentAlreadyCancelledError: 결제가 이미 취소된 경우
  • CancellableAmountConsistencyBrokenError: 취소 가능 잔액 검증에 실패한 경우
  • CancelAmountExceedsCancellableAmountError: 결제 취소 금액이 취소 가능 금액을 초과한 경우
  • SumOfPartsExceedsCancelAmountError: 면세 금액 등 하위 항목들의 합이 전체 취소 금액을 초과한 경우
  • CancelTaxFreeAmountExceedsCancellableTaxFreeAmountError: 취소 면세 금액이 취소 가능한 면세 금액을 초과한 경우
  • CancelTaxAmountExceedsCancellableTaxAmountError: 취소 과세 금액이 취소 가능한 과세 금액을 초과한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 CancellableAmountConsistencyBrokenError 입니다.
message?: string
(Optional)

502

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

빌링키 결제

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

billingKey: string
빌링키 결제에 사용할 빌링키
orderName: string
주문명
customer?: CustomerInput
고객 정보 입력 정보
(Optional)

고객 정보 입력 정보

id?: string
고객 아이디
(Optional)

가맹점이 지정한 고객의 고유 식별자입니다.

name?: CustomerNameInput
고객 이름 입력 정보
(Optional)

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

birthYear?: string
출생 연도
(Optional)
birthMonth?: string
출생월
(Optional)
birthDay?: string
출생일
(Optional)
country?: Country
국가
(Optional)

국가

gender?: Gender
성별
(Optional)

성별

email?: string
이메일
(Optional)
phoneNumber?: string
전화번호
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

zipcode?: string
우편번호
(Optional)
businessRegistrationNumber?: string
사업자 등록 번호
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
amount: PaymentAmountInput
금액 세부 입력 정보

금액 세부 입력 정보

total: integer (64 bit)
총 금액
taxFree?: integer (64 bit)
면세액
(Optional)
vat?: integer (64 bit)
부가세액
(Optional)

가맹점에서 직접 계산이 필요한 경우 입력합니다. 입력하지 않으면 면세 금액을 제외한 금액의 1/11 로 자동 계산됩니다.

currency: Currency
통화 단위

통화 단위

OMRRial Omani
CUCPeso Convertible
BBDBarbados Dollar
PLNZloty
SVCEl Salvador Colon
BMDBermudian Dollar
TJSSomoni
TNDTunisian Dinar
GNFGuinean Franc
SDGSudanese Pound
MRUOuguiya
XBBBond Markets Unit European Monetary Unit (E.M.U.-6)
PKRPakistan Rupee
FKPFalkland Islands Pound
MURMauritius Rupee
XAFCFA Franc BEAC
SARSaudi Riyal
CADCanadian Dollar
HKDHong Kong Dollar
PYGGuarani
MGAMalagasy Ariary
UYIUruguay Peso en Unidades Indexadas (UI)
AUDAustralian Dollar
AMDArmenian Dram
YERYemeni Rial
CHEWIR Euro
MMKKyat
SEKSwedish Krona
TRYTurkish Lira
XBCBond Markets Unit European Unit of Account 9 (E.U.A.-9)
KESKenyan Shilling
GELLari
GTQQuetzal
TZSTanzanian Shilling
CUPCuban Peso
ALLLek
ERNNakfa
BRLBrazilian Real
UGXUganda Shilling
XUAADB Unit of Account
GIPGibraltar Pound
MZNMozambique Metical
KRW대한민국 원화
JODJordanian Dinar
IQDIraqi Dinar
VUVVatu
XXXThe codes assigned for transactions where no currency is involved
UZSUzbekistan Sum
BOVMvdol
UAHHryvnia
PENSol
KMFComorian Franc
DOPDominican Peso
BDTTaka
LKRSri Lanka Rupee
FJDFiji Dollar
LSLLoti
BSDBahamian Dollar
SRDSurinam Dollar
XTSCodes specifically reserved for testing purposes
SHPSaint Helena Pound
LRDLiberian Dollar
QARQatari Rial
BNDBrunei Dollar
CDFCongolese Franc
SLELeone
USNUS Dollar (Next day)
VESBolívar Soberano
TMTTurkmenistan New Manat
CHWWIR Franc
BGNBulgarian Lev
JMDJamaican Dollar
SZLLilangeni
CZKCzech Koruna
ZMWZambian Kwacha
UYUPeso Uruguayo
NPRNepalese Rupee
EGPEgyptian Pound
AZNAzerbaijan Manat
CLPChilean Peso
MOPPataca
SCRSeychelles Rupee
HTGGourde
VNDDong
LAKLao Kip
BTNNgultrum
GBPPound Sterling
SSPSouth Sudanese Pound
XPDPalladium
TWDNew Taiwan Dollar
DZDAlgerian Dinar
MXNMexican Peso
XDRSDR (Special Drawing Right)
ZWLZimbabwe Dollar
AWGAruban Florin
THBBaht
ISKIceland Krona
LBPLebanese Pound
SGDSingapore Dollar
MWKMalawi Kwacha
KZTTenge
CRCCosta Rican Colon
WSTTala
DJFDjibouti Franc
LYDLibyan Dinar
NGNNaira
BIFBurundi Franc
AEDUAE Dirham
CHFSwiss Franc
RWFRwanda Franc
XBDBond Markets Unit European Unit of Account 17 (E.U.A.-17)
INRIndian Rupee
CLFUnidad de Fomento
XOFCFA Franc BCEAO
COUUnidad de Valor Real
MXVMexican Unidad de Inversion (UDI)
PGKKina
CNYYuan Renminbi
SYPSyrian Pound
VEDBolívar Soberano
RONRomanian Leu
AFNAfghani
PHPPhilippine Peso
MDLMoldovan Leu
KHRRiel
XPTPlatinum
COPColombian Peso
DKKDanish Krone
KYDCayman Islands Dollar
XPFCFP Franc
GMDDalasi
MVRRufiyaa
STNDobra
TTDTrinidad and Tobago Dollar
PABBalboa
XAUGold
XAGSilver
JPY일본 엔화
TOPPa’anga
BWPPula
MKDDenar
ARSArgentine Peso
HUFForint
MYRMalaysian Ringgit
USD미국 달러
SLLLeone
MADMoroccan Dirham
RUBRussian Ruble
MNTTugrik
BOBBoliviano
GYDGuyana Dollar
SBDSolomon Islands Dollar
XBABond Markets Unit European Composite Unit (EURCO)
BHDBahraini Dinar
HNLLempira
UYWUnidad Previsional
NZDNew Zealand Dollar
XCDEast Caribbean Dollar
XSUSucre
KGSSom
AOAKwanza
BZDBelize Dollar
IDRRupiah
SOSSomali Shilling
NIOCordoba Oro
GHSGhana Cedi
ANGNetherlands Antillean Guilder
RSDSerbian Dinar
ILSNew Israeli Sheqel
NOKNorwegian Krone
KWDKuwaiti Dinar
NADNamibia Dollar
ETBEthiopian Birr
BYNBelarusian Ruble
KPWNorth Korean Won
EUREuro
CVECabo Verde Escudo
ZARRand
IRRIranian Rial
HRKKuna (Replaced by EUR)
BAMConvertible Mark
installmentMonth?: integer (32 bit)
할부 개월 수
(Optional)
useFreeInterestFromMerchant?: boolean
무이자 할부 이자를 가맹점이 부담할지 여부
(Optional)
useCardPoint?: boolean
카드 포인트 사용 여부
(Optional)
cashReceipt?: CashReceiptInput
현금영수증 입력 정보
(Optional)

현금영수증 입력 정보

type: CashReceiptInputType
입력 시 발급 유형

입력 시 발급 유형

customerIdentityNumber?: string
사용자 식별 번호
(Optional)

미발행 유형 선택 시 입력하지 않습니다.

country?: Country
국가
(Optional)

국가

CVCabo Verde
MAMorocco
AOAngola
VNViet Nam
INIndia
KWKuwait
MLMali
IDIndonesia
JEJersey
HMHeard Island and McDonald Islands
EGEgypt
BGBulgaria
SGSingapore
SVEl Salvador
BDBangladesh
TCTurks and Caicos Islands (the)
THThailand
ATAustria
GQEquatorial Guinea
TRTürkiye
HTHaiti
UMUnited States Minor Outlying Islands (the)
MHMarshall Islands (the)
MYMalaysia
RURussian Federation (the)
NINicaragua
BZBelize
KPKorea (the Democratic People's Republic of)
VEVenezuela (Bolivarian Republic of)
ILIsrael
GDGrenada
GIGibraltar
TNTunisia
DMDominica
MOMacao
PRPuerto Rico
NFNorfolk Island
TWTaiwan (Province of China)
KNSaint Kitts and Nevis
PHPhilippines (the)
WFWallis and Futuna
JOJordan
MEMontenegro
ESSpain
AZAzerbaijan
MRMauritania
SMSan Marino
BLSaint Barthélemy
PKPakistan
NZNew Zealand
GPGuadeloupe
NANamibia
JMJamaica
AXÅland Islands
CMCameroon
USUnited States of America (the)
GUGuam
SBSolomon Islands
MVMaldives
SISlovenia
CWCuraçao
BHBahrain
VGVirgin Islands (British)
HKHong Kong
SDSudan (the)
ADAndorra
RORomania
LULuxembourg
VCSaint Vincent and the Grenadines
FOFaroe Islands (the)
GLGreenland
BWBotswana
CFCentral African Republic (the)
CICôte d'Ivoire
KGKyrgyzstan
BVBouvet Island
KYCayman Islands (the)
LYLibya
MMMyanmar
MZMozambique
IRIran (Islamic Republic of)
EHWestern Sahara
IQIraq
BBBarbados
SZEswatini
IEIreland
FKFalkland Islands (the) [Malvinas]
NPNepal
BEBelgium
AUAustralia
TZTanzania, the United Republic of
UYUruguay
SASaudi Arabia
ZWZimbabwe
MDMoldova (the Republic of)
HUHungary
PGPapua New Guinea
AFAfghanistan
MUMauritius
SLSierra Leone
GTGuatemala
BOBolivia (Plurinational State of)
TMTurkmenistan
NENiger (the)
CLChile
FIFinland
MNMongolia
NONorway
GGGuernsey
EEEstonia
KMComoros (the)
LTLithuania
EREritrea
SHSaint Helena, Ascension and Tristan da Cunha
SYSyrian Arab Republic (the)
LCSaint Lucia
CCCocos (Keeling) Islands (the)
PLPoland
CHSwitzerland
STSao Tome and Principe
NGNigeria
TFFrench Southern Territories (the)
KIKiribati
LVLatvia
UGUganda
CYCyprus
MWMalawi
CGCongo (the)
MFSaint Martin (French part)
PMSaint Pierre and Miquelon
ISIceland
BIBurundi
TKTokelau
SESweden
AEUnited Arab Emirates (the)
KZKazakhstan
LBLebanon
ARArgentina
GSSouth Georgia and the South Sandwich Islands
BFBurkina Faso
DJDjibouti
BABosnia and Herzegovina
SJSvalbard and Jan Mayen
FRFrance
GMGambia (the)
HRCroatia
BSBahamas (the)
RSSerbia
WSSamoa
GBUnited Kingdom of Great Britain and Northern Ireland (the)
LSLesotho
UZUzbekistan
PFFrench Polynesia
AGAntigua and Barbuda
GWGuinea-Bissau
FJFiji
COColombia
ZMZambia
AQAntarctica
GFFrench Guiana
NUNiue
BNBrunei Darussalam
RWRwanda
PTPortugal
SOSomalia
MTMalta
PWPalau
KHCambodia
SXSint Maarten (Dutch part)
TJTajikistan
KRKorea (the Republic of)
SSSouth Sudan
PYParaguay
AMArmenia
MCMonaco
CXChristmas Island
TTTrinidad and Tobago
UAUkraine
LILiechtenstein
BRBrazil
PAPanama
MQMartinique
NRNauru
PNPitcairn
GAGabon
TGTogo
FMMicronesia (Federated States of)
GNGuinea
YTMayotte
CDCongo (the Democratic Republic of the)
MGMadagascar
AIAnguilla
YEYemen
HNHonduras
ITItaly
RERéunion
DODominican Republic (the)
IOBritish Indian Ocean Territory (the)
GRGreece
ASAmerican Samoa
ZASouth Africa
GYGuyana
BYBelarus
LKSri Lanka
BTBhutan
OMOman
CKCook Islands (the)
KEKenya
CZCzechia
GHGhana
MXMexico
SKSlovakia
MKNorth Macedonia
DZAlgeria
QAQatar
CUCuba
BJBenin
LALao People's Democratic Republic (the)
TLTimor-Leste
DKDenmark
VIVirgin Islands (U.S.)
NLNetherlands (Kingdom of the)
CACanada
BMBermuda
JPJapan
AWAruba
TOTonga
CNChina
VUVanuatu
ALAlbania
ETEthiopia
IMIsle of Man
SNSenegal
PEPeru
BQBonaire, Sint Eustatius and Saba
NCNew Caledonia
MPNorthern Mariana Islands (the)
GEGeorgia
CRCosta Rica
VAHoly See (the)
PSPalestine, State of
ECEcuador
TVTuvalu
LRLiberia
MSMontserrat
TDChad
SCSeychelles
DEGermany
SRSuriname
noticeUrls?: string[]
웹훅 주소
(Optional)

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다. 입력된 값이 없을 경우에는 빈 배열로 해석됩니다.

products?: PaymentProduct[]
상품 정보
(Optional)

입력된 값이 없을 경우에는 빈 배열로 해석됩니다.

id: string
상품 고유 식별자

가맹점이 직접 부여한 식별자입니다.

name: string
상품명
tag?: string
상품 태그
(Optional)

카테고리 등으로 활용될 수 있습니다.

code?: string
상품 코드
(Optional)
amount: integer (64 bit)
상품 단위가격
quantity: integer (32 bit)
주문 수량
productCount?: integer (32 bit)
상품 개수
(Optional)
productType?: PaymentProductType
상품 유형
(Optional)

상품 유형

PHYSICAL실물 상품
DIGITAL디지털 상품

서비스, 온라인 상품 등 실물이 존재하지 않는 무형의 상품을 의미합니다.

shippingAddress?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

addressLine1: string
상세 주소 1
addressLine2: string
상세 주소 2
city?: string
시/군/구
(Optional)
province?: string
주/도/시
(Optional)
country?: Country
국가
(Optional)

국가

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

Response

200

성공 응답

payment: BillingKeyPaymentSummary
빌링키 결제 완료된 결제 건 요약 정보

빌링키 결제 완료된 결제 건 요약 정보

pgTxId: string
PG사 결제 아이디
paidAt: 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

  • BillingKeyNotFoundError: 빌링키가 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • AlreadyPaidError: 결제가 이미 완료된 경우
  • SumOfPartsExceedsTotalAmountError: 면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
  • BillingKeyAlreadyDeletedError: 빌링키가 이미 삭제된 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 AlreadyPaidError 입니다.
message?: string
(Optional)

502

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

수기 결제

수기 결제를 진행합니다.

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

channelKey: string
채널키
method: InstantPaymentMethodInput
수기 결제 수단 입력 정보

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

card?: InstantPaymentMethodInputCard
카드 수단 정보 입력 정보
(Optional)

카드 수단 정보 입력 정보

virtualAccount?: InstantPaymentMethodInputVirtualAccount
가상계좌 수단 정보 입력 정보
(Optional)

가상계좌 수단 정보 입력 정보

orderName: string
주문명
isCulturalExpense?: boolean
문화비 지출 여부
(Optional)

기본값은 false 입니다.

isEscrow?: boolean
에스크로 결제 여부
(Optional)

기본값은 false 입니다.

customer?: CustomerInput
고객 정보 입력 정보
(Optional)

고객 정보 입력 정보

id?: string
고객 아이디
(Optional)

가맹점이 지정한 고객의 고유 식별자입니다.

name?: CustomerNameInput
고객 이름 입력 정보
(Optional)

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

birthYear?: string
출생 연도
(Optional)
birthMonth?: string
출생월
(Optional)
birthDay?: string
출생일
(Optional)
country?: Country
국가
(Optional)

국가

gender?: Gender
성별
(Optional)

성별

email?: string
이메일
(Optional)
phoneNumber?: string
전화번호
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

zipcode?: string
우편번호
(Optional)
businessRegistrationNumber?: string
사업자 등록 번호
(Optional)
customData?: string
사용자 지정 데이터
(Optional)
amount: PaymentAmountInput
금액 세부 입력 정보

금액 세부 입력 정보

total: integer (64 bit)
총 금액
taxFree?: integer (64 bit)
면세액
(Optional)
vat?: integer (64 bit)
부가세액
(Optional)

가맹점에서 직접 계산이 필요한 경우 입력합니다. 입력하지 않으면 면세 금액을 제외한 금액의 1/11 로 자동 계산됩니다.

currency: Currency
통화 단위

통화 단위

OMRRial Omani
CUCPeso Convertible
BBDBarbados Dollar
PLNZloty
SVCEl Salvador Colon
BMDBermudian Dollar
TJSSomoni
TNDTunisian Dinar
GNFGuinean Franc
SDGSudanese Pound
MRUOuguiya
XBBBond Markets Unit European Monetary Unit (E.M.U.-6)
PKRPakistan Rupee
FKPFalkland Islands Pound
MURMauritius Rupee
XAFCFA Franc BEAC
SARSaudi Riyal
CADCanadian Dollar
HKDHong Kong Dollar
PYGGuarani
MGAMalagasy Ariary
UYIUruguay Peso en Unidades Indexadas (UI)
AUDAustralian Dollar
AMDArmenian Dram
YERYemeni Rial
CHEWIR Euro
MMKKyat
SEKSwedish Krona
TRYTurkish Lira
XBCBond Markets Unit European Unit of Account 9 (E.U.A.-9)
KESKenyan Shilling
GELLari
GTQQuetzal
TZSTanzanian Shilling
CUPCuban Peso
ALLLek
ERNNakfa
BRLBrazilian Real
UGXUganda Shilling
XUAADB Unit of Account
GIPGibraltar Pound
MZNMozambique Metical
KRW대한민국 원화
JODJordanian Dinar
IQDIraqi Dinar
VUVVatu
XXXThe codes assigned for transactions where no currency is involved
UZSUzbekistan Sum
BOVMvdol
UAHHryvnia
PENSol
KMFComorian Franc
DOPDominican Peso
BDTTaka
LKRSri Lanka Rupee
FJDFiji Dollar
LSLLoti
BSDBahamian Dollar
SRDSurinam Dollar
XTSCodes specifically reserved for testing purposes
SHPSaint Helena Pound
LRDLiberian Dollar
QARQatari Rial
BNDBrunei Dollar
CDFCongolese Franc
SLELeone
USNUS Dollar (Next day)
VESBolívar Soberano
TMTTurkmenistan New Manat
CHWWIR Franc
BGNBulgarian Lev
JMDJamaican Dollar
SZLLilangeni
CZKCzech Koruna
ZMWZambian Kwacha
UYUPeso Uruguayo
NPRNepalese Rupee
EGPEgyptian Pound
AZNAzerbaijan Manat
CLPChilean Peso
MOPPataca
SCRSeychelles Rupee
HTGGourde
VNDDong
LAKLao Kip
BTNNgultrum
GBPPound Sterling
SSPSouth Sudanese Pound
XPDPalladium
TWDNew Taiwan Dollar
DZDAlgerian Dinar
MXNMexican Peso
XDRSDR (Special Drawing Right)
ZWLZimbabwe Dollar
AWGAruban Florin
THBBaht
ISKIceland Krona
LBPLebanese Pound
SGDSingapore Dollar
MWKMalawi Kwacha
KZTTenge
CRCCosta Rican Colon
WSTTala
DJFDjibouti Franc
LYDLibyan Dinar
NGNNaira
BIFBurundi Franc
AEDUAE Dirham
CHFSwiss Franc
RWFRwanda Franc
XBDBond Markets Unit European Unit of Account 17 (E.U.A.-17)
INRIndian Rupee
CLFUnidad de Fomento
XOFCFA Franc BCEAO
COUUnidad de Valor Real
MXVMexican Unidad de Inversion (UDI)
PGKKina
CNYYuan Renminbi
SYPSyrian Pound
VEDBolívar Soberano
RONRomanian Leu
AFNAfghani
PHPPhilippine Peso
MDLMoldovan Leu
KHRRiel
XPTPlatinum
COPColombian Peso
DKKDanish Krone
KYDCayman Islands Dollar
XPFCFP Franc
GMDDalasi
MVRRufiyaa
STNDobra
TTDTrinidad and Tobago Dollar
PABBalboa
XAUGold
XAGSilver
JPY일본 엔화
TOPPa’anga
BWPPula
MKDDenar
ARSArgentine Peso
HUFForint
MYRMalaysian Ringgit
USD미국 달러
SLLLeone
MADMoroccan Dirham
RUBRussian Ruble
MNTTugrik
BOBBoliviano
GYDGuyana Dollar
SBDSolomon Islands Dollar
XBABond Markets Unit European Composite Unit (EURCO)
BHDBahraini Dinar
HNLLempira
UYWUnidad Previsional
NZDNew Zealand Dollar
XCDEast Caribbean Dollar
XSUSucre
KGSSom
AOAKwanza
BZDBelize Dollar
IDRRupiah
SOSSomali Shilling
NIOCordoba Oro
GHSGhana Cedi
ANGNetherlands Antillean Guilder
RSDSerbian Dinar
ILSNew Israeli Sheqel
NOKNorwegian Krone
KWDKuwaiti Dinar
NADNamibia Dollar
ETBEthiopian Birr
BYNBelarusian Ruble
KPWNorth Korean Won
EUREuro
CVECabo Verde Escudo
ZARRand
IRRIranian Rial
HRKKuna (Replaced by EUR)
BAMConvertible Mark
country?: Country
국가
(Optional)

국가

CVCabo Verde
MAMorocco
AOAngola
VNViet Nam
INIndia
KWKuwait
MLMali
IDIndonesia
JEJersey
HMHeard Island and McDonald Islands
EGEgypt
BGBulgaria
SGSingapore
SVEl Salvador
BDBangladesh
TCTurks and Caicos Islands (the)
THThailand
ATAustria
GQEquatorial Guinea
TRTürkiye
HTHaiti
UMUnited States Minor Outlying Islands (the)
MHMarshall Islands (the)
MYMalaysia
RURussian Federation (the)
NINicaragua
BZBelize
KPKorea (the Democratic People's Republic of)
VEVenezuela (Bolivarian Republic of)
ILIsrael
GDGrenada
GIGibraltar
TNTunisia
DMDominica
MOMacao
PRPuerto Rico
NFNorfolk Island
TWTaiwan (Province of China)
KNSaint Kitts and Nevis
PHPhilippines (the)
WFWallis and Futuna
JOJordan
MEMontenegro
ESSpain
AZAzerbaijan
MRMauritania
SMSan Marino
BLSaint Barthélemy
PKPakistan
NZNew Zealand
GPGuadeloupe
NANamibia
JMJamaica
AXÅland Islands
CMCameroon
USUnited States of America (the)
GUGuam
SBSolomon Islands
MVMaldives
SISlovenia
CWCuraçao
BHBahrain
VGVirgin Islands (British)
HKHong Kong
SDSudan (the)
ADAndorra
RORomania
LULuxembourg
VCSaint Vincent and the Grenadines
FOFaroe Islands (the)
GLGreenland
BWBotswana
CFCentral African Republic (the)
CICôte d'Ivoire
KGKyrgyzstan
BVBouvet Island
KYCayman Islands (the)
LYLibya
MMMyanmar
MZMozambique
IRIran (Islamic Republic of)
EHWestern Sahara
IQIraq
BBBarbados
SZEswatini
IEIreland
FKFalkland Islands (the) [Malvinas]
NPNepal
BEBelgium
AUAustralia
TZTanzania, the United Republic of
UYUruguay
SASaudi Arabia
ZWZimbabwe
MDMoldova (the Republic of)
HUHungary
PGPapua New Guinea
AFAfghanistan
MUMauritius
SLSierra Leone
GTGuatemala
BOBolivia (Plurinational State of)
TMTurkmenistan
NENiger (the)
CLChile
FIFinland
MNMongolia
NONorway
GGGuernsey
EEEstonia
KMComoros (the)
LTLithuania
EREritrea
SHSaint Helena, Ascension and Tristan da Cunha
SYSyrian Arab Republic (the)
LCSaint Lucia
CCCocos (Keeling) Islands (the)
PLPoland
CHSwitzerland
STSao Tome and Principe
NGNigeria
TFFrench Southern Territories (the)
KIKiribati
LVLatvia
UGUganda
CYCyprus
MWMalawi
CGCongo (the)
MFSaint Martin (French part)
PMSaint Pierre and Miquelon
ISIceland
BIBurundi
TKTokelau
SESweden
AEUnited Arab Emirates (the)
KZKazakhstan
LBLebanon
ARArgentina
GSSouth Georgia and the South Sandwich Islands
BFBurkina Faso
DJDjibouti
BABosnia and Herzegovina
SJSvalbard and Jan Mayen
FRFrance
GMGambia (the)
HRCroatia
BSBahamas (the)
RSSerbia
WSSamoa
GBUnited Kingdom of Great Britain and Northern Ireland (the)
LSLesotho
UZUzbekistan
PFFrench Polynesia
AGAntigua and Barbuda
GWGuinea-Bissau
FJFiji
COColombia
ZMZambia
AQAntarctica
GFFrench Guiana
NUNiue
BNBrunei Darussalam
RWRwanda
PTPortugal
SOSomalia
MTMalta
PWPalau
KHCambodia
SXSint Maarten (Dutch part)
TJTajikistan
KRKorea (the Republic of)
SSSouth Sudan
PYParaguay
AMArmenia
MCMonaco
CXChristmas Island
TTTrinidad and Tobago
UAUkraine
LILiechtenstein
BRBrazil
PAPanama
MQMartinique
NRNauru
PNPitcairn
GAGabon
TGTogo
FMMicronesia (Federated States of)
GNGuinea
YTMayotte
CDCongo (the Democratic Republic of the)
MGMadagascar
AIAnguilla
YEYemen
HNHonduras
ITItaly
RERéunion
DODominican Republic (the)
IOBritish Indian Ocean Territory (the)
GRGreece
ASAmerican Samoa
ZASouth Africa
GYGuyana
BYBelarus
LKSri Lanka
BTBhutan
OMOman
CKCook Islands (the)
KEKenya
CZCzechia
GHGhana
MXMexico
SKSlovakia
MKNorth Macedonia
DZAlgeria
QAQatar
CUCuba
BJBenin
LALao People's Democratic Republic (the)
TLTimor-Leste
DKDenmark
VIVirgin Islands (U.S.)
NLNetherlands (Kingdom of the)
CACanada
BMBermuda
JPJapan
AWAruba
TOTonga
CNChina
VUVanuatu
ALAlbania
ETEthiopia
IMIsle of Man
SNSenegal
PEPeru
BQBonaire, Sint Eustatius and Saba
NCNew Caledonia
MPNorthern Mariana Islands (the)
GEGeorgia
CRCosta Rica
VAHoly See (the)
PSPalestine, State of
ECEcuador
TVTuvalu
LRLiberia
MSMontserrat
TDChad
SCSeychelles
DEGermany
SRSuriname
noticeUrls?: string[]
웹훅 주소
(Optional)

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다. 입력된 값이 없을 경우에는 빈 배열로 해석됩니다.

products?: PaymentProduct[]
상품 정보
(Optional)

입력된 값이 없을 경우에는 빈 배열로 해석됩니다.

id: string
상품 고유 식별자

가맹점이 직접 부여한 식별자입니다.

name: string
상품명
tag?: string
상품 태그
(Optional)

카테고리 등으로 활용될 수 있습니다.

code?: string
상품 코드
(Optional)
amount: integer (64 bit)
상품 단위가격
quantity: integer (32 bit)
주문 수량
productCount?: integer (32 bit)
상품 개수
(Optional)
productType?: PaymentProductType
상품 유형
(Optional)

상품 유형

PHYSICAL실물 상품
DIGITAL디지털 상품

서비스, 온라인 상품 등 실물이 존재하지 않는 무형의 상품을 의미합니다.

shippingAddress?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

addressLine1: string
상세 주소 1
addressLine2: string
상세 주소 2
city?: string
시/군/구
(Optional)
province?: string
주/도/시
(Optional)
country?: Country
국가
(Optional)

국가

Response

200

성공 응답

payment: InstantPaymentSummary
수기 결제가 완료된 결제 건 요약 정보

수기 결제가 완료된 결제 건 요약 정보

pgTxId: string
PG사 결제 아이디
paidAt: 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

  • ChannelNotFoundError: 요청된 채널이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • AlreadyPaidError: 결제가 이미 완료된 경우
  • SumOfPartsExceedsTotalAmountError: 면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 AlreadyPaidError 입니다.
message?: string
(Optional)

502

  • PgProviderError: PG사에서 오류가 발생한 경우
type: string
message?: string
(Optional)
pgCode: string
pgMessage: string
try
Request
Response Status: N/A
N/A
post/payments/{paymentId}/virtual-account/close

가상계좌 말소

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Query

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

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

Response

200

성공 응답

closedAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotWaitingForDepositError: 결제 건이 입금 대기 상태가 아닌 경우
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/payments/{paymentId}/escrow/logistics

에스크로 배송 정보 등록

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

sender?: PaymentEscrowSenderInput
에스크로 발송자 정보
(Optional)

에스크로 발송자 정보

name?: string
이름
(Optional)
phoneNumber?: string
전화번호
(Optional)
zipcode?: string
우편번호
(Optional)
relationship?: string
수취인과의 관계
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

receiver?: PaymentEscrowReceiverInput
에스크로 수취인 정보
(Optional)

에스크로 수취인 정보

name?: string
이름
(Optional)
phoneNumber?: string
전화번호
(Optional)
zipcode?: string
우편번호
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

logistics: PaymentLogistics
배송정보

배송정보

company: PaymentLogisticsCompany
물류 회사

물류 회사

invoiceNumber: string
송장번호
sentAt: string (RFC 3339 date-time)
발송시점
receivedAt?: string (RFC 3339 date-time)
수령시점
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

sendEmail?: boolean
이메일 알림 전송 여부
(Optional)

에스크로 구매 확정 시 이메일로 알림을 보낼지 여부입니다.

products?: PaymentProduct[]
상품 정보
(Optional)
id: string
상품 고유 식별자

가맹점이 직접 부여한 식별자입니다.

name: string
상품명
tag?: string
상품 태그
(Optional)

카테고리 등으로 활용될 수 있습니다.

code?: string
상품 코드
(Optional)
amount: integer (64 bit)
상품 단위가격
quantity: integer (32 bit)
주문 수량

Response

200

성공 응답

invoiceNumber: string
송장 번호
sentAt: string (RFC 3339 date-time)
발송 시점
appliedAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotPaidError: 결제가 완료되지 않은 경우
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
patch/payments/{paymentId}/escrow/logistics

에스크로 배송 정보 수정

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

sender?: PaymentEscrowSenderInput
에스크로 발송자 정보
(Optional)

에스크로 발송자 정보

name?: string
이름
(Optional)
phoneNumber?: string
전화번호
(Optional)
zipcode?: string
우편번호
(Optional)
relationship?: string
수취인과의 관계
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

receiver?: PaymentEscrowReceiverInput
에스크로 수취인 정보
(Optional)

에스크로 수취인 정보

name?: string
이름
(Optional)
phoneNumber?: string
전화번호
(Optional)
zipcode?: string
우편번호
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

logistics: PaymentLogistics
배송정보

배송정보

company: PaymentLogisticsCompany
물류 회사

물류 회사

invoiceNumber: string
송장번호
sentAt: string (RFC 3339 date-time)
발송시점
receivedAt?: string (RFC 3339 date-time)
수령시점
(Optional)
address?: SeparatedAddressInput
분리 형식 주소 입력 정보
(Optional)

분리 형식 주소 입력 정보

sendEmail?: boolean
이메일 알림 전송 여부
(Optional)

에스크로 구매 확정 시 이메일로 알림을 보낼지 여부입니다.

products?: PaymentProduct[]
상품 정보
(Optional)
id: string
상품 고유 식별자

가맹점이 직접 부여한 식별자입니다.

name: string
상품명
tag?: string
상품 태그
(Optional)

카테고리 등으로 활용될 수 있습니다.

code?: string
상품 코드
(Optional)
amount: integer (64 bit)
상품 단위가격
quantity: integer (32 bit)
주문 수량

Response

200

성공 응답

invoiceNumber: string
송장 번호
sentAt: string (RFC 3339 date-time)
발송 시점
modifiedAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotPaidError: 결제가 완료되지 않은 경우
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/payments/{paymentId}/escrow/complete

에스크로 구매 확정

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

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

fromStore?: boolean
확인 주체가 상점인지 여부
(Optional)

구매확정요청 주체가 가맹점 관리자인지 구매자인지 구분하기 위한 필드입니다. 네이버페이 전용 파라미터이며, 구분이 모호한 경우 가맹점 관리자(true)로 입력합니다.

Response

200

성공 응답

completedAt: 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

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotPaidError: 결제가 완료되지 않은 경우
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/payments/{paymentId}/resend-webhook

웹훅 재발송

웹훅을 재발송합니다.

Request

Path

paymentId: string
결제 건 아이디

결제 건 아이디

Body

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

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

webhookId?: string
웹훅 아이디
(Optional)

입력하지 않으면 결제 건의 가장 최근 웹훅 아이디가 기본 적용됩니다

Response

200

성공 응답

webhook: PaymentWebhook
성공 웹훅 내역

성공 웹훅 내역

paymentStatus?: PaymentWebhookPaymentStatus
웹훅 발송 시 결제 건 상태
(Optional)

웹훅 발송 시 결제 건 상태

id: string
웹훅 아이디
status?: PaymentWebhookStatus
웹훅 전송 상태
(Optional)

웹훅 전송 상태

url: string
웹훅이 발송된 url

V1 결제 건인 경우, 값이 존재하지 않습니다.

isAsync?: boolean
비동기 웹훅 여부
(Optional)

V1 결제 건인 경우, 값이 존재하지 않습니다.

currentExecutionCount?: integer (32 bit)
현재 발송 횟수
(Optional)
maxExecutionCount?: integer (32 bit)
최대 발송 횟수
(Optional)
trigger?: PaymentWebhookTrigger
웹훅 실행 트리거
(Optional)

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

request?: PaymentWebhookRequest
웹훅 요청 정보
(Optional)

웹훅 요청 정보

response?: PaymentWebhookResponse
웹훅 응답 정보
(Optional)

웹훅 응답 정보

triggeredAt?: string (RFC 3339 date-time)
웹훅 처리 시작 시점
(Optional)

400

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

401

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

403

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

404

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
  • WebhookNotFoundError: 웹훅 내역이 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.
message?: string
(Optional)
try
Request
Response Status: N/A
N/A
post/payments/{paymentId}/register-store-receipt

영수증 내 하위 상점 거래 등록 API

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

Request

Path

paymentId: string
등록할 하위 상점 결제 건 아이디

등록할 하위 상점 결제 건 아이디

Body

items: RegisterStoreReceiptBodyItem[]
하위 상점 거래 목록
storeBusinessRegistrationNumber: string
하위 상점 사업자등록번호
storeName: string
하위 상점명
totalAmount: integer (64 bit)
결제 총 금액
taxFreeAmount?: integer (64 bit)
면세액
(Optional)
vatAmount?: integer (64 bit)
부가세액
(Optional)
supplyAmount?: integer (64 bit)
공급가액
(Optional)
currency: Currency
통화 단위

통화 단위

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

Response

200

성공 응답

receiptUrl?: string
결제 영수증 URL
(Optional)

400

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

401

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

403

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

404

  • PaymentNotFoundError: 결제 건이 존재하지 않는 경우
type: string
message?: string
(Optional)

409

  • PaymentNotPaidError: 결제가 완료되지 않은 경우
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

결제 예약 관련 API

결제 예약과 관련된 API 기능을 제공합니다.

빌링키 관련 API

빌링키와 관련된 API 기능을 제공합니다.

현금 영수증 관련 API

현금 영수증과 관련된 API 기능을 제공합니다.

본인인증 관련 API

본인인증과 관련된 API 기능을 제공합니다.

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