Payment API

매장의 결제 정보를 관리하는 API예요. 결제 내역과 결제 수단별 세부 정보를 확인할 수 있어요. 새로운 결제 내역이 승인되거나 취소된 경우 웹훅을 통해 이벤트를 수신할 수 있어요.

Types

결제 (Payment)

결제 금액과 내역, 결제 수단별 세부 데이터를 포함하는 개념이에요.

Name	Type	Required	Description	Example
`id`	`String`	✅	결제 ID	`"640000000000000000"`
`merchantId`	`Long`	✅	매장 ID	`42`
`orderId`	`String`	✅	주문 ID	`"620000000000000000"`
`state`	`PaymentState`	✅	결제 상태	`"APPROVED"`
`sourceType`	`PaymentSourceType`	✅	결제수단 대분류	`"CARD"`
`paymentMethod`	`String`	✅	결제수단 세부 분류	`"CARD_NFC"`
`van`	`String`		VAN	`"NICE"`
`amount`	`Long`	✅	결제금액	`3200`
`taxAmount`	`Long`	✅	세액	`291`
`supplyAmount`	`Long`	✅	공급가액	`2909`
`taxExemptAmount`	`Long`	✅	면세금액	`0`
`tipAmount`	`Long`	✅	봉사료	`0`
`approvedNo`	`String`	✅	승인번호	`"00000000"`
`approvedAt`	`timestamp`		승인 시각	`"2025-09-01T00:00:00"`
`cancelledAt`	`timestamp`		취소 시각	`"2025-09-01T00:00:00"`
`cashDetails`	`PaymentCashDetails`		현금결제 세부 내역
`cardDetails`	`PaymentCardDetails`		카드결제 세부 내역
`prepaidValueDetails`	`PaymentPrepaidValueDetails`		선불지급수단 결제 세부 내역
`accountTransferDetails`	`PaymentAccountTransferDetails`		계좌이체 세부 내역
`easyPayDetails`	`PaymentEasyPayDetails`		간편결제 세부 내역
`externalDetails`	`PaymentExternalDetails`		외부 결제수단 세부 내역
`pgDetails`	`PaymentPgDetails`		PG사 결제 세부 내역
`cashReceipt`	`PaymentCashReceipt`		현금영수증 세부 내역
`settlement`	`PaymentSettlement`		정산 관련 정보
`createdAt`	`timestamp`	✅	생성 시각	`"2025-09-01T00:00:00"`
`updatedAt`	`timestamp`	✅	변경 시각	`"2025-09-01T00:00:00"`

결제 상태 (PaymentState)

Value	Description
`"APPROVED"`	승인됨
`"CANCELLED"`	취소됨
`"UNDEFINED"`

결제 수단 분류 (PaymentSourceType)

Value	Description
`"CASH"`	현금
`"CARD"`	카드
`"PREPAID_VALUE"`	선불지급수단
`"ACCOUNT_TRANSFER"`	계좌이체
`"BARCODE"`	간편결제
`"EXTERNAL"`	외부 결제수단
`"UNDEFINED"`

현금결제 상세 (PaymentCashDetails)

Name	Type	Required	Description	Example
`buyerSuppliedAmount`	`Long`		고객이 지불한 금액	`5000`
`changeBackAmount`	`Long`		거스름돈	`1000`

카드결제 상세 (PaymentCardDetails)

Name	Type	Description	Example
`cardType`	`CardType`	카드 종류	`"CREDIT"`
`cardBrand`	`String`	발급사명
`cardNo`	`String`	카드번호 (마스킹 적용)	`"00000000********"`
`cardBrandId`	`String`	발급사 코드
`acquirer`	`String`	매입사명
`acquirerId`	`String`	매입사 코드
`balance`	`Long`	잔액
`van`	`String`	VAN	`"NICE"`
`approvalNo`	`String`	승인번호	`"12345678"`
`amount`	`Long`	결제 금액	`3200`
`installmentMonth`	`String`	할부개월 수	`"00"`

카드 종류 (CardType)

Value	Description
`"CREDIT"`	신용카드
`"DEBIT"`	직불카드
`"PREPAID"`	선불카드
`"FOREIGN"`	해외 카드 사용
`"UNDEFINED"`

선불지급수단 결제 상세 (PaymentPrepaidValueDetails)

Name	Type	Description	Example
`provider`	`String`	선불지급수단 제공사
`code`	`String`	선불지급수단 코드 (상품권번호 등)
`amount`	`Long`	사용 금액	`3200`

