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`		정산 관련 정보
`bundle`	`PaymentBundle`		`ALPHA` 결제 번들 정보
`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"`

`ALPHA` 결제 번들 (PaymentBundle)

번들은 논리적으로 같은 결제 행위에 묶이는 결제 이력이에요. 같은 key를 가진 결제들이 하나의 번들로 묶여요.

Name	Type	Required	Description	Example
`key`	`String`	✅	번들 식별자	`"BDL-001"`

예를 들어 신용카드 결제에 포인트 사용이 함께 묶이는 경우에요. 이 경우 결제 취소 시 포인트 사용도 함께 취소되어야 하는데, 번들은 이런 규칙을 표현합니다.

json

{
  "payments": [
    /* 번들에 포함되어 있어요. */
    {
      "amount": 1000,
      "cardDetails": { "cardBrand": "토스", "amount": 1000 },
      "bundle": { "key": "BDL-001" }
    },
    /* 번들 식별자가 같으니 위 결제와 함께 하나의 번들로 묶여요. */
    {
      "amount": 500,
      "prepaidValueDetails": { "provider": "토스포인트", "amount": 500 },
      "bundle": { "key": "BDL-001" }
    },
    /* 번들에 포함되지 않아요. */
    {
      "amount": 1000,
      "cashDetails": { "buyerSuppliedAmount": 1000, "changeBackAmount": 0 },
      "bundle": null
    }
  ]
}

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는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요.

개발·연동 중 궁금한 점은 개발자 포럼에 남겨주세요. 다른 개발자의 질문과 답변도 확인할 수 있어요.

개발자 포럼: https://forum.tossplace.com

앱별 사용 권한·승인 여부 확인은 개발자센터 메일로 문의해 주세요. 계정·매장 정보는 포럼에 공개하지 마세요.

Property	Value
Method	POST
Path	`/api-public/openapi/v1/merchants/{merchantId}/payment/payments`
Response Type	`Payment`
Description	주문에 승인된 결제 기록을 추가해요. 이 API의 호출을 통해 실제로 결제가 승인 처리되는 것이 아니라는 점에 유의해야 해요. 주문 생성 API를 통해 생성한 주문에 대해서만 결제를 기록할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`orderId`	Body	`String`	✅	-	주문 ID
`payment`	Body	`Payment.Create`	✅	-	승인된 결제 내역 (주문 생성 - 결제 내역 생성 참고)

취소된 결제 기록

WARNING

취소된 결제 기록 API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요.

개발·연동 중 궁금한 점은 개발자 포럼에 남겨주세요. 다른 개발자의 질문과 답변도 확인할 수 있어요.

개발자 포럼: https://forum.tossplace.com

앱별 사용 권한·승인 여부 확인은 개발자센터 메일로 문의해 주세요. 계정·매장 정보는 포럼에 공개하지 마세요.

Property	Value
Method	POST
Path	`/api-public/openapi/v1/merchants/{merchantId}/payment/payments/{paymentId}/cancel`
Response Type	`Payment`
Description	취소된 결제를 기록해요. 주문에 등록한 결제 내역을 취소 상태로 기록해요. 이 API의 호출을 통해 실제로 결제가 환불 처리되는 것이 아니라는 점에 유의해야 해요. 주문 생성 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)

`ALPHA` 결제 번들 (PaymentBundle)

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) ​

ALPHA 결제 번들 (PaymentBundle) ​

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)

`ALPHA` 결제 번들 (PaymentBundle)

Methods

결제 단건 조회

주문의 결제건 모두 조회

승인된 결제 기록

취소된 결제 기록

Events

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

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