PortOne Payment Gateways API

openapi: 3.0.3
info:
  title: PortOne B2b Payment Gateways API
  version: 1.16.0
servers:
- url: https://api.portone.io
  description: 운영환경 서버
tags:
- name: Payment Gateways
paths:
  /payment-gateways/card-promotion:
    get:
      summary: PG사 카드 프로모션 조회 API
      description: 'PG사 카드 프로모션 조회 API


        주어진 채널에 대해 PG사에서 제공하는 카드 프로모션 목록을 조회합니다.

        해당 API는 현재 특정 PG사(KCP_V2)에 대해서만 지원되며, 지원 여부는 포트원 기술지원팀에 문의 부탁드립니다.'
      operationId: getPgCardPromotions
      parameters:
      - name: channelKey
        in: query
        description: '채널 키


          조회하고자 하는 채널의 키'
        required: true
        schema:
          type: string
        x-portone-title: 채널 키
        x-portone-description: 조회하고자 하는 채널의 키
      - name: amount
        in: query
        description: '결제 금액


          결제 금액입니다. 해당 결제 금액 기준 이용 가능한 프로모션 목록이 조회됩니다.'
        required: true
        schema:
          type: integer
          format: int64
        x-portone-title: 결제 금액
        x-portone-description: 결제 금액입니다. 해당 결제 금액 기준 이용 가능한 프로모션 목록이 조회됩니다.
      - name: cardCompany
        in: query
        description: '카드사 필터


          조회할 카드사입니다. 값을 입력하지 않으면 카드사 필터링이 적용되지 않습니다.'
        required: false
        schema:
          $ref: '#/components/schemas/PgPromotionCardCompany'
        x-portone-title: 카드사 필터
        x-portone-description: 조회할 카드사입니다. 값을 입력하지 않으면 카드사 필터링이 적용되지 않습니다.
      responses:
        '200':
          description: 성공 응답으로 카드 프로모션 목록을 반환합니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPgCardPromotionsResponse'
          x-portone-title: 성공 응답으로 카드 프로모션 목록을 반환합니다.
        '400':
          description: '* `InvalidRequestError`: 요청된 입력 정보가 유효하지 않은 경우'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPgCardPromotionsError'
        '401':
          description: '* `UnauthorizedError`: 인증 정보가 올바르지 않은 경우'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPgCardPromotionsError'
        '404':
          description: '* `ChannelNotFoundError`: 요청된 채널이 존재하지 않는 경우'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPgCardPromotionsError'
        '502':
          description: '* `PgProviderError`: PG사에서 오류를 전달한 경우'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPgCardPromotionsError'
      security:
      - bearerJwt: []
      - portOne: []
      x-portone-category: payment.additionalFeature
      x-portone-title: PG사 카드 프로모션 조회 API
      x-portone-description: '주어진 채널에 대해 PG사에서 제공하는 카드 프로모션 목록을 조회합니다.

        해당 API는 현재 특정 PG사(KCP_V2)에 대해서만 지원되며, 지원 여부는 포트원 기술지원팀에 문의 부탁드립니다.'
      x-portone-error:
        $ref: '#/components/schemas/GetPgCardPromotionsError'
      tags:
      - Payment Gateways