계좌이제 상세 (PaymentAccountTransferDetails)

Name	Type	Required	Description	Example
`bankCode`	`Int`		은행 코드	`20`
`accountNumber`	`String`		계좌번호 (마스킹 적용)	`"110-*-****"`

간편결제 상세 (PaymentEasyPayDetails)

Name	Type	Description	Example
`provider`	`String`	간편결제 제공사	`"토스페이"`
`acquirer`	`String`	매입사	`"토스머니"`
`acquirerId`	`String`	매입사 코드	`"TS"`
`payType`	`PaymentEasyPayType`	간편결제에 연결된 결제 수단 종류	`"ACCOUNT"`
`amount`	`Long`	결제 금액	`3200`

간편결제 결제수단 종류 (PaymentEasyPayType)

Value	Description
`"ACCOUNT"`	계좌
`"CARD"`	카드
`"UNDEFINED"`

외부 결제수단 상세 (PaymentExternalDetails)

Name	Type	Required	Description	Example
`source`	`String`		결제수단명	`"모바일 상품권"`

PG사 결제 상세 (PaymentPgDetails)

Name	Type	Required	Description	Example
`provider`	`String`		PG 벤더명	`"토스페이먼츠"`
`transactionId`	`String`		PG 거래 ID	`"12345"`

현금영수증 상세 (PaymentCashReceipt)

Name	Type	Required	Description	Example
`issuerType`	`PaymentCashReceiptIssuerType`	✅	발급 종류	`"CONSUMER"`
`issuanceType`	`PaymentCashReceiptIssuanceType`	✅	발급 방법	`"PHONE"`
`identityNumber`	`String`	✅	발급 방법에 해당하는 식별번호 (휴대전화 번호 / 사업자번호 / 카드 번호)	`"**********"`
`selfIssuance`	`Boolean`	✅	자진 발급 여부	`true`
`issueNumber`	`String`	✅	발급 번호	`"0000000000"`
`issuedAt`	`timestamp`		발급 시각	`"2025-09-01T00:00:00"`
`amount`	`Long`		발급 금액	`3200`

현금영수증 발급 종류 (PaymentCashReceiptIssuerType)

Value	Description
`"CONSUMER"`	개인 소득공제용
`"BUSINESSES"`	사업자 지출증빙용
`"UNDEFINED"`

현금영수증 발급 방법 (PaymentCashReceiptIssuanceType)

Value	Description
`"PHONE"`	핸드폰 번호
`"BUSINESS_NUMBER"`	사업자 번호
`"CARD"`	현금영수증 카드
`"UNDEFINED"`

결제 정산 정보 (PaymentSettlement)

Name	Type	Required	Description	Example
`settlementType`	`PaymentSettlementType`	✅	정산 주체 종류	`"ACQUIRER"`
`settlementSubject`	`String`	✅	정산 주체

정산 주체 종류 (PaymentSettlementType)

Value	Description
`"ACQUIRER"`	매입사
`"PG"`	PG사
`"UNDEFINED"`

Methods

결제 단건 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/payment/payments/{paymentId}`
Response Type	`Payment`
Description	매장의 결제 하나를 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`paymentId`	Path	`String`	✅	-	결제 ID

주문의 결제건 모두 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/payment/payments/by-order-id`
Response Type	`Payment[]`
Description	주문 하나의 결제 건을 모두 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`orderId`	Query	`String`	✅	-	주문 ID

취소된 결제 기록

WARNING

취소된 결제 기록 API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요. 문의사항이 있으신 경우 개발자 센터 지원 이메일로 문의해주세요.

Property	Value
Method	POST
Path	`/api-public/openapi/v1/merchants/{merchantId}/payment/payments/{paymentId}/cancel`
Response Type	`Payment`
Description	취소된 결제를 기록해요. 주문에 등록한 결제 내역을 취소 상태로 기록해요. 실제로 결제가 환불 처리되는 것이 아니라는 점에 유의해야 해요. 주문 생성 API를 통해 생성한 주문의 결제 내역에 대해서만 취소 처리할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`paymentId`	Path	`String`	✅	-	결제 ID

요청 Body

Name	Type	Required	Description	Example
`cancelledAt`	`timestamp`	✅	취소 시각	`"2025-09-01T00:00:00"`

Events

결제 승인됨 (`payment.payment.approved.v1`)

Property	Value
Event Type	`payment.payment.approved.v1`
Description	결제가 승인되었어요.

