PortOne REST API - V2

API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.

V2 API hostname: api.portone.io

OpenAPI JSON 내려받기Postman 등에서 import하여 활용할 수 있습니다.

요청 및 응답 형식

요청과 응답의 본문은 JSON 형식입니다.

API 매개 변수 중 URL 경로에 들어가는 문자열 값이 있는 경우, URL 경로에 들어갈 수 없는 문자열은 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent 함수 등을 사용할 수 있습니다.

인증 방식

V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 관리자콘솔 내 결제연동 탭에서 발급받으실 수 있습니다.

인증 관련 API를 제외한 모든 API는 HTTP Authorization 헤더로 아래 형식의 인증 정보를 전달해주셔야 합니다.

Authorization: PortOne MY_API_SECRET

GET 요청 시 Body 대신 Query 사용하기

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

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

하위호환성

포트원이 제공하는 모든 Stable API에 대해 아래와 같은 하위호환성이 보장됩니다.

현재 사용 가능한 입력 형식은 앞으로도 사용할 수 있습니다.
- 입력 형식 내 필드 정의가 삭제되지 않습니다.
- 필수 입력 정보가 추가되거나, 선택 입력 정보가 필수로 변경되지 않습니다.
  - 오로지 선택 입력 정보만 추가될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
- enum 타입의 값이 삭제되지 않습니다.
출력 형식이 확장될 수 있지만, 축소되지 않습니다.
- 출력 형식 내 필드 정의가 삭제되지 않습니다.
- 사용 중인 필수 출력 정보가 선택사항으로 변경되거나 출력 시 누락되지 않습니다.
  - 이미 존재하는 용례 내에서는 필수 출력 정보가 언제나 유지됩니다.
  - 단, 기능이 추가 및 확장되는 등 새로운 용례로 사용될 때의 출력 정보에 한하여 선택사항으로 변경될 수 있습니다.
- 하위 필드의 형식(타입) 또한 위 규칙을 지키며 변경됩니다.
- 단, 새로운 필드 또는 enum 값, oneOf 케이스가 추가될 수 있습니다.
  - 알지 못하는 필드 및 값이 주어지더라도 crash가 발생하지 않도록 유의하여 개발해주세요.

UNSTABLE이 표기된 일부 API의 경우, 위 하위호환성 정책과 무관하게 변경 및 지원 종료될 수 있으니 이용에 유의하세요.

인증 관련 API

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

결제 관련 API

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

결제 정보 사전 등록

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

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

409

AlreadyPaidError: 결제가 이미 완료된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 AlreadyPaidError 입니다.

message?: string

(Optional)

try

Request

Request Sample

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사 결제 모듈

pgMerchantId: string

PG사 고객사 식별 아이디

channelGroup?: ChannelGroupSummary

채널 그룹 정보

(Optional)

채널 그룹 정보

id: string

채널 그룹 아이디

채널 그룹 이름

isForTest: boolean

테스트 채널 그룹 여부

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

상품 고유 식별자

고객사가 직접 부여한 식별자입니다.

상품명

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)

pgTxId?: string

PG사 거래 아이디

(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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

try

Request

Request Sample

N/A

get/payments

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

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

Request

Query

requestBody?:

(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

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

channelGroup?: ChannelGroupSummary

채널 그룹 정보

(Optional)

채널 그룹 정보

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)

pgTxId?: string

PG사 거래 아이디

(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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

try

Request

Request Sample

N/A

get/payments-by-cursor

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

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

Request

Query

requestBody?:

(Optional)

Response

200

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

items: PaymentWithCursor[]

조회된 결제 건 및 커서 정보 리스트

payment: Payment

결제 건

cursor: string

해당 결제 건의 커서 정보

400

InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

try

Request

Request Sample

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

취소 사유

requester?: CancelRequester

CancelRequester

(Optional)

CUSTOMER

ADMIN

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotPaidError: 결제가 완료되지 않은 경우
PaymentAlreadyCancelledError: 결제가 이미 취소된 경우
CancellableAmountConsistencyBrokenError: 취소 가능 잔액 검증에 실패한 경우
CancelAmountExceedsCancellableAmountError: 결제 취소 금액이 취소 가능 금액을 초과한 경우
SumOfPartsExceedsCancelAmountError: 면세 금액 등 하위 항목들의 합이 전체 취소 금액을 초과한 경우
CancelTaxFreeAmountExceedsCancellableTaxFreeAmountError: 취소 면세 금액이 취소 가능한 면세 금액을 초과한 경우
CancelTaxAmountExceedsCancellableTaxAmountError: 취소 과세 금액이 취소 가능한 과세 금액을 초과한 경우
RemainedAmountLessThanPromotionMinPaymentAmountError: 부분 취소 시, 취소하게 될 경우 남은 금액이 프로모션의 최소 결제 금액보다 작아지는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 CancellableAmountConsistencyBrokenError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

N/A

post/payments/{paymentId}/billing-key

빌링키 결제

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

Request

Path

paymentId: string

결제 건 아이디

Body

storeId?: string

상점 아이디

(Optional)

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

billingKey: string

빌링키 결제에 사용할 빌링키

channelKey?: string

채널 키

(Optional)

다수 채널에 대해 발급된 빌링키에 대해, 결제 채널을 특정하고 싶을 때 명시

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

상품 고유 식별자

고객사가 직접 부여한 식별자입니다.

상품명

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)

국가

promotionId?: string

해당 결제에 적용할 프로모션 아이디

(Optional)

bypass?: object

PG사별 추가 파라미터 ("PG사별 연동 가이드" 참고)

(Optional)

Response

200

성공 응답

payment: BillingKeyPaymentSummary

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

pgTxId: string

PG사 결제 아이디

paidAt: string (RFC 3339 date-time)

결제 완료 시점

400

InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
PromotionPayMethodDoesNotMatchError: 결제수단이 프로모션에 지정된 것과 일치하지 않는 경우
DiscountAmountExceedsTotalAmountError: 프로모션 할인 금액이 결제 시도 금액 이상인 경우
MaxTransactionCountReachedError: 결제 혹은 본인인증 시도 횟수가 최대에 도달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 DiscountAmountExceedsTotalAmountError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

BillingKeyNotFoundError: 빌링키가 존재하지 않는 경우
ChannelNotFoundError: 요청된 채널이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 BillingKeyNotFoundError 입니다.

message?: string

(Optional)

409

AlreadyPaidError: 결제가 이미 완료된 경우
SumOfPartsExceedsTotalAmountError: 면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
BillingKeyAlreadyDeletedError: 빌링키가 이미 삭제된 경우
PaymentScheduleAlreadyExistsError: 결제 예약건이 이미 존재하는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 AlreadyPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

N/A

post/payments/{paymentId}/instant

수기 결제

수기 결제를 진행합니다.

Request

Path

paymentId: string

결제 건 아이디

Body

storeId?: string

상점 아이디

(Optional)

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

channelKey?: string

채널 키

(Optional)

채널 키 또는 채널 그룹 ID 필수

channelGroupId?: string

채널 그룹 ID

(Optional)

채널 키 또는 채널 그룹 ID 필수

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

상품 고유 식별자

고객사가 직접 부여한 식별자입니다.

상품명

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)

국가

promotionId?: string

해당 결제에 적용할 프로모션 아이디

(Optional)

Response

200

성공 응답

payment: InstantPaymentSummary

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

pgTxId: string

PG사 결제 아이디

paidAt: string (RFC 3339 date-time)

결제 완료 시점

400

InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
PromotionPayMethodDoesNotMatchError: 결제수단이 프로모션에 지정된 것과 일치하지 않는 경우
DiscountAmountExceedsTotalAmountError: 프로모션 할인 금액이 결제 시도 금액 이상인 경우
MaxTransactionCountReachedError: 결제 혹은 본인인증 시도 횟수가 최대에 도달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 DiscountAmountExceedsTotalAmountError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

ChannelNotFoundError: 요청된 채널이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ChannelNotFoundError 입니다.

message?: string

(Optional)

409