components:
  schemas:
    InvalidRequestError:
      title: 요청된 입력 정보가 유효하지 않은 경우
      description: '요청된 입력 정보가 유효하지 않은 경우


        허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.'
      type: object
      required:
      - type
      properties:
        type:
          type: string
        message:
          type: string
      x-portone-title: 요청된 입력 정보가 유효하지 않은 경우
      x-portone-description: 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
      x-portone-status-code: 400
    GetPgCardPromotionsError:
      title: GetPgCardPromotionsError
      oneOf:
      - $ref: '#/components/schemas/ChannelNotFoundError'
      - $ref: '#/components/schemas/InvalidRequestError'
      - $ref: '#/components/schemas/PgProviderError'
      - $ref: '#/components/schemas/UnauthorizedError'
      discriminator:
        propertyName: type
        mapping:
          CHANNEL_NOT_FOUND: '#/components/schemas/ChannelNotFoundError'
          INVALID_REQUEST: '#/components/schemas/InvalidRequestError'
          PG_PROVIDER: '#/components/schemas/PgProviderError'
          UNAUTHORIZED: '#/components/schemas/UnauthorizedError'
    PgPromotionCardCompany:
      title: PG 프로모션 카드사
      description: 'PG 프로모션 카드사


        PG사 프로모션 조회 시 필터링할 수 있는 카드사 목록입니다.'
      type: string
      enum:
      - KOREA_DEVELOPMENT_BANK
      - KFCC
      - SHINHYUP
      - EPOST
      - SAVINGS_BANK_KOREA
      - KAKAO_BANK
      - WOORI_CARD
      - BC_CARD
      - GWANGJU_CARD
      - SAMSUNG_CARD
      - SHINHAN_CARD
      - HYUNDAI_CARD
      - LOTTE_CARD
      - SUHYUP_CARD
      - CITI_CARD
      - NH_CARD
      - JEONBUK_CARD
      - JEJU_CARD
      - HANA_CARD
      - KOOKMIN_CARD
      - K_BANK
      - TOSS_BANK
      - MIRAE_ASSET_SECURITIES
      x-portone-title: PG 프로모션 카드사
      x-portone-description: PG사 프로모션 조회 시 필터링할 수 있는 카드사 목록입니다.
      x-portone-enum:
        HANA_CARD:
          title: 하나카드
        JEONBUK_CARD:
          title: 전북카드
        SHINHYUP:
          title: 신협
        WOORI_CARD:
          title: 우리카드
        LOTTE_CARD:
          title: 롯데카드
        SAMSUNG_CARD:
          title: 삼성카드
        KOREA_DEVELOPMENT_BANK:
          title: KDB산업은행
        SUHYUP_CARD:
          title: 수협카드
        GWANGJU_CARD:
          title: 광주카드
        HYUNDAI_CARD:
          title: 현대카드
        EPOST:
          title: 우체국
        BC_CARD:
          title: BC카드
        K_BANK:
          title: 케이뱅크
        JEJU_CARD:
          title: 제주카드
        KOOKMIN_CARD:
          title: 국민카드
        MIRAE_ASSET_SECURITIES:
          title: 미래에셋증권
        NH_CARD:
          title: NH카드
        SHINHAN_CARD:
          title: 신한카드
        CITI_CARD:
          title: 씨티카드
        SAVINGS_BANK_KOREA:
          title: 저축은행
        KFCC:
          title: 새마을금고
        KAKAO_BANK:
          title: 카카오뱅크
        TOSS_BANK:
          title: 토스뱅크
    ChannelNotFoundError:
      title: 요청된 채널이 존재하지 않는 경우
      description: 요청된 채널이 존재하지 않는 경우
      type: object
      required:
      - type
      properties:
        type:
          type: string
        message:
          type: string
      x-portone-title: 요청된 채널이 존재하지 않는 경우
      x-portone-status-code: 404
    UnauthorizedError:
      title: 인증 정보가 올바르지 않은 경우
      description: 인증 정보가 올바르지 않은 경우
      type: object
      required:
      - type
      properties:
        type:
          type: string
        message:
          type: string
      x-portone-title: 인증 정보가 올바르지 않은 경우
      x-portone-status-code: 401
    GetPgCardPromotionsResponse:
      title: PG사 카드 프로모션 조회 응답
      description: PG사 카드 프로모션 조회 응답
      type: object
      properties:
        promotions:
          title: 카드 프로모션 목록
          type: array
          items:
            $ref: '#/components/schemas/PgCardPromotion'
          x-portone-title: PG사 카드 프로모션
          x-portone-description: PG사에서 제공하는 카드 프로모션 정보입니다.
          properties:
            promotionId:
              title: 프로모션 아이디
              description: PG사에서 부여한 프로모션 식별자입니다.
            cardCompany:
              title: 카드사
              description: 프로모션이 적용되는 카드사입니다.
            discountAmount:
              title: 할인 금액
              description: 프로모션 적용 시 할인되는 금액입니다.
            minimumPaymentAmount:
              title: 최소 결제 금액
              description: 프로모션이 적용되기 위한 최소 결제 금액입니다.
      x-portone-title: PG사 카드 프로모션 조회 응답
    PgProviderError:
      title: PG사에서 오류를 전달한 경우
      description: PG사에서 오류를 전달한 경우
      type: object
      required:
      - type
      - pgCode
      - pgMessage
      properties:
        type:
          type: string
        message:
          type: string
        pgCode:
          type: string
        pgMessage:
          type: string
      x-portone-title: PG사에서 오류를 전달한 경우
      x-portone-status-code: 502
    PgCardPromotion:
      title: PG사 카드 프로모션
      description: 'PG사 카드 프로모션


        PG사에서 제공하는 카드 프로모션 정보입니다.'
      type: object
      required:
      - promotionId
      - cardCompany
      - discountAmount
      - minimumPaymentAmount
      properties:
        promotionId:
          type: string
          title: 프로모션 아이디
          description: PG사에서 부여한 프로모션 식별자입니다.
        cardCompany:
          $ref: '#/components/schemas/PgPromotionCardCompany'
          title: 카드사
          description: 프로모션이 적용되는 카드사입니다.
        discountAmount:
          type: integer
          format: int64
          title: 할인 금액
          description: 프로모션 적용 시 할인되는 금액입니다.
        minimumPaymentAmount:
          type: integer
          format: int64
          title: 최소 결제 금액
          description: 프로모션이 적용되기 위한 최소 결제 금액입니다.
      x-portone-title: PG사 카드 프로모션
      x-portone-description: PG사에서 제공하는 카드 프로모션 정보입니다.
  securitySchemes:
    bearerJwt:
      type: http
      description: 'Authorization: Bearer `엑세스 토큰`'
      scheme: bearer
    portOne:
      type: http
      description: 'Authorization: PortOne `발급된 API 시크릿`'
      scheme: portone
x-portone-categories:
- id: payment
  title: 결제 관련 API
  description: 결제와 관련된 API 기능을 제공합니다.
  children:
  - id: payment.paymentSchedule
    title: 결제 예약 관련 API
    description: 결제 예약과 관련된 API 기능을 제공합니다.
  - id: payment.billingKey
    title: 빌링키 관련 API
    description: 빌링키와 관련된 API 기능을 제공합니다.
  - id: payment.cashReceipt
    title: 현금 영수증 관련 API
    description: 현금 영수증과 관련된 API 기능을 제공합니다.
  - id: payment.promotion
    title: 프로모션 관련 API
    description: 프로모션과 관련된 API 기능을 제공합니다.
  - id: payment.additionalFeature
    title: 결제 부가기능 관련 API
    description: 결제 부가기능과 관련된 API 기능을 제공합니다.
- id: identityVerification
  title: 본인인증 관련 API
  description: 본인인증과 관련된 API 기능을 제공합니다.
- id: pgSpecific
  title: 특정 PG사 관련 API
  description: 특정 PG사에 국한된 API 기능을 제공합니다.
- id: reconciliation
  title: 대사 서비스 API
  description: 거래 대사 및 정산 대사 관련 API 기능을 제공합니다.
- id: b2b
  title: 세금계산서 API
  description: 세금계산서 API 기능을 제공합니다.
  children:
  - id: b2b.counterparty
    title: 거래처 관련 API
    description: 거래처 관련 API 기능을 제공합니다.
  - id: b2b.taxInvoice
    title: 세금계산서 발행 관련 API
    description: 세금계산서 발행 관련 API 기능을 제공합니다.
- id: platform
  title: 파트너 정산 관련 API
  description: 파트너 정산 서비스 API 기능을 제공합니다.
  children:
  - id: platform.policy
    title: 정책 관련 API
    description: 파트너 정산에 적용할 정책에 관한 API 입니다.
  - id: platform.partner
    title: 파트너 관련 API
    description: 파트너 정산에 적용할 파트너에 관한 API 입니다.
  - id: platform.transfer
    title: 정산 상세내역 관련 API
    description: 파트너 정산 서비스의 정산 상세내역과 관련된 API 입니다.
  - id: platform.account
    title: 계좌 관련 API
    description: 파트너 정산 서비스의 계좌와 관련된 API 입니다.
  - id: platform.partnerSettlement
    title: 정산 내역 관련 API
    description: 파트너 정산 서비스의 정산 내역과 관련된 API 입니다.
  - id: platform.payout
    title: 지급 내역 관련 API
    description: 파트너 정산 서비스의 지급 내역과 관련된 API 입니다.
  - id: platform.bulkPayout
    title: 일괄 지급 내역 관련 API
    description: 파트너 정산 서비스의 일괄 지급 내역과 관련된 API 입니다.
  - id: platform.accountTransfer
    title: 이체 내역 관련 API
    description: 파트너 정산 서비스의 이체 내역과 관련된 API 입니다.
  - id: platform.bulkAccountTransfer
    title: 일괄 이체 내역 관련 API
    description: 파트너 정산 서비스의 일괄 이체 내역과 관련된 API 입니다.
  - id: platform.company
    title: 사업자 관련 API
    description: 파트너 정산 서비스의 사업자와 관련된 API 입니다.
- id: auth
  title: 인증 관련 API
  description: '인증과 관련된 API 기능을 제공합니다.

    접근 토큰 방식으로 인증하기를 원하는 경우, API 시크릿을 통해 토큰을 발급받은 후 Authorization 헤더에 `Bearer ACCESS_TOKEN` 형식으로 전달합니다.'
- id: paymentSession
  title: 결제 세션 API
  description: 결제 세션 생성 및 관리 API. 호스티드 체크아웃에 사용됩니다.
- id: checkoutProfile
  title: 체크아웃 프로필 API
  description: 체크아웃 프로필에서 결제 수단 목록을 조회하기 위한 API.
- id: ap
  title: AP API
  description: AP 기능을 제공합니다.
- id: common
  title: 공통 API
  description: 공통 API 기능을 제공합니다.