이벤트 Payload

Name	Type	Required	Description	Example
`payment`	`Payment`	✅	승인된 결제 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "payment.payment.approved.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "payment": {
            "id": "640000000000000000",
            "merchantId": 42,
            "orderId": "620000000000000000",
            "state": "APPROVED",
            "sourceType": "CASH",
            "paymentMethod": "CASH",
            "amount": 3200,
            "taxAmount": 291,
            "supplyAmount": 2909,
            "taxExemptAmount": 0,
            "tipAmount": 0,
            "approvedNo": "00000000",
            "approvedAt": "2025-09-01T00:00:00",
            "cashDetails": {
                "buyerSuppliedAmount": 3200,
                "changeBackAmount": 0
            },
            "createdAt": "2025-09-01T00:00:00",
            "updatedAt": "2025-09-01T00:00:00"
        }
    }
}

결제 취소됨 (`payment.payment.cancelled.v1`)

Property	Value
Event Type	`payment.payment.cancelled.v1`
Description	결제가 취소되었어요.

이벤트 Payload

Name	Type	Required	Description	Example
`payment`	`Payment`	✅	취소된 결제 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "payment.payment.cancelled.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "payment": {
            "id": "640000000000000000",
            "merchantId": 42,
            "orderId": "620000000000000000",
            "state": "CANCELLED",
            "sourceType": "CASH",
            "paymentMethod": "CASH",
            "amount": 3200,
            "taxAmount": 291,
            "supplyAmount": 2909,
            "taxExemptAmount": 0,
            "tipAmount": 0,
            "approvedNo": "00000000",
            "approvedAt": "2025-09-01T00:00:00",
            "cancelledAt": "2025-09-01T00:00:00",
            "cashDetails": {
                "buyerSuppliedAmount": 3200,
                "changeBackAmount": 0
            },
            "createdAt": "2025-09-01T00:00:00",
            "updatedAt": "2025-09-01T00:00:00"
        }
    }
}

Payment API ​

Types ​

결제 (Payment) ​

결제 상태 (PaymentState) ​

결제 수단 분류 (PaymentSourceType) ​

현금결제 상세 (PaymentCashDetails) ​

카드결제 상세 (PaymentCardDetails) ​

카드 종류 (CardType) ​

선불지급수단 결제 상세 (PaymentPrepaidValueDetails) ​

계좌이제 상세 (PaymentAccountTransferDetails) ​

간편결제 상세 (PaymentEasyPayDetails) ​

간편결제 결제수단 종류 (PaymentEasyPayType) ​

외부 결제수단 상세 (PaymentExternalDetails) ​

PG사 결제 상세 (PaymentPgDetails) ​

현금영수증 상세 (PaymentCashReceipt) ​

현금영수증 발급 종류 (PaymentCashReceiptIssuerType) ​

현금영수증 발급 방법 (PaymentCashReceiptIssuanceType) ​

결제 정산 정보 (PaymentSettlement) ​

정산 주체 종류 (PaymentSettlementType) ​

Methods ​

결제 단건 조회 ​

주문의 결제건 모두 조회 ​

취소된 결제 기록 ​

Events ​

결제 승인됨 (payment.payment.approved.v1) ​

결제 취소됨 (payment.payment.cancelled.v1) ​

Payment API

Types

결제 (Payment)

결제 상태 (PaymentState)

결제 수단 분류 (PaymentSourceType)

현금결제 상세 (PaymentCashDetails)

카드결제 상세 (PaymentCardDetails)

카드 종류 (CardType)

선불지급수단 결제 상세 (PaymentPrepaidValueDetails)

계좌이제 상세 (PaymentAccountTransferDetails)

간편결제 상세 (PaymentEasyPayDetails)

간편결제 결제수단 종류 (PaymentEasyPayType)

외부 결제수단 상세 (PaymentExternalDetails)

PG사 결제 상세 (PaymentPgDetails)

현금영수증 상세 (PaymentCashReceipt)

현금영수증 발급 종류 (PaymentCashReceiptIssuerType)

현금영수증 발급 방법 (PaymentCashReceiptIssuanceType)

결제 정산 정보 (PaymentSettlement)

정산 주체 종류 (PaymentSettlementType)

Methods

결제 단건 조회

주문의 결제건 모두 조회

취소된 결제 기록

Events

결제 승인됨 (`payment.payment.approved.v1`)

결제 취소됨 (`payment.payment.cancelled.v1`)