AlreadyPaidError: 결제가 이미 완료된 경우
SumOfPartsExceedsTotalAmountError: 면세 금액 등 하위 항목들의 합이 전체 결제 금액을 초과한 경우
PaymentScheduleAlreadyExistsError: 결제 예약건이 이미 존재하는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 AlreadyPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotWaitingForDepositError: 결제 건이 입금 대기 상태가 아닌 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotWaitingForDepositError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

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

상품 고유 식별자

고객사가 직접 부여한 식별자입니다.

상품명

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotPaidError: 결제가 완료되지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

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

상품 고유 식별자

고객사가 직접 부여한 식별자입니다.

상품명

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotPaidError: 결제가 완료되지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotPaidError: 결제가 완료되지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

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: 요청된 입력 정보가 유효하지 않은 경우
MaxWebhookRetryCountReachedError: 동일한 webhook id에 대한 수동 재시도 횟수가 최대에 도달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우
WebhookNotFoundError: 웹훅 내역이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

try

Request

Request Sample

N/A

post/payments/{paymentId}/register-store-receipt

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

결제 내역 매출전표에 하위 상점의 거래를 등록합니다. 지원되는 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 (Union Tag)

필드의 값이 일 때 타입은 InvalidRequestError 입니다.

message?: string

(Optional)

401

UnauthorizedError: 인증 정보가 올바르지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 UnauthorizedError 입니다.

message?: string

(Optional)

403

ForbiddenError: 요청이 거절된 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 ForbiddenError 입니다.

message?: string

(Optional)

404

PaymentNotFoundError: 결제 건이 존재하지 않는 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotFoundError 입니다.

message?: string

(Optional)

409

PaymentNotPaidError: 결제가 완료되지 않은 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PaymentNotPaidError 입니다.

message?: string

(Optional)

502

PgProviderError: PG사에서 오류를 전달한 경우

type: string (Union Tag)

필드의 값이 일 때 타입은 PgProviderError 입니다.

message?: string

(Optional)

pgCode: string

pgMessage: string

try

Request

Request Sample

N/A

결제 예약 관련 API

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

빌링키 관련 API

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

현금 영수증 관련 API

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

프로모션 관련 API

프로모션과 관련된 API 기능을 제공합니다.

본인인증 관련 API

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

파트너 정산 관련 API

파트너 정산 서비스 API 기능을 제공합니다.

정책 관련 API

파트너 정산에 적용할 정책에 관한 API 입니다.

파트너 관련 API

파트너 정산에 적용할 파트너에 관한 API 입니다.

정산 상세내역 관련 API

파트너 정산 서비스의 정산 상세내역과 관련된 API 입니다.

계좌 관련 API

파트너 정산 서비스의 계좌와 관련된 API 입니다.

정산 내역 관련 API

파트너 정산 서비스의 정산 내역과 관련된 API 입니다.

지급 내역 관련 API

파트너 정산 서비스의 지급 내역과 관련된 API 입니다.

일괄 지급 내역 관련 API

파트너 정산 서비스의 일괄 지급 내역과 관련된 API 입니다.

이체 내역 관련 API

파트너 정산 서비스의 이체 내역과 관련된 API 입니다.

특정 PG사 관련 API

특정 PG사에 국한된 API 기능을 제공합니다.

대사 서비스 API

거래 대사 및 정산 대사 관련 API 기능을 제공합니다.

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다

PortOne REST API - V2

요청 및 응답 형식

인증 방식

GET 요청 시 Body 대신 Query 사용하기

하위호환성

인증 관련 API

목차

결제 관련 API

목차

결제 정보 사전 등록

Request

Path

Body

Response

200

400

401

403

409

결제 단건 조회

Request

Path

Query

Response

200

400

401

403

404

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

Request

Query

Response

200

400

401

403

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

Request

Query

Response

200

400

401

403

결제 취소

Request

Path

Body

Response

200

400

401

403

404

409

502

빌링키 결제

Request

Path

Body

Response

200

400

401

403

404

409

502

수기 결제

Request

Path

Body

Response

200

400

401

403

404

409