채널

프로퍼티 접기

channel_id

string

필수

결제 채널 ID

channel_name

string

필수

결제 채널 이름

pg_provider

enum

필수

PgProvider

V2 결제가 가능한 PG사

기본값:PG_PROVIDER_UNSPECIFIED

2개의 Enum 값 펼치기

channel_type

enum

필수

ChannelType

기본값:CHANNEL_TYPE_UNSPECIFIED

4개의 Enum 값 펼치기

pg_merchant_id

string

필수

PG 상점 ID

is_checkout

boolean

필수

결체창 방식(Checkout) 채널 여부

is_api

boolean

필수

API 결제용 채널 여부

is_identification_certification

boolean

필수

본인인증용 채널 여부

toss_payments_credential

object

TossPaymentsCredential

2개의 프로퍼티 펼치기

401 인증되지 않음

params

object

에러 상세 정보를 담은 파라미터 모음

프로퍼티 접기

message

string

code

enum

필수

`UnauthenticatedException`: 인증되지 않은 요청입니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

UnauthenticatedException

403 하위상점에 접근할 권한이 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

프로퍼티 접기

message

string

code

enum

필수

`PermissionDeniedException`: 해당 하위상점에 접근할 권한이 없습니다.

Enum 접기

PermissionDeniedException

404 채널을 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

프로퍼티 접기

message

string

code

enum

필수

`RecordNotFoundException`: 채널을 찾을 수 없습니다.

Enum 접기

RecordNotFoundException

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

프로퍼티 접기

message

string

code

enum

필수

에러 코드

Enum 접기

UnknownErrorDataRequestExceptionUnspecifiedDatabaseException

인증

API Key 방식으로 로그인

POST /signin/api-key

Body 파라미터

api_key

string

필수

사용자의 API Key

Response

200 로그인 성공

access_token

string

필수

인증 서버에서 인증된 사용자의 access token

refresh_token

string

필수

인증 서버에서 인증된 사용자의 access token

401 인증 실패

code

enum

필수

에러 이름

Enum 접기

UNAUTHORIZED

params

object

필수

에러 세부사항

프로퍼티 접기

message

string

에러 메시지

500 서버 에러

code

enum

필수

에러 이름

Enum 접기

INTERNAL

params

object

필수

에러 세부사항

프로퍼티 접기

message

string

에러 메시지

결제

결제내역 단건조회

GET /payments/{payment_id}

결제가 발생한 이후 즉시 조회가 가능한 API입니다.

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

payment

object

필수

결제내역

프로퍼티 접기

id

string

필수

가맹점에서 입력한 결제 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

transactions

array

필수

동일한 `payment_id`로 결제시도된 결제내역들

31개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

결제내역 다건조회

GET /payments

결제내역들을 조회할 수 있는 API입니다. 실제 결제 발생 이후 조회되기까지 지연이 있으니 검증을 위해서는 [결제내역 단건조회](#getPayment)를 이용해주세요.

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Query 파라미터

store_id

string

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

start

string

date-time (ISO 8601)

결제시작시각(`requested_at`) 범위의 시작 - 값을 넣지 않으면 `end`의 90일 전으로 설정됩니다.

end

string

date-time (ISO 8601)

결제시작시각(`requested_at`) 범위의 끝 - 값을 넣지 않으면 현재 시각으로 설정됩니다.

status

array

TransactionStatus

결제상태 리스트 - 값을 넣지 않으면 결제상태 필터링이 적용되지 않습니다.

6개의 Enum 값 펼치기

methods

array

Method

결제수단 리스트 - 값을 넣지 않으면 결제수단 필터링이 적용되지 않습니다.

6개의 Enum 값 펼치기

pg_providers

array

PgProvider

결제대행사 리스트 - 값을 넣지 않으면 결제대행사 필터링이 적용되지 않습니다.

37개의 Enum 값 펼치기

is_test_payment

boolean

테스트결제 필터링

is_scheduled_payment

boolean

정기결제 필터링

text_search_column

enum

TextSearchColumn

통합검색 항목

31개의 Enum 값 펼치기

text_search_value

string

통합검색 입력값

page

integer

페이지 - 0부터 시작합니다.

기본값:0

limit

integer

페이지 크기

기본값:10

sort_by

enum

필수

정렬 기준 `REQUESTED_AT`: 결제요청시각 `STATUS_UPDATED_AT`: 상태변경시각

기본값:REQUESTED_AT

2개의 Enum 값 펼치기

sort_order

enum

필수

정렬 방향 `DESCENDING`: 내림차순 `ASCENDING`: 오름차순

기본값:DESCENDING

2개의 Enum 값 펼치기

Response

200 200 응답

current_page

integer

필수

total_page

integer

필수

total_count

integer

필수

payments

array

필수

프로퍼티 접기

id

string

필수

가맹점에서 입력한 결제 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

transactions

array

필수

동일한 `payment_id`로 결제시도된 결제내역들

31개의 프로퍼티 펼치기

400 400 에러 응답

code

string

필수

에러 코드

params

object

에러 세부사항

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

결제 취소

POST /payments/{payment_id}/cancel

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Body 파라미터

reason

string

취소 사유

cancel_amount

integer

취소 금액 - 값을 넣지 않으면 전액 취소됩니다.

tax_free_amount

integer

취소 금액 중 면세 금액 - 값을 넣지 않으면 전액 과세됩니다.

vat_amount

integer

취소 금액 중 부가세 금액 (PG사 기본값: null). 결제 시 부가세를 지정했던 경우 필수 입력 바랍니다. 지원되는 PG사: 나이스페이먼츠(NICE), 이니시스(HTML5_INICIS)

check_refundable_amount

integer

결제 건의 취소 가능 잔액 - 값을 넣지 않으면 별도의 검증 처리를 수행하지 않습니다.

refund

object

환불 계좌 정보 - 가상계좌 결제인 경우에만 기입할 수 있습니다.

4개의 프로퍼티 펼치기

Response

200 200 응답

cancelled_tx_id

string

필수

취소 대상 거래 아이디

cancellation_id

string

필수

취소 아이디

payment

object

필수

결제내역

프로퍼티 접기

id

string

필수

가맹점에서 입력한 결제 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

transactions

array

필수

동일한 `payment_id`로 결제시도된 결제내역들

31개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

웹훅 재발송

POST /payments/{payment_id}/resend-webhook

`tx_id`와 `webhook_id` 모두 값을 넣지 않으면 대표 트랜잭션의 가장 최근 웹훅 발송 이력을 기준으로 재전송됩니다.

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Body 파라미터

tx_id

string

재발송 대상 트랜잭션 아이디 - 값을 넣지 않으면 기본값은 대표 트랜잭션 아이디로 설정됩니다.

webhook_id

string

재발송 대상 웹훅 아이디 - 값을 넣지 않으면 기본값은 가장 최근의 웹훅 아이디로 설정됩니다.

Response

200 200 응답

tx_id

string

필수

재발송 대상 트랜잭션 아이디

webhook_id

string

재발송 대상 웹훅 아이디 (값을 넣지 않으면 가장 최근의 웹훅 아이디 기준으로 재전송) 비동기 웹훅이거나 웹훅 처리에 너무 오랜 시간이 걸리는 경우 값이 비어있을 수 있습니다.

payment

object

필수

결제내역

프로퍼티 접기

id

string

필수

가맹점에서 입력한 결제 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

transactions

array

필수

동일한 `payment_id`로 결제시도된 결제내역들

31개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

가상계좌 테스트 웹훅 호출

POST /test-payments/{payment_id}/notice-virtual-account-deposit

가상계좌 테스트 결제 건에 대한 입금 통보 웹훅을 호출합니다.

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

tx_id

string

필수

웹훅 기준 트랜잭션 ID

webhook_id

string

payment

object

필수

결제내역

프로퍼티 접기

id

string

필수

가맹점에서 입력한 결제 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

transactions

array

필수

동일한 `payment_id`로 결제시도된 결제내역들

31개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

현금영수증 발급

POST /payments/{payment_id}/cash-receipt

결제 건에 대한 수동 현금영수증 발급

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

Body 파라미터

store_id

string

channel_name

string

필수

customer_identifier

string

필수

type

enum

필수

CashReceiptType

현금영수증 용도. personal = 소득공제용, corporate = 지출증빙용, anonymous = 국세청번호 자동발급 케이스

3개의 Enum 값 펼치기

order_name

string

필수

currency

enum

필수

화폐

181개의 Enum 값 펼치기

amount

number

필수

tax_free_amount

number

필수

면세 금액

기본값:0

product_type

enum

상품 유형

2개의 Enum 값 펼치기

customer_name

string

고객 성명

customer_email

string

고객 이메일

Response

200 현금영수증 발급 성공

receipt_id

string

필수

현금영수증 ID

pg_tx_id

string

필수

PG사 거래ID

issue_number

string

필수

receipt_url

string

필수

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`RequestParseFailed`: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요.

Enum 접기

RequestParseFailed

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

403 이미 발급된 현금영수증입니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`CashReceiptAlreadyIssued`: 이미 발급된 현금영수증입니다.

Enum 접기

CashReceiptAlreadyIssued

404 하위 상점이나 결제 채널을 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `ChannelNotFound`: 결제 채널을 찾을 수 없습니다.

Enum 접기

StoreNotFoundChannelNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownErrorPGProviderError

결제 예약

POST /schedules

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Body 파라미터

billing_key

string

필수

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

store_id

string

빌링키 결제를 진행하는 상점의 id

order_name

string

필수

주문명

is_cultural_expense

boolean

필수

문화비 지출 여부

기본값:false

is_escrow

boolean

필수

에스크로 여부

기본값:false

products

array

상품 정보 (에스크로 결제 상품 정보)

기본값:[]

6개의 프로퍼티 펼치기

customer

object

필수

고객 정보

8개의 프로퍼티 펼치기

custom_data

string

가맹점에서 추가로 저장할 데이터

total_amount

number

필수

결제 금액

tax_free_amount

number

필수

면세 금액

기본값:0

country

enum

Country

국가

249개의 Enum 값 펼치기

currency

enum

필수

화폐

181개의 Enum 값 펼치기

notice_urls

array

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.

기본값:[]

card_installment_plan

integer

할부 개월 수

product_type

enum

상품 유형

2개의 Enum 값 펼치기

payment_id

string

필수

scheduled_at

string

date-time (ISO 8601)

필수

Response

200 결제 예약 성공

id

string

필수

scheduled_at

string

date-time (ISO 8601)

필수

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`RequestParseFailed`: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요. `PastScheduled`: 현재 시각보다 이전의 시각으로 예약을 요청하였습니다.

Enum 접기

RequestParseFailedPastScheduled

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

403 이미 예약되었거나 삭제된 빌링키로 예약을 시도했습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`PaymentAlreadyExists`: 해당 payment는 이미 결제되었거나 가상계좌 입금 대기 상태입니다. `PaymentAlreadyScheduled`: 이미 존재하는 예약건입니다. `BillingKeyDeleted`: 삭제된 빌링키로 예약을 시도했습니다.

Enum 접기

PaymentAlreadyExistsPaymentAlreadyScheduledBillingKeyDeleted

404 하위 상점이나 빌링키를 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `BillingKeyNotFound`: 빌링키를 찾을 수 없습니다.

Enum 접기

StoreNotFoundBillingKeyNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownError

빌링키 결제

POST /payments/{payment_id}/billing-key/pay

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Body 파라미터

billing_key

string

필수

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

store_id

string

빌링키 결제를 진행하는 상점의 id

order_name

string

필수

주문명

is_cultural_expense

boolean

필수

문화비 지출 여부

기본값:false

is_escrow

boolean

필수

에스크로 여부

기본값:false

products

array

상품 정보 (에스크로 결제 상품 정보)

기본값:[]

6개의 프로퍼티 펼치기

customer

object

필수

고객 정보

8개의 프로퍼티 펼치기

custom_data

string

가맹점에서 추가로 저장할 데이터

total_amount

number

필수

결제 금액

tax_free_amount

number

필수

면세 금액

기본값:0

country

enum

Country

국가

249개의 Enum 값 펼치기

currency

enum

필수

화폐

181개의 Enum 값 펼치기

notice_urls

array

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.

기본값:[]

card_installment_plan

integer

할부 개월 수

product_type

enum

상품 유형

2개의 Enum 값 펼치기

Response

200 빌링키 결제 성공

tx_id

string

필수

customer_id

string

필수

requested_at

string

date-time (ISO 8601)

필수

paid_at

string

date-time (ISO 8601)

필수

pg_tx_id

string

필수

PG사 거래ID

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`RequestParseFailed`: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요. `TaxFreeAmountMustBeLessThanOrEqualToTotalAmount`: 면세금액은 결제금액보다 작거나 같아야 합니다.

Enum 접기

RequestParseFailedTaxFreeAmountMustBeLessThanOrEqualToTotalAmount

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

403 이미 결제되었거나 삭제된 빌링키입니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`BillingKeyAlreadyDeleted`: 삭제된 빌링키로 결제를 시도하셨습니다. `PaymentAlreadyPaid`: 이미 결제되었습니다.

Enum 접기

BillingKeyAlreadyDeletedPaymentAlreadyPaid

404 하위 상점이나 빌링키를 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `BillingKeyNotFound`: 빌링키를 찾을 수 없습니다.

Enum 접기

StoreNotFoundBillingKeyNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownErrorPGProviderError

키인(수기) 결제

POST /payments/{payment_id}/instant/pay

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

Body 파라미터

store_id

string

하위 상점 ID

order_name

string

필수

is_cultural_expense

boolean

필수

문화비 지출 여부

기본값:false

is_escrow

boolean

필수

에스크로 여부

기본값:false

products

array

기본값:[]

6개의 프로퍼티 펼치기

customer

object

필수

고객 정보

8개의 프로퍼티 펼치기

custom_data

string

total_amount

number

필수

결제 금액

tax_free_amount

number

필수

면세 금액

기본값:0

country

enum

Country

국가

249개의 Enum 값 펼치기

currency

enum

필수

화폐

181개의 Enum 값 펼치기

notice_urls

array

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.

기본값:[]

channel_name

string

필수

결제 채널 이름

product_type

enum

상품 유형

2개의 Enum 값 펼치기

payment_method_option

object

필수

InstantPaymentMethodForm

가능한 결제 수단: 카드, 가상계좌 선택한 결제 수단에 따라 `card`와 `virtual_account` 중 하나에만 값이 들어있어야 합니다.

2개의 프로퍼티 펼치기

Response

200 키인(수기) 결제 성공

tx_id

string

필수

customer_id

string

필수

requested_at

string

date-time (ISO 8601)

필수

paid_at

string

date-time (ISO 8601)

필수

pg_tx_id

string

필수

PG사 거래ID

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

Enum 접기

RequestParseFailedTaxFreeAmountMustBeLessThanOrEqualToTotalAmount

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

403 이미 결제되었습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`PaymentAlreadyPaid`: 이미 결제되었습니다.

Enum 접기

PaymentAlreadyPaid

404 하위 상점이나 결제 채널을 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `ChannelNotFound`: 결제 채널을 찾을 수 없습니다.

Enum 접기

StoreNotFoundChannelNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownErrorPGProviderError

에스크로 배송정보 등록/변경

POST /payments/{payment_id}/escrow/logis

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Body 파라미터

store_id

string

sender

object

필수

5개의 프로퍼티 펼치기

receiver

object

필수

4개의 프로퍼티 펼치기

logistics_form

object

필수

5개의 프로퍼티 펼치기

Response

200 에스크로 배송정보 등록/변경 성공

company

string

필수

invoice_number

string

필수

sent_at

string

date-time (ISO 8601)

필수

applied_at

string

date-time (ISO 8601)

필수

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`RequestParseFailed`: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요.

Enum 접기

RequestParseFailed

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

403 지불되지 않은 결제 건입니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`NotPaid`: 지불되지 않은 결제 건입니다.

Enum 접기

NotPaid

404 하위 상점을 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `PaymentNotFound`: 해당하는 결제를 찾을 수 없습니다.

Enum 접기

StoreNotFoundPaymentNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownErrorPGProviderError

현금영수증

현금영수증 조회

GET /payments/{payment_id}/cash-receipt

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

receipt

object

필수

CashReceipt

현금영수증 정보

프로퍼티 접기

pg_receipt_id

string

PG사 현금영수증 발급 ID

issue_number

string

필수

현금영수증 승인번호

type

enum

CashReceiptType

3개의 Enum 값 펼치기

amount

integer

필수

금액

tax_free_amount

integer

면세금액

status

enum

CashReceiptStatus

2개의 Enum 값 펼치기

issued_at

string

date-time (ISO 8601)

필수

발급일시

cancelled_at

string

date-time (ISO 8601)

취소일시 (`status`가 `CANCELLED`인 경우 제공)

receipt_url

string

영수증 url

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

payment_id

string

필수

결제 ID

order_name

string

필수

주문명

is_manual

boolean

필수

수동발급 여부

currency

enum

통화

181개의 Enum 값 펼치기

channel

object

결제 채널 정보

5개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

현금영수증 발급 취소

DELETE /payments/{payment_id}/cash-receipt

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

payment_id

string

필수

결제 ID

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

cancelled_amount

integer

필수

현금영수증 취소 금액

cancelled_at

string

date-time (ISO 8601)

필수

현금영수증 취소 시각

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

정기결제

정기결제예약 다건 조회

GET /schedules

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

start

string

date-time (ISO 8601)

필수

결제예약시각(`scheduled_at`) 범위의 시작 - 값을 넣지 않으면 파라미터 end의 90일 전으로 설정됩니다.

end

string

date-time (ISO 8601)

필수

결제예약시각(`scheduled_at`) 범위의 끝 - 값을 넣지 않으면 현재 시각으로 설정됩니다.

status

array

ScheduleStatus

결제예약 상태 리스트

기본값:[]

4개의 Enum 값 펼치기

page

integer

페이지 - 0부터 시작합니다.

기본값:0

limit

integer

페이지 크기

기본값:10

Response

200 200 응답

current_page

integer

필수

total_page

integer

필수

total_count

integer

필수

schedules

array

필수

Schedule

프로퍼티 접기

id

string

필수

결제예약 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

billing_key

string

필수

빌링키

payment_id

string

필수

결제 ID

status

enum

필수

ScheduleStatus

예약결제 상태 `SCHEDULED`: 결제 예약 `STARTED`: 결제 실행 `COMPLETED`: 실행 완료 `CANCELLED`: 예약 취소

4개의 Enum 값 펼치기

scheduled_at

string

date-time (ISO 8601)

필수

결제 예약 시각

started_at

string

date-time (ISO 8601)

결제 실행 시각 (`status`가 `STARTED`로 되었을 경우 제공)

completed_at

string

date-time (ISO 8601)

결제 완료 시각 (`status`가 `COMPLETED`인 경우 제공)

cancelled_at

string

date-time (ISO 8601)

결제 취소 시각 (`status`가 `CANCELLED`인 경우 제공)

order_name

string

필수

주문명

is_cultural_expense

boolean

필수

문화비 지출 여부

is_escrow

boolean

필수

에스크로 결제 여부

products

array

상품 정보 (에스크로 결제 시 에스크로 상품 정보로 활용됨)

6개의 프로퍼티 펼치기

customer

object

필수

구매자 정보

8개의 프로퍼티 펼치기

custom_data

string

커스텀 데이터

total_amount

integer

필수

결제 금액

tax_free_amount

integer

면세 금액

currency

enum

필수

통화

181개의 Enum 값 펼치기

origin

object

결제를 요청한 근원에 대한 정보

4개의 프로퍼티 펼치기

notice_urls

array

필수

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.

installment_month

integer

할부개월

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

빌링키 정기결제예약 취소

DELETE /schedules

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

billing_key

string

필수

정기결제예약 빌링키

schedule_id

array

삭제할 정기결제예약 아이디 목록, 비어있을 경우 빌링키로 예약한 모든 예약을 취소함

Response

200 200 응답

deleted_schedule_ids

array

필수

삭제된 정기결제예약 아이디 목록

기본값:[]

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

정기결제예약 단건 조회

GET /schedules/{schedule_id}

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

schedule_id

string

필수

정기결제예약 ID

Response

200 200 응답

schedule

object

필수

Schedule

결제예약정보

프로퍼티 접기

id

string

필수

결제예약 ID

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

billing_key

string

필수

빌링키

payment_id

string

필수

결제 ID

status

enum

필수

ScheduleStatus

예약결제 상태 `SCHEDULED`: 결제 예약 `STARTED`: 결제 실행 `COMPLETED`: 실행 완료 `CANCELLED`: 예약 취소

4개의 Enum 값 펼치기

scheduled_at

string

date-time (ISO 8601)

필수

결제 예약 시각

started_at

string

date-time (ISO 8601)

결제 실행 시각 (`status`가 `STARTED`로 되었을 경우 제공)

completed_at

string

date-time (ISO 8601)

결제 완료 시각 (`status`가 `COMPLETED`인 경우 제공)

cancelled_at

string

date-time (ISO 8601)

결제 취소 시각 (`status`가 `CANCELLED`인 경우 제공)

order_name

string

필수

주문명

is_cultural_expense

boolean

필수

문화비 지출 여부

is_escrow

boolean

필수

에스크로 결제 여부

products

array

상품 정보 (에스크로 결제 시 에스크로 상품 정보로 활용됨)

6개의 프로퍼티 펼치기

customer

object

필수

구매자 정보

8개의 프로퍼티 펼치기

custom_data

string

커스텀 데이터

total_amount

integer

필수

결제 금액

tax_free_amount

integer

면세 금액

currency

enum

필수

통화

181개의 Enum 값 펼치기

origin

object

결제를 요청한 근원에 대한 정보

4개의 프로퍼티 펼치기

notice_urls

array

필수

결제 승인/실패 시 요청을 받을 웹훅 주소입니다. 상점에 설정되어 있는 값보다 우선적으로 적용됩니다.

installment_month

integer

할부개월

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

빌링키

빌링키 다건 조회

GET /billing-keys

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Query 파라미터

billing_key

array

필수

빌링키

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

billing_keys

array

필수

BillingKey

프로퍼티 접기

billing_key

string

필수

빌링키

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

channel

object

필수

결제 채널 정보

5개의 프로퍼티 펼치기

origin

object

결제를 요청한 근원에 대한 정보

4개의 프로퍼티 펼치기

customer

object

필수

구매자 정보

8개의 프로퍼티 펼치기

issued_at

string

date-time (ISO 8601)

발급 일시 (`status`가 `ISSUED`인 경우 제공)

custom_data

string

커스텀 데이터

payment_method_detail

object

필수

BillingKeyPaymentMethod

빌링키 결제수단 상세정보

3개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

빌링키 발급

POST /billing-keys

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Body 파라미터

store_id

string

하위 상점 ID

customer

object

필수

InstantBillingKeyPaymentMethodForm

고객 정보

8개의 프로퍼티 펼치기

custom_data

string

channel_name

string

필수

결제 채널 이름

payment_method_option

object

필수

가능한 결제 수단: 카드, 휴대폰 소액 결제 선택한 결제 수단에 따라 `card`와 `mobile_phone` 중 하나에만 값이 들어있어야 합니다.

2개의 프로퍼티 펼치기

Response

200 빌링키 발급 성공

billing_key

string

필수

customer_id

string

필수

requested_at

string

date-time (ISO 8601)

필수

issued_at

string

date-time (ISO 8601)

필수

400 잘못된 요청

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`RequestParseFailed`: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요.

Enum 접기

RequestParseFailed

401 권한 없음

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`Unauthorized`: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.

Enum 접기

Unauthorized

404 하위 상점이나 결제 채널을 찾을 수 없습니다.

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

`StoreNotFound`: 하위 상점을 찾을 수 없습니다. `ChannelNotFound`: 결제 채널을 찾을 수 없습니다.

Enum 접기

StoreNotFoundChannelNotFound

500 내부 서버 에러

params

object

에러 상세 정보를 담은 파라미터 모음

code

enum

필수

에러 코드

Enum 접기

InvalidEntityStateUnknownErrorPGProviderError

빌링키 단건 조회

GET /billing-keys/{billing_key}

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

billing_key

string

필수

빌링키

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

billing_key

object

필수

BillingKey

빌링키 정보

프로퍼티 접기

billing_key

string

필수

빌링키

merchant_id

string

필수

가맹점 ID

store_id

string

필수

하위 상점 ID

channel

object

필수

결제 채널 정보

5개의 프로퍼티 펼치기

origin

object

결제를 요청한 근원에 대한 정보

4개의 프로퍼티 펼치기

customer

object

필수

구매자 정보

8개의 프로퍼티 펼치기

issued_at

string

date-time (ISO 8601)

발급 일시 (`status`가 `ISSUED`인 경우 제공)

custom_data

string

커스텀 데이터

payment_method_detail

object

필수

BillingKeyPaymentMethod

빌링키 결제수단 상세정보

3개의 프로퍼티 펼치기

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array

누락된 권한 리스트

21개의 Enum 값 펼치기

404 찾을 수 없음

code

string

필수

에러 코드

params

object

에러 세부사항

500 내부 서버 에러

code

string

필수

에러 코드

params

object

에러 세부사항

빌링키 삭제

DELETE /billing-keys/{billing_key}

인증이 필요한 API

Authorization 헤더에 API Key 방식으로 로그인한 뒤 반환된 access-token을 넣어주세요.

예시: Authorization: Bearer <JWT>

Path 파라미터

billing_key

string

필수

빌링키

Query 파라미터

store_id

string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Response

200 200 응답

deleted_at

string

date-time (ISO 8601)

필수

빌링키 삭제 시각

401 인증 실패

code

string

필수

에러 코드

params

object

에러 세부사항

403 권한 없음

code

string

필수

에러 코드

params

object

필수

에러 세부사항

프로퍼티 접기

missing_authorities

array