파트너정산 API

파트너정산에 관련된 API 를 확인할 수 있습니다

서문

안녕하세요. 포트원 PO 김준일입니다.

파트너 정산 Public API의 스펙을 소개합니다.

포트원이 제공하는 관리자 콘솔을 통해 정산 업무를 확인하고자 한다면, 정산 부분을 참고해주시고, 귀사의 자체 백오피스에 통합하길 원하신다면 전체 API 스펙을 검토해주시기 바랍니다.

간단하게 api 사용방법을 원하신다면 예제 페이지를 참고해주세요.

이체 관련 API는 문서 작업중이며 빠른시일내에 업데이트 하겠습니다.

더 궁금한 사항이 있으시거나 추가적인 도움이 필요하시면 언제든지 연락주세요.

openapi.yaml 파일 혹은 graphql로 개발하시길 희망하실 경우 편하게 연락주시면 됩니다.

정산

고객의 주문(order-transfer) 와 주문취소(order-cancel-transfer)로 부터 계약 규칙에 맞게 파생되는 정산금과 수동으로(manual-transfer) 임의의 정산금액을 등록할 수 있습니다. 고객의 주문건에 대해서는 결제/환불 모두 적용할 수 있습니다.

Endpoints

POST /platform/transfers/order
POST /platform/transfers/order-cancel
POST /platform/transfers/manual
GET /platform/transfers/{id}
GET /platform/transfer-sumaries
GET /platform/transfer-dashbaord
GET /platform/transfer-filter-options

정산 객체

정산 생성 및 조회시 response 로 반환되는 transfer 객체의 파라미터 별 설명입니다.

Attributes type enum 정산 타입

Enum Value	Description
ORDER	주문 정산
ORDER_CANCEL	주문 취소 정산
MANUAL	수동 정산

id string

정산 객체 아이디

graphqlId string

포트원 내부에서 사용되는 정산 객체 graphql 아이디. 혹시 graphql을 더 선호하신다면 연락 부탁드립니다.

partner dictionary

정산의 대상이 되는 파트너 객체

partner attribute

status enum

정산의 상태값

Enum Value	Description
SCHEDULED	정산 시작일(settlementStartDate)이 현시점 이후일때 예약 상태
IN_PROCESS	현시점이 정산 시작일 이후 정산일(settlementDate) 이전일때 진행중 상태
SETTLED	현시점이 정산일 이후일때 완료 상태
IN_PAYOUT	이체 중. 관리자 콘솔 내에서 대량이체 엑셀 파일을 받은 후 아직 이체완료 상태값 업데이트를 하지 않았을때
PAID_OUT	이체 완료 상태

memo string

정산에 대한 메모. 수동 정산(manual)에만 해당됩니다.

settlementDate string

정산일. 정산주기에 맞게 파트너에게 이체되어야 하는 시점이다.

yyyy-MM-dd 형식을 따릅니다.

payoutId string

정산 객체가 정산주기에 맞춰서 포함될 이체 객체의 고유 아이디

status 가 IN_PAYOUT 일때부터 생성됩니다성

payoutGraphqlID string

payoutId의 내부 graphql 아이디

contract dictionary

정산에 적용되는 계약 객체

contract entity

isForTest boolean

테스트용 정산인지 여부. false 일때 실제 정산입니다.

amount dictionary 정산 금액 정보

amount.settlement int64

계산된 정산금액.

기본적으로 주문금액 - 플랫폼_중계_수수료 - 중계_수수료_부가세 - PG사_수수료 - PG사_수수료_부가세- 할인분담금 - 추가수수료 - 추가수수료_부가세 로 계산됩니다.

수식설정을 통해 계산법을 변경하실 수 있습니다. 수식 설정은 관리자 콘솔에서 가능합니다.

amount.payment int64

결제금액.

amount.order int64

주문금액. 주문금액 = 결제금액 + 할인금액 으로 통상적으로 계산됩니다.

amount.platformFee int64

계산된 플랫폼 중개 수수료. 기본적으로 contractId 에 해당되는 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다.

amount.platformFeeVat int64

계산된 중개수수료 부가세. 기본적으로 중개 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다.

amount.additionalFee int64

계산된 추가 수수료. 기본적으로 additionalFeeIds 에 해당되는 추가 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다.

amount.additionalFeeVat int64

계산된 추가 수수료 부가세. 기본적으로 추가 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다.

amount.discountShare int64

계산된 파트너 할인 분담 금액. discountShareId 의 분담율이 적용됩니다.

amount.discount int64

할인금

payment dictionary

주문 정산건에 해당되는 결제 정보. 포트원(Portone) 결제일때 와 외부 결제(External) 일때 요구되는 값이 다릅니다. 해당 값은 one of 로직으로 간주되어 "payment": { "type" : "INTERNAL" 혹은 "EXTERNAL"} 와 같이 전달해야 합니다.

payment.type string required

결제 타입. 포트원 결제일때는 “INTERNAL” 입니다.

payment.id string required

merchant_uid(V1) 혹은 payment_id(V2)

혹여나 주문은 이루어 졌지만 결제가 이루어지지 않은 경우가 있습니다. 대표적인 예로 포인트 및 쿠폰 (할인) 으로 상품을 사는 case 입니다. 해당 경우에는 포트원 결제는 없어도 가맹점 내에서 해당 주문에 대한 주문 아이디를 전달해주셔야 합니다.

payment.storeId string

포트원 가맹점의 스토어 아이디. 관리자 콘솔에서 확인하실 수 있습니다.

포트원 결제일때만 반환됩니다.

payment.channelKey string

포트원 결제시 사용된 채널키. 관리자 콘솔에서 확인하실 수 있습니다.

포트원 결제일때만 반환됩니다.

payment.orderName string

주문명. 임의로 전달해주실 수 있습니다.

payment.method dicionary

주문건의 결제수단 아래 결제 수단중 하나만 택해서 전달해야 합니다. 간편 결제수단(“easyPay”) 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 ({}) 을 전달해야 합니다.

method.card dictionary optional

신용카드

method.transfer dictionary optional

계좌이체

method.virtualAccount dictionary optional

가상계좌

method.giftCertificate dictionary optional

상품권

method.mobile dictionary optional

휴대폰 소액결제

method.easyPay dictionary optional

간편결제

easyPay.provider enum

간편결제 브랜드 (i.e. “KAKAOPAY”)

easyPay.method enum

간편결제 내의 결제 수단 (i.e. “CARD”, “TRANSFER”)

payment.currency enum

외부 결제연동 서비스를 통해 결제된 주문건의 결제통화

현재는 ‘KRW’, ‘JPY’, ‘USD’ 만 지원합니다.

payment.paidAt Date

결제 완료 시점

settlementStartDate Date

정산 시작일. 정산주기에 맞춰서 정산이 진행되는 시점이다. 정산 주기가 적용되는 시점이다.

orderDetails dictionary required

주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다.

one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우에는 "orderDetails" : {"orderAmount": 금액} 와 같이 전달하시면 됩니다. 상품 정보 및 상품별 할인 및 추가수수료를 적용하여 전달하고 싶으신 경우에는 "orderDetails" : {"orderLines": [{...}, {...}]} 와 같이 전달하시면 됩니다.

payment.type = INTERNAL 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 payment.id 에 해당되는 결제금액 + discounts.amount 의 합에 해당되는 할인금액 으로 계산됩니다.

주문금액만 전달할 경우 ("orderDetails": {"orderAmount": 금액})

orderAmount int optional

정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다.

단일 주문건에 정산해야할 파트너 대상이 여러명일 경우, 혹은 다른 이유로 여러 정산 건을 생성하고 싶을 경우, 해당되는 주문금액을 전달하시면 됩니다.

전달하지 기본값은 주어진 payment.portOne.id 에 해당되는 결제금액 + discounts.amount 의 합에 해당되는 할인금액 입니다.

payment.external 일때는 orderAmount 혹은 orderLines 를 통해서 주문금액을 전달해주셔야 합니다.

상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 ("orderDetails": {"orderLines": [{...}, {...}]})

해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다.

orderLines.product dictionary required

주문정산건에 해당되는 낱개 상품 정보.

product.id string required

상품 아이디. 가맹점의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다.

product.name string required

상품 이름. 가맹점의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다.

product.amount int required

상품 가격. 상품의 낱개 가격입니다.

product.tag list of string optional

상품 태그. 내부 구분을 위한 태그입니다.

orderLines.quantity int required

상품 갯수

orderLines.discounts list of dictionary optional

해당 상품에 적용될 할인정보 리스트 할인 정책 참고

orderLines.additionalFees list of dictionary optional

해당 상품에 적용된 추가수수료 정책 리스트. 포트원에 등록된 추가수수료 아이디를 보내주시면 됩니다. 해당 아이디의 추가수수료가 정산에 적용됩니다. 추가수수료 참고]

discounts list of dictionary

할인 금액과 유형 (discountShares) 객체의 리스트

리스트의 각 객체별 단일 할인에 해당된다.

해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다.

할인 정책 참고

discounts.amount int64

할인 금액

discounts.sharePolicy dictionary

할인 정책 (sharePolicy) 객체

sharePolicy.id string

할인 정책 객체 고유 아이디

sharePolicy.partnerShareRate int64

할인 분담율

sharePolicy.memo string

할인유형 객체 가맹점 지정 내부 메모

sharePolicy.isHidden boolean

할인유형 객체 숨김 여부

sharePolicy.appliedAt Date

할인유형 객체 적용 시간

additionalFees list of dictionary

추가수수료 (additionalFee) 객체의 리스트

해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다.

추가 수수료 참고

additionalFee attributes

additionalFee.policy dictionary

추가수수료 정책 (additionalFeePolicy) 객체

policy.id string

추가수수료 정책 객체 고유 아이디

policy.fee dictionary

추가수수료 정책 객체 수수료

fee.amount int64

추가수수료 정책 객체 수수료 정액 금액

fee.rate int64

추가수수료 정책 객체 수수료 비율 1*10^5 으로써 10% 일경우 100000 으로 입력

Response (주문 정산예시)

{
  "transfer": {
    "type": "ORDER",
    "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2",
    "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==",
    "partner": {
      "id": "partner_2",
      "graphqlId": "NDpwYXJ0bmVyXzI=",
      "name": "파이썬 강사",
      "email": "kjnkyj12@gmail.com",
      "businessRegistrationNumber": "1178178260",
      "account": {
        "bank": "SHINHAN",
        "currency": "KRW",
        "number": "10358907249",
        "holder": "김준일",
        "status": "VERIFIED"
      },
      "status": "APPROVED",
      "defaultContractId": "contract_2",
      "memo": "잭슨 테스트",
      "tags": ["파이썬"],
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:25.645014Z"
    },
    "status": "IN_PROCESS",
    "memo": "testing order transfer",
    "settlementDate": "2023-08-18",
    "settlementCurrency": "KRW",
    "isForTest": true,
    "amount": {
      "settlement": 17250,
      "payment": 20000,
      "order": 25000,
      "platformFee": 2500,
      "platformFeeVat": 0,
      "additionalFee": 2500,
      "additionalFeeVat": 250,
      "discount": 5000,
      "discountShare": 2500
    },
    "contract": {
      "id": "contract_2",
      "graphqlId": "NTpjb250cmFjdF8y",
      "memo": "contract 2",
      "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
      "settlementCycle": {
        "lagDays": 2,
        "datePolicy": "CALENDAR_DAY",
        "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
      },
      "platformFeeVatPayer": "MERCHANT",
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:17.207733Z"
    },
    "payment": {
      "type": "EXTERNAL",
      "id": "payment_1",
      "orderName": "테스트 주문",
      "currency": "KRW",
      "method": { "type": "CARD" },
      "paidAt": "2023-08-11T08:21:01.241Z"
    },
    "settlementStartDate": "2023-08-11",
    "orderLines": [
      {
        "product": { "id": "1", "name": "product_1", "amount": 5000 },
        "quantity": 5,
        "discounts": [
          {
            "sharePolicy": {
              "id": "discount_1",
              "graphqlId": "MjpkaXNjb3VudF8x",
              "partnerShareRate": 500000000,
              "memo": "테스트 할인",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:45:45.799176Z"
            },
            "amount": 2500,
            "shareAmount": 1250
          }
        ],
        "additionalFees": [
          {
            "policy": {
              "id": "addtional_fee_1",
              "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
              "fee": { "type": "FIXED_RATE", "rate": 5000 },
              "memo": "테스트 추가수수료",
              "vatPayer": "PARTNER",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:41:12.393974Z"
            },
            "amount": 1250,
            "vat": 125
          }
        ],
        "amount": {
          "settlement": 19875,
          "payment": 22500,
          "order": 25000,
          "platformFee": 2500,
          "platformFeeVat": 0,
          "additionalFee": 1250,
          "additionalFeeVat": 125,
          "discount": 2500,
          "discountShare": 1250
        }
      }
    ],
    "additionalFees": [
      {
        "policy": {
          "id": "addtional_fee_1",
          "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
          "fee": { "type": "FIXED_RATE", "rate": 5000 },
          "memo": "테스트 추가수수료",
          "vatPayer": "PARTNER",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:41:12.393974Z"
        },
        "amount": 1250,
        "vat": 125
      }
    ],
    "discounts": [
      {
        "sharePolicy": {
          "id": "discount_1",
          "graphqlId": "MjpkaXNjb3VudF8x",
          "partnerShareRate": 500000000,
          "memo": "테스트 할인",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:45:45.799176Z"
        },
        "amount": 2500,
        "shareAmount": 1250
      }
    ]
  }
}

주문 정산건 생성

POST https://api.portone.io/platform/transfers/order

주문 정산건이란 결제를 기반으로 한 주문건에 대해서 각 파트너에게 정산해주기 위한 정산객체를 api로 등록하는 겁니다.

Parameters

partnerId string required

주문 정산건에 해당되는 파트너 지정

contractId string optional

주문 정산건에 적용될 계약의 아이디. 기본으로 정산될 파트너의 기본 계약이 적용되지만 contractId 를 통해 다른 계약을 지정할 경우 지정된 계약의 정보가 적용된다.

memo string optional

정산건에 내부 구분을 위한 메모

paymentId dictionary required

가맹점 주문 아이디. 포트원 결제일 경우 포트원 결제에 전달해주시는 merchant_uid (v1) 혹은 payment_id(v2) 를 전달하셔야 합니다. 외부결제 일 경우 단순히 가맹점 주문번호를 전달해주시면 됩니다.

orderDetails dictionary required

주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다.

payment.portOne 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 payment.portOne.id 에 해당되는 결제금액 + discounts.amount 의 합에 해당되는 할인금액 으로 계산됩니다.

주문금액만 전달할 경우 ("orderDetails": {"orderAmount": 금액})

orderAmount int optional

정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다.

전달하지 기본값은 주어진 payment.portOne.id 에 해당되는 결제금액 + discounts.amount 의 합에 해당되는 할인금액 입니다.

payment.external 일때는 orderAmount 혹은 orderLines 를 통해서 주문금액을 전달해주셔야 합니다.

상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 ("orderDetails": {"orderLines": [{...}, {...}]})

해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다.

orderLines.product dictionary required

주문정산건에 해당되는 낱개 상품 정보.

product.id string required

상품 아이디. 가맹점의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다.

product.name string required

상품 이름. 가맹점의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다.

product.amount int required

상품 가격. 상품의 낱개 가격입니다.

product.tag list of string optional

상품 태그. 내부 구분을 위한 태그입니다.

orderLines.quantity int required

상품 갯수

orderLines.discounts list of dictionary optional

해당 상품에 적용될 할인정보 리스트 할인 정책 참고

discounts.sharePolicyId string required

적용될 할인정책 아이디.

discounts.amount int required

해당 할인정책이 적용되는 할인금액. i.e. 1000원 쿠폰에 대한 할인이면 1000

orderLines.additionalFees list of dictionary optional

additionalFees.policyId string required

적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다.

settlementStartDate string 기본값은 결제완료 시점 optional

'yyyy-MM-dd' 형식을 따릅니다.

정산 시작일로써 정산 주기가 적용될 날짜이다. 주문완료, 배송완료 등 정산이 고려되기 시작해야하는 시간을 뜻한다. 기본값은 주문정산건과 연결된 결제의 완료 시점으로 업데이트 된다.

따라서 payment.type = ‘INTERNAL’ 일때는 포트원 결제완료 시점, payment.type = ‘EXTERNAL’ 일때는 externalPaymentDetail.paidAt 값이 기본값으로 적용되며 payment.paidAt 값을 전달하지 않을경우 현재시점으로 적용된다.

배송완료 예정일, 수강 오픈일, 등 미래시점으로 지정해 놓으면 해당 시점부터 정산주기가 적용되며 그동안 정산객체의 상태값은 준비 (SCHEDULED)로 적용된다.

discounts list of dictionary optional

주문 정산건에 적용할 할인 정책들의 리스트. 할인 정책 객체들로 이루어져 있다.

할인 정책이란 특정 주문에 적용된 할인에 대해서 유형별 파트너 분담율을 정산에 계산하기 위한 객체이다.

orderLines를 통해 각 상품별 적용될 할인 정보와 orderLines.discounts 별개로 해당 파라미터는 주문건 전체에 적용될 할인 정보를 전달할 때 사용합니다.

discount.sharePolicyId* string required

할인 정책 아이디. 포트원에 등록된 할인 정책 아이디를 보내주시면 됩니다. 해당 아이디의 할인분담율이 정산에 적용됩니다.

discount.amount int64 required

할인 금액. 주문금액보다 클 수 없습니다.

additionalFees list of dictionary optional

주문 정산건에 적용될 추가 수수료 아이디들의 리스트

추가수수료란 특정 주문정산건에 가맹점이 파트너에게 추가 서비스를 제공함으로써 과금되는 수수료 이다. 정산수식에대한 수정이 있지 않는한 기본으로 추가수수료는 주문금액에 부과된다. 추가수수료 참고]

additionalFees.policyId string required

적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다.

externalPaymentDetail dictionary optional

포트원 결제가 아닌 경우에만 전달하셔야 합니다.

externalPaymentDetail.currency enum required

외부 결제 통화. ‘KRW’,‘USD’,‘JPY’만 지원합니다.

externalPaymentDetail.orderName string optional

외부 결제 주문명.

externalPaymentDetail.paidAt string optional

외부 결제 완료 시점. ‘yyyy-MM-dd’T’HH:mm:ss.SSSZ’ 형식을 따릅니다. 기본값은 현재시점입니다.

externalPaymentDetail.method dicionary

외부 결제연동 서비스를 통해 결제된 주문건의 결제수단 아래 결제 수단중 하나만 택해서 전달해야 합니다. 간편 결제수단(“easyPay”) 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 ({}) 을 전달해야 합니다.

method.card dictionary optional

신용카드

method.transfer dictionary optional

계좌이체

method.virtualAccount dictionary optional

가상계좌

method.giftCertificate dictionary optional

상품권

method.mobile dictionary optional

휴대폰 소액결제

method.easyPay dictionary optional

간편결제

easyPay.provider enum

간편결제 브랜드 (i.e. “KAKAOPAY”)

easyPay.method enum

간편결제 내의 결제 수단 (i.e. “CARD”, “TRANSFER”)

payment.currency enum

외부 결제연동 서비스를 통해 결제된 주문건의 결제통화

현재는 ‘KRW’, ‘JPY’, ‘USD’ 만 지원합니다.

isForTest boolean optional 기본값은 false

포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다.

Request body one of 까지 다 표현되어 모든 파라미터가 나옵니다.

{
  "partnerId": "string",
  "contractId": "string",
  "memo": "string",
  "paymentId": "string",
  "orderDetail": {
    "orderAmount": 0,
    "orderLines": [
      {
        "product": {
          "id": "string",
          "name": "string",
          "amount": 0,
          "tag": "string"
        },
        "quantity": 0,
        "discounts": [
          {
            "sharePolicyId": "string",
            "amount": 0
          }
        ],
        "additionalFees": [
          {
            "policyId": "string"
          }
        ]
      }
    ]
  },
  "settlementStartDate": "string",
  "discounts": [
    {
      "sharePolicyId": "string",
      "amount": 0
    }
  ],
  "additionalFees": [
    {
      "policyId": "string"
    }
  ],
  "externalPaymentDetail": {
    "currency": "AED",
    "orderName": "string",
    "paidAt": "2023-08-15T08:14:26.703Z",
    "method": {
      "card": {},
      "transfer": {},
      "virtualAccount": {},
      "giftCertificate": {},
      "mobile": {},
      "easyPay": {
        "provider": "APPLEPAY",
        "method": "CARD"
      }
    }
  },
  "isForTest": true
}

Response

주문 정산객체가 반환됩니다.

정산 시작일 참고

정산시작일(settlementStartDate)을 전달하지 않을경우 결제완료 시점으로 기본으로 지정됩니다. 이 경우 정산 api호출시점에 결제완료가 아직 되지 않았다면 에러를 반환합니다.
정산시작일(settlementStartDate)을 미래의 시점으로 전달할 경우 status 는 PREPARE이고 이에 적용될 계약정보는 정산api를 호출한 시점에 등록된 계약으로 적용되나 계약정보가 바뀌어 업데이트 될 여지가 있습니다.

포트원 결제일 경우
상품 정보를 전달할 경우

{
  "transfer": {
    "type": "ORDER",
    "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2",
    "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==",
    "partner": {
      "id": "partner_2",
      "graphqlId": "NDpwYXJ0bmVyXzI=",
      "name": "파이썬 강사",
      "email": "kjnkyj12@gmail.com",
      "businessRegistrationNumber": "1178178260",
      "account": {
        "bank": "SHINHAN",
        "currency": "KRW",
        "number": "10358907249",
        "holder": "김준일",
        "status": "VERIFIED"
      },
      "status": "APPROVED",
      "defaultContractId": "contract_2",
      "memo": "잭슨 테스트",
      "tags": ["파이썬"],
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:25.645014Z"
    },
    "status": "IN_PROCESS",
    "memo": "testing order transfer",
    "settlementDate": "2023-08-18",
    "settlementCurrency": "KRW",
    "isForTest": true,
    "amount": {
      "settlement": 17250,
      "payment": 20000,
      "order": 25000,
      "platformFee": 2500,
      "platformFeeVat": 0,
      "additionalFee": 2500,
      "additionalFeeVat": 250,
      "discount": 5000,
      "discountShare": 2500
    },
    "contract": {
      "id": "contract_2",
      "graphqlId": "NTpjb250cmFjdF8y",
      "memo": "contract 2",
      "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
      "settlementCycle": {
        "lagDays": 2,
        "datePolicy": "CALENDAR_DAY",
        "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
      },
      "platformFeeVatPayer": "MERCHANT",
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:17.207733Z"
    },
    "payment": {
      "type": "EXTERNAL",
      "id": "payment_1",
      "orderName": "테스트 주문",
      "currency": "KRW",
      "method": { "type": "CARD" },
      "paidAt": "2023-08-11T08:21:01.241Z"
    },
    "settlementStartDate": "2023-08-11",
    "orderLines": [
      {
        "product": { "id": "1", "name": "product_1", "amount": 5000 },
        "quantity": 5,
        "discounts": [
          {
            "sharePolicy": {
              "id": "discount_1",
              "graphqlId": "MjpkaXNjb3VudF8x",
              "partnerShareRate": 500000000,
              "memo": "테스트 할인",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:45:45.799176Z"
            },
            "amount": 2500,
            "shareAmount": 1250
          }
        ],
        "additionalFees": [
          {
            "policy": {
              "id": "addtional_fee_1",
              "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
              "fee": { "type": "FIXED_RATE", "rate": 5000 },
              "memo": "테스트 추가수수료",
              "vatPayer": "PARTNER",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:41:12.393974Z"
            },
            "amount": 1250,
            "vat": 125
          }
        ],
        "amount": {
          "settlement": 19875,
          "payment": 22500,
          "order": 25000,
          "platformFee": 2500,
          "platformFeeVat": 0,
          "additionalFee": 1250,
          "additionalFeeVat": 125,
          "discount": 2500,
          "discountShare": 1250
        }
      }
    ],
    "additionalFees": [
      {
        "policy": {
          "id": "addtional_fee_1",
          "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
          "fee": { "type": "FIXED_RATE", "rate": 5000 },
          "memo": "테스트 추가수수료",
          "vatPayer": "PARTNER",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:41:12.393974Z"
        },
        "amount": 1250,
        "vat": 125
      }
    ],
    "discounts": [
      {
        "sharePolicy": {
          "id": "discount_1",
          "graphqlId": "MjpkaXNjb3VudF8x",
          "partnerShareRate": 500000000,
          "memo": "테스트 할인",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:45:45.799176Z"
        },
        "amount": 2500,
        "shareAmount": 1250
      }
    ]
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
400	PlatformDiscountAmountOverflowError
400	PlatformProductIdDuplicatedError
400	PlatformSettlementExceededPaymentAmountError
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformPartnerNotFoundError
404	PlatformContractNotFoundError
404	PlatformAdditionalFeePoliciesNotFoundError
404	PlatformDiscountSharePoliciesNotFoundError
404	PlatformPaymentNotFoundError
409	PlatformTransferAlreadyExistsError

주문 취소 정산건 생성

POST https://api.portone.io/platform/transfers/order-cancel

주문 취소 정산건이란 결제 취소를 기반으로 파트너에게 정산금을 차감할 수 있는 api입니다.

취소 정산 등록은 사전에 주문 정산이 등록되어 있는 경우에만 사용할 수 있습니다.

결제 취소에 대한 id를 전달주셔야 하며 취소시 차감되는 주문금액 및 할인금액 에 따라 차감될 정산금액을 계산합니다.

Parameters

partnerId required

주문 취소 정산건에 해당되는 파트너 지정

paymentId required

취소하고자 하는 기존 주문건의 paymentId. 기존에 주문정산으로써 등록 되어있어야 합니다.

cancellationId required

결제 취소 아이디. 포트원 결제일 경우 결제취소 아이디 (cancellation_id) 는 v2 api를 통해 발급 가능하며 #결제-취소(POST https://api.portone.io/v2/payments/{payment_id}/cancel), 결제내역-단건조회 (GET https://api.portone.io/v2/payments) api를 통해 받으실 수 있습니다. (참고: https://developers.portone.io/docs/ko/api-v2/payment/)

외부 결제일 경우 단순히 결제 취소건당 unique한 아이디를 전달해주시면 됩니다.

memo optional

주문 취소 정산 건에 내부 구분을 위한 메모

orderDetails required

주문취소 정산건에 해당되는 주문 상세 정보. 기존 주문건에 포함된 상품의 정보중 취소하고자 한는 항목을 전달해야 합니다.

one of 로직으로써 단순히 주문취소 금액만 전달하고 싶으신 경우에는 "orderDetails" : {"orderAmount": 금액} 와 같이 전달하시면 됩니다. 취소하고자 하는 상품 정보 및 상품별 할인금 을 전달하고 싶으신 경우에는 "orderDetails" : {"orderLines": [{...}, {...}]} 와 같이 전달하시면 됩니다. 단순히 전체 취소를 하시고 싶으시다면 "orderDetails" : {"all": []} 와 같이 전달하시면 됩니다.

주문취소 금액만 전달할 경우 ("orderDetails": {"orderAmount": 금액})

orderAmount optional

주문 취소시 적용될 주문 취소금액. 주문금액 인점 유의 하셔야 합니다. 주문금액은 결제금액 + 할인금액 입니다.

해당 값이 주문 정산시 주문금액과 동일한 경우에는 따로 취소하실 할인금액을 전달하지 않으셔도 환불 처리 됩니다.

상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 ("orderDetails": {"orderLines": [{...}, {...}]})

해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다.

orderLines.productId dictionary required

취소하고자 하는 상품 아이디

orderLines.quantity required

취소하고자 하는 상품 갯수

orderLines.discounts list of dictionary optional

해당 상품에서 취소하고자 하는 할인정보 리스트

상품에 대한 모든 수량 취소시 모든 discount도 자동으로 취소됩니다.

discounts.amount required

취소할 할인 금액. 해당 상품에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다.

discounts.sharePolicyId required

할인 정책 아이디. 주문 정산시 상품에 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다.

전체 취소를 하고자 할 경우 ("orderDetails": {"all": []})

discounts optional

주문 취소시 적용될 할인정보 리스트

모든 금액 취소시 모든 discount도 자동으로 취소됩니다.

discount.sharePolicyId string required

할인 정책 아이디. 주문 정산시 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다.

discount.amount int64 required

취소할 할인 금액. 해당 주문에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다.

settlementStartDate string 기본값은 결제완료 시점

'yyyy-MM-dd' 형식의 문자열로 전달해주시면 됩니다.

취소 정산 또한 주문 정산과 동일하게 정산주기가 적용됩니다. 따라서 주문 정산건이 이미 정산이 되었고 해당 주문건에 대한 취소정산이 이루어졌을때 취소금액은 다음 정산주기에 적용됩니다.

따라서 payment.type = INTERNAL 일때는 포트원 결제취소 시점 값이 기본값으로 적용됩니다.

isForTest boolean optional 기본값은 false

취소 정산의 취소 주문금액 , 상품별 취소 주문 금액 및 수량, 주문 취소 할인금액 및 상품별 취소 할인 금액에 따라 새로운 음수 정산금액을 계산하신다고 이해하시면 됩니다.

Request Body one of 로직에 해당되는 parameter가 다 표기되었습니다.

{
  "partnerId": "string",
  "paymentId": "string",
  "cancellationId": "string",
  "memo": "string",
  "orderDetail": {
    "orderAmount": 0,
    "orderLines": [
      {
        "productId": "string",
        "quantity": 0,
        "discounts": [
          {
            "sharePolicyId": "string",
            "amount": 0
          }
        ]
      }
    ],
    "all": {}
  },
  "discounts": [
    {
      "sharePolicyId": "string",
      "amount": 0
    }
  ],
  "settlementStartDate": "string",
  "externalCancellationDetail": {
    "cancelledAt": "2023-08-15T09:02:20.868Z"
  },
  "isForTest": true
}

Response

취소 정산시 반환되는 금액 및 수수 값들은 다 주문정산객체 값의 음수처리 입니다.

외부 결제일때
orderAmount 일때

{
  "transfer": {
    "type": "ORDER_CANCEL",
    "id": "01H7J87XQ4JAS28RWZBC29YCJ1",
    "graphqlId": "NjowMUg3Sjg3WFE0SkFTMjhSV1pCQzI5WUNKMQ==",
    "partner": {
      "id": "partnerA",
      "graphqlId": "NDpwYXJ0bmVyQQ==",
      "name": "파이썬 강사",
      "email": "kjnkyj12@gmail.com",
      "businessRegistrationNumber": "1178178260",
      "account": {
        "bank": "SHINHAN",
        "currency": "KRW",
        "number": "10358907249",
        "holder": "김준일",
        "status": "VERIFIED"
      },
      "status": "APPROVED",
      "defaultContractId": "contractA",
      "memo": "잭슨 테스트 예시문",
      "tags": ["파이썬"],
      "isHidden": false,
      "appliedAt": "2023-08-11T11:19:58.829787Z"
    },
    "status": "SCHEDULED",
    "settlementDate": "2023-08-31",
    "settlementCurrency": "KRW",
    "isForTest": false,
    "amount": {
      "settlement": 4450,
      "payment": 5000,
      "order": 5000,
      "platformFee": 500,
      "platformFeeVat": 50,
      "additionalFee": 0,
      "additionalFeeVat": 0,
      "discount": 0,
      "discountShare": 0
    },
    "contract": {
      "id": "contractA",
      "graphqlId": "NTpjb250cmFjdEE=",
      "memo": "contract A",
      "platformFee": {
        "type": "FIXED_RATE",
        "rate": 10000
      },
      "settlementCycle": {
        "lagDays": 2,
        "datePolicy": "HOLIDAY_BEFORE",
        "method": {
          "type": "MONTHLY",
          "daysOfMonth": [31]
        }
      },
      "platformFeeVatPayer": "PARTNER",
      "isHidden": false,
      "appliedAt": "2023-08-11T11:18:52.944447Z"
    },
    "payment": {
      "type": "EXTERNAL",
      "id": "payment_1",
      "orderName": "테스트 주문",
      "currency": "KRW",
      "method": {
        "type": "CARD"
      },
      "paidAt": "2023-08-11T08:21:01.241Z"
    },
    "settlementStartDate": "2023-08-12",
    "orderLines": [],
    "additionalFees": [],
    "discounts": [],
    "cancellation": {
      "id": "cancellation_1",
      "cancelledAt": "2023-08-12T11:57:15.292Z"
    }
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
400	PlatformCancelOrderDetailMismatchedError
400	PlatformCancelProductQuantityExceededError
400	PlatformCancellableAmountExceededError
400	PlatformCancellableDiscountAmountExceededError
400	PlatformProductIdDuplicatedError
400	PlatformDiscountSharePolicyIdDuplicatedError
400	PlatformDiscountAmountOverflowError
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformTransferNotFoundError
404	PlatformCancellationNotFoundError
404	PlatformProductIdNotFoundError
404	PlatformPaymentNotFoundError
404	PlatformTransferDiscountSharePolicyNotFoundError
409	PlatformTransferAlreadyExistsError
409	PlatformOrderTransferAlreadyCancelledError

수동 정산건 생성

POST https://api.portone.io/platform/transfers/manual

수동 정산건이란 결제를 기반으로 하지않고 고객이 원하는 만큼 파트너에게 정산금을 추가 및 차감할 수 있는 api입니다.

Parameters

partnerId string required

해당 수동 정산건이 적용될 파트너의 고유 아이디

settlementAmount int required

해당 수동 정산건으로 적용하길 원하는 금액. 음수 및 양수 둘다 가능하다.

settlementDate string required

'yyyy-mm-dd' 형식으로 보내주시면 됩니다. 해당 수동 정산건이 적용되길 원하는 정산일. 꼭 정확한 정산일을 전달하셔야 합니다.

memo string optional

해당 수동 정산건 등록시 내부 관리를 위해 전달하는 메모. 50자 까지 가능하다다

isForTest boolean optional 기본값은 false

Request Body

Example Value
Schema
{
  "partnerId": "string",
  "memo": "string",
  "settlementAmount": 0,
  "settlementDate": "string",
  "isForTest": true
}

Response

수동 정산객체가 반환된다.

{
  "transfer": {
    "type": "MANUAL",
    "id": "01H7W8JQF61EXTRYWCT667CYK2",
    "graphqlId": "NjowMUg3VzhKUUY2MUVYVFJZV0NUNjY3Q1lLMg==",
    "partner": {
      "id": "partnerA",
      "graphqlId": "NDpwYXJ0bmVyQQ==",
      "name": "파이썬 강사",
      "email": "kjnkyj12@gmail.com",
      "businessRegistrationNumber": "1178178260",
      "account": {
        "bank": "SHINHAN",
        "currency": "KRW",
        "number": "10358907249",
        "holder": "김준일",
        "status": "VERIFIED"
      },
      "status": "APPROVED",
      "defaultContractId": "contractA",
      "memo": "잭슨 테스트 예시문",
      "tags": ["파이썬"],
      "isHidden": false,
      "appliedAt": "2023-08-11T11:19:58.829787Z"
    },
    "status": "IN_PROCESS",
    "memo": "테스트 수동 정산",
    "settlementDate": "2023-09-27",
    "settlementCurrency": "KRW",
    "isForTest": false,
    "settlementAmount": 100000
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
400	PlatformUnavailableSettlementDateError: 사용할 수 없는 정산일이 요청된 경우. 요청한 정산일에 이체되지 않은 주문 정산 건이 없을 때 발생합니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformPartnerNotFoundError

정산 조회

GET https://api.portone.io/platform/transfers/{id}

등록된 정산객체를 조회합니다.

Parameters

Request Body 는 없습니다.

Request

curl -X GET https://api.portone.com/v2/platform/transfers/{id} \
     -h {Authorization: Bearer {access_token}}

Response

정산정보가 반환됩니다.

{
  "transfer": {
    "type": "ORDER",
    "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2",
    "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==",
    "partner": {
      "id": "partner_2",
      "graphqlId": "NDpwYXJ0bmVyXzI=",
      "name": "파이썬 강사",
      "email": "kjnkyj12@gmail.com",
      "businessRegistrationNumber": "1178178260",
      "account": {
        "bank": "SHINHAN",
        "currency": "KRW",
        "number": "10358907249",
        "holder": "김준일",
        "status": "VERIFIED"
      },
      "status": "APPROVED",
      "defaultContractId": "contract_2",
      "memo": "잭슨 테스트",
      "tags": ["파이썬"],
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:25.645014Z"
    },
    "status": "IN_PROCESS",
    "memo": "testing order transfer",
    "settlementDate": "2023-08-18",
    "settlementCurrency": "KRW",
    "isForTest": true,
    "amount": {
      "settlement": 17250,
      "payment": 20000,
      "order": 25000,
      "platformFee": 2500,
      "platformFeeVat": 0,
      "additionalFee": 2500,
      "additionalFeeVat": 250,
      "discount": 5000,
      "discountShare": 2500
    },
    "contract": {
      "id": "contract_2",
      "graphqlId": "NTpjb250cmFjdF8y",
      "memo": "contract 2",
      "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
      "settlementCycle": {
        "lagDays": 2,
        "datePolicy": "CALENDAR_DAY",
        "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
      },
      "platformFeeVatPayer": "MERCHANT",
      "isHidden": false,
      "appliedAt": "2023-08-09T07:39:17.207733Z"
    },
    "payment": {
      "type": "EXTERNAL",
      "id": "payment_1",
      "orderName": "테스트 주문",
      "currency": "KRW",
      "method": { "type": "CARD" },
      "paidAt": "2023-08-11T08:21:01.241Z"
    },
    "settlementStartDate": "2023-08-11",
    "orderLines": [
      {
        "product": { "id": "1", "name": "product_1", "amount": 5000 },
        "quantity": 5,
        "discounts": [
          {
            "sharePolicy": {
              "id": "discount_1",
              "graphqlId": "MjpkaXNjb3VudF8x",
              "partnerShareRate": 500000000,
              "memo": "테스트 할인",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:45:45.799176Z"
            },
            "amount": 2500,
            "shareAmount": 1250
          }
        ],
        "additionalFees": [
          {
            "policy": {
              "id": "addtional_fee_1",
              "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
              "fee": { "type": "FIXED_RATE", "rate": 5000 },
              "memo": "테스트 추가수수료",
              "vatPayer": "PARTNER",
              "isHidden": false,
              "appliedAt": "2023-08-09T07:41:12.393974Z"
            },
            "amount": 1250,
            "vat": 125
          }
        ],
        "amount": {
          "settlement": 19875,
          "payment": 22500,
          "order": 25000,
          "platformFee": 2500,
          "platformFeeVat": 0,
          "additionalFee": 1250,
          "additionalFeeVat": 125,
          "discount": 2500,
          "discountShare": 1250
        }
      }
    ],
    "additionalFees": [
      {
        "policy": {
          "id": "addtional_fee_1",
          "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
          "fee": { "type": "FIXED_RATE", "rate": 5000 },
          "memo": "테스트 추가수수료",
          "vatPayer": "PARTNER",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:41:12.393974Z"
        },
        "amount": 1250,
        "vat": 125
      }
    ],
    "discounts": [
      {
        "sharePolicy": {
          "id": "discount_1",
          "graphqlId": "MjpkaXNjb3VudF8x",
          "partnerShareRate": 500000000,
          "memo": "테스트 할인",
          "isHidden": false,
          "appliedAt": "2023-08-09T07:45:45.799176Z"
        },
        "amount": 2500,
        "shareAmount": 1250
      }
    ]
  }
}

계약

계약 객체는 가맹점이 파트너에게 정산해줄 대금과 정산일을 계산하는데 적용되는 정보입니다.

가맹점의 플랫폼에서 재화 및 서비스를 판매하는데에 대한 중개수수료정보와 판매금에 대한 정산을 언제 해주는지 알려주는 정산일로 구성되어 있습니다.

Endpoints

POST /platform/contracts
GET /platform/contract/{id}
PATCH /platform/contract/{id}
POST /platform/contracts/numered-pages
POST /platform/contracts/{id}/schedule
PUT /platform/contracts/{id}/schedule
GET /platform/contracts/{id}/schedule
DELETE /platform/contracts/{id}/schedule
GET /platform/contract-filter-options

계약 객체

Attributes

id string

계약객체의 고유 아이디

graphqlId string

계약객체의 고유 아이디 (포트원 내부 graphql버전)

memo string

계약객체 내부 표기를 위한 메모

platformFee dictionary

중개수수료. 기본 Fee attribute 을 사용한다.

one of logic 으로 정액, 정률 중 하나만 사용할 수 있다.

platformFee.amount int64

정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.

platformFee.fixedRate int64

정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력.

settlementCycle dictionary

정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다.

settlementCycle.lagDays int64

지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다.

settlementCycle.datePolicy enum

기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. 값: CALENDAR_DAY, HOLIDAY_BEFORE, HOLIDAY_AFTER

CALENDAR_DAY 달력일. 정산일 계산시 공휴일을 고려하지 않습니다.

HOLIDAY_BEFORE 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다.

HOLIDAY_AFTER 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다.

settlementCycle.method dictionary

정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다.

계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다.

method.type enum

정산 주기의 종류를 나타냅니다. 값으론 daily, weekly, monthly, manualDates 가 있습니다.

값	설명

method.daily json dicionary

정산 주기가 매일일때 단순히 빈 json ’’ 을 입력하면 됩니다.

혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다.

method.weekly dicionary

weekly attribute

weekly.dayOfWeek enum

정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. i.e. [‘MON’, ‘WED’] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다.

요일 enum

MON 월요일

TUE 화요일

WED 수요일

THU 목요일

FRI 금요일

SAT 토요일

SUN 일요일

method.monthly dictionary

monthly attribute

monthly.dayOfMonth list of int64

정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. i.e. [1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다.

31 의 경우에는 월말로 지정됩니다.

두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

method.manualDates dicionary

manualDates attribute

manualDates.dates

정산 주기가 특정 분기 혹은 지정된 날짜(‘MM-DD’)일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다.

dates attribute

dates.month int64

달로써 1-12 사이의 값을 가집니다.

dates.day int64

일로써 1-31 사이의 값을 가집니다.

만약에 없는 일을 지정할 경우 에러를 반환합니다.

여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

정산주기 값 설정 예시

settlementCycle = {
  lay_days: 3,
  method: {
    monthly: {
      dayOfMonth: [15, 31],
    },
  },
  datePolicy: "HOLIDAY_BEFORE",
};

case 1: 10일 주문완료 (settlementStartDate)

d + 3일 = 13일
13일의 그다음 정산일 = 15일
if 15일이 영업일이라면 정산일 = 15일
elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일

case 2: 13일 주문완료

d + 3일 = 16일
16일의 그다음 정산일 = 31일
if 31일이 영업일이라면 정산일 = 31일
elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일

platformFeeVatPayer enum

해당 계약의 중개수수료에 대해서 부가세 포함 여부. 값: PARTNER, MERCHANT

PARTNER: 부가세 파트너 부담

MERCHANT: 부가세 파트너 미부담

isHidden boolean

계약 객체 숨기처리 여부. 숨김 처리는 soft delete이라고 생각하시면 됩니다.

appliedAt Datetime

계약 객체가 업데이트 된 시점.

Response (월별 정산)

{
  "id": "contract_2",
  "graphqlId": "NTpjb250cmFjdF8y",
  "memo": "contract 2",
  "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
  "settlementCycle": {
    "lagDays": 2,
    "datePolicy": "CALENDAR_DAY",
    "method": { "type": "MONTHLY", "daysOfmonth": [31] }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:39:17.207733Z"
}

Response (일별 정산)

{
  "id": "contract_2",
  "graphqlId": "NTpjb250cmFjdF8y",
  "memo": "contract 2",
  "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
  "settlementCycle": {
    "lagDays": 2,
    "datePolicy": "CALENDAR_DAY",
    "method": { "type": "DAILY", "daily": {} }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:39:17.207733Z"
}

Response (주별 정산)

{
  "id": "contract_2",
  "graphqlId": "NTpjb250cmFjdF8y",
  "memo": "contract 2",
  "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
  "settlementCycle": {
    "lagDays": 2,
    "datePolicy": "CALENDAR_DAY",
    "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:39:17.207733Z"
}

Response (월-일 정산)

{"id": "contract_2",
 "graphqlId": "NTpjb250cmFjdF8y",
 "memo": "contract 2",
 "platformFee": {"type": "FIXED_RATE", "rate": 10000},
 "settlementCycle": {"lagDays": 2,
  "datePolicy": "CALENDAR_DAY",
  "method": {"type": "MANUALDATES", "dates": ["month": 1, "day": 1]}},
 "platformFeeVatPayer": "MERCHANT",
 "isHidden": false,
 "appliedAt": "2023-08-09T07:39:17.207733Z"}

계약 생성

POST https://api.portone.io/platform/contracts

새로운 계약을 생성합니다.

Parameters

id optional string

계약객체에 부여하는 고유 아이디. 전달하지 않을경우 response에서 포트원이 임의로 발급해 드립니다.

memo optional string

계약객체 내부 표기를 위한 메모

platformFee required dictionary

중개수수료. 기본 Fee attribute 을 사용한다.

Amount (정액 수수료) 혹은 dRate (정률 수수료) 둘 중 하나만 전달 하셔야 합니다.

platformFee.Amount int64

정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.

platformFee.Rate int64

정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력.

settlementCycle required dictionary

정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다.

settlementCycle.lagDays int64

지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다.

settlementCycle.datePolicy enum

CALENDAR_DAY 달력일. 정산일 계산시 공휴일을 고려하지 않습니다.

HOLIDAY_BEFORE 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다.

HOLIDAY_AFTER 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다.

settlementCycle.method dictionary

계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다.

method.daily json dicionary

정산 주기가 매일일때 단순히 빈 json ’’ 을 입력하면 됩니다.

혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다.

method.weekly dicionary

weekly attribute

weekly.daysOfWeek enum

요일 enum

MON 월요일

TUE 화요일

WED 수요일

THU 목요일

FRI 금요일

SAT 토요일

SUN 일요일

method.monthly dictionary

monthly attribute

monthly.daysOfMonth list of int64

31 의 경우에는 월말로 지정됩니다.

두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

method.manualDates dicionary

manualDates attribute

manualDates.dates

정산 주기가 특정 분기 혹은 지정된 날짜(‘MM-DD’)일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다.

dates attribute

dates.month int64

달로써 1-12 사이의 값을 가집니다.

dates.day int64

일로써 1-31 사이의 값을 가집니다.

만약에 없는 일을 지정할 경우 에러를 반환합니다.

여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

정산주기 값 설정 예시

settlementCycle = {
  lay_days: 3,
  method: {
    monthly: {
      daysOfMonth: [15, 31],
    },
  },
  datePolicy: "HOLIDAY_BEFORE",
};

case 1: 10일 주문완료 (settlementStartDate)

d + 3일 = 13일
13일의 그다음 정산일 = 15일
if 15일이 영업일이라면 정산일 = 15일
elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일

case 2: 13일 주문완료

d + 3일 = 16일
16일의 그다음 정산일 = 31일
if 31일이 영업일이라면 정산일 = 31일
elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일

platformFeeVatPayer optional

부가세 여부

PARTNER: 부가세 파트너 부담

MERCHANT: 부가세 파트너 미부담

Request Example

one of logic 을 다 담았습니다.

{
  "id": "string",
  "memo": "string",
  "platformFee": {
    "fixedRate": 0,
    "fixedAmount": 0
  },
  "settlementCycle": {
    "lagDays": 0,
    "datePolicy": "CALENDAR_DAY",
    "method": {
      "daily": {},
      "weekly": {
        "daysOfWeek": ["FRI"]
      },
      "monthly": {
        "daysOfMonth": [0]
      },
      "manualDates": {
        "dates": [
          {
            "month": 0,
            "day": 0
          }
        ]
      }
    }
  },
  "platformFeeVatPayer": "MERCHANT"
}

Response

생성된 계약 객체가 반환됩니다.

{
  "id": "contract_2",
  "graphqlId": "NTpjb250cmFjdF8y",
  "memo": "contract 2",
  "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
  "settlementCycle": {
    "lagDays": 2,
    "datePolicy": "CALENDAR_DAY",
    "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:39:17.207733Z"
}

계약 조회

GET https://api.portone.io/platform/contracts{id}

Parameters

None

Request

curl https://api.portone.com/v2/platform/contract/{id}\
     -h {'Bearer Token {YOUR TOKEN}'} \

Response

조회한 아이디의 계약객체가 반환됩니다.

{
  "contract": {
    "id": "BBG4AY9P95",
    "graphqlId": "NTpCQkc0QVk5UDk1",
    "memo": "contract A",
    "platformFee": {
      "type": "FIXED_RATE",
      "rate": 10000
    },
    "settlementCycle": {
      "lagDays": 2,
      "datePolicy": "HOLIDAY_AFTER",
      "method": {
        "type": "DAILY"
      }
    },
    "platformFeeVatPayer": "PARTNER",
    "isHidden": false,
    "appliedAt": "2023-08-15T14:31:23.586857Z"
  }
}

계약 수정

PATCH https://api.portone.io/platform/contracts/{id}

주어진 아이디에 대응되는 계약을 업데이트합니다.

해당 api는 호출 시점에 변경사항을 적용합니다. 변경사항을 미래 시점에 적용하고 싶다면 POST /v2/platform/contracts/{id}/schedule api를 사용하세요.

계약을 업데이트 하면 api 호출 시점 이후의 settlementStartDate를 가진 해당 계약의 정산에 변경사항이 적용됩니다.

Parameters

id required string (url path)

업데이트 하고자 하는 계약의 아이디

memo optional string

계약객체 내부 표기를 위한 메모

platformFee required dictionary

중개수수료. 기본 Fee attribute 을 사용한다.

Amount (정액 수수료) 혹은 Rate (정률 수수료) 둘 중 하나만 전달 하셔야 합니다.

platformFee.Amount int64

정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.

platformFee.Rate int64

정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력.

settlementCycle required dictionary

정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다.

settlementCycle.lagDays int64

지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다.

settlementCycle.datePolicy enum

CALENDAR_DAY 달력일. 정산일 계산시 공휴일을 고려하지 않습니다.

HOLIDAY_BEFORE 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다.

HOLIDAY_AFTER 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다.

settlementCycle.method dictionary

계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다.

method.daily json dicionary

정산 주기가 매일일때 단순히 빈 json ’’ 을 입력하면 됩니다.

혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다.

method.weekly dicionary

weekly attribute

weekly.daysOfWeek enum

요일 enum

MON 월요일

TUE 화요일

WED 수요일

THU 목요일

FRI 금요일

SAT 토요일

SUN 일요일

method.monthly dictionary

monthly attribute

monthly.daysOfMonth list of int64

31 의 경우에는 월말로 지정됩니다.

두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

method.manualDates dicionary

manualDates attribute

manualDates.dates

정산 주기가 특정 분기 혹은 지정된 날짜(‘MM-DD’)일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다.

dates attribute

dates.month int64

달로써 1-12 사이의 값을 가집니다.

dates.day int64

일로써 1-31 사이의 값을 가집니다.

만약에 없는 일을 지정할 경우 에러를 반환합니다.

여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다.

platformVatPayer optional enum

부가세 여부

PARTNER: 부가세 파트너 부담

MERCHANT: 부가세 파트너 미부담

isHidden optional boolean

계약 숨김 여부. 기본 값은 false 입니다.

Request Example

{
  "memo": "string",
  "platformFee": {
    "fixedRate": 0,
    "fixedAmount": 0
  },
  "settlementCycle": {
    "lagDays": 0,
    "datePolicy": "CALENDAR_DAY",
    "method": {
      "daily": {},
      "weekly": {
        "daysOfWeek": ["FRI"]
      },
      "monthly": {
        "daysOfMonth": [0]
      },
      "manualDates": {
        "dates": [
          {
            "month": 0,
            "day": 0
          }
        ]
      }
    }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": true
}

Response

{
  "id": "contract_2",
  "graphqlId": "NTpjb250cmFjdF8y",
  "memo": "contract 2",
  "platformFee": { "type": "FIXED_RATE", "rate": 10000 },
  "settlementCycle": {
    "lagDays": 2,
    "datePolicy": "CALENDAR_DAY",
    "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] }
  },
  "platformFeeVatPayer": "MERCHANT",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:39:17.207733Z"
}

계약 다건 조회 (TBU)

GET https://api.portone.io/platform/contracts

페이지 기반으로 여러 계약을 조회합니다.

page optional

요청할 페이지 정보

페이지 번호를 통한 다건 조회 API에 필요한 입력 정보

page.size integer required 각 페이지 당 포함할 객체 수. 기본값은 10

page.number integer required 페이지 번호. 0 부터 시작합니다.

filter dictionary

다건 조회시 적용하고 싶은 필터 값.

filter.includeHidden boolean optional

true일 경우 숨김 처리된 파트너가 조회됩니다.

기본값은 false입니다.

filter.tags list of string optional 파트너에게 부여한 태그 리스트 값.

filter.keyword one of dictionary 검색 조건. 조건중 한 값을 지정하여 %like% 검색한다.

Request

curl -X DELETE https://api.portone.com/v2/platform/contract/{id}/numbered-pages \
     -u {api_key}

Response

request로 전달된 검색조건에 대응하는 여러 계약들이 반환됩니다.

{
  "items": [
    {
      "id": "contract_1",
      "memo": "셀러 기본 계약 1",
      "platformFee": {
        "rate": 100000000
      },
      "settlementCycle": {
        "lagDays": 3,
        "method": "monthly",
        "method": {
          "weekly": {
            "daysOfWeek": ["FRI"]
          }
        },
        "datePolicy": "HOLIDAY_BEFORE"
      },
      "vatPayer": "PARTNER",
      "isHidden": false,
      "appliedAt": "2021-01-01T00:00:00Z" //api 호출 시점
    } /// ...
  ],
  "page": {
    "size": 10,
    "number": 0,
    "totalCount": 10
  }
}

계약 예약 업데이트

POST https://api.portone.io/platform/contracts/{id}/schedule

주어진 아이디에 대응되는 계약에 업데이트를 예약합니다.

“update” 필드에 업데이트를 예약할 정보를 입력합니다.

“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다.

Parameter

update dictionary required

예약 업데이트 하고 싶은 계약 정보 기존 계약 수정 API와 동일한 파라미터를 사용합니다.

appliedAt Datetime required

업데이트가 적용되길 원하는 시점 입니다.다.

settlementStartDate 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다.

Request

{
  "update": {
    "memo": "string",
    "platformFee": {
      "fixedRate": 0,
      "fixedAmount": 0
    },
    "settlementCycle": {
      "lagDays": 0,
      "datePolicy": "CALENDAR_DAY",
      "method": {
        "daily": {},
        "weekly": {
          "daysOfWeek": ["FRI"]
        },
        "monthly": {
          "daysOfMonth": [0]
        },
        "manualDates": {
          "dates": [
            {
              "month": 0,
              "day": 0
            }
          ]
        }
      }
    },
    "platformFeeVatPayer": "MERCHANT",
    "isHidden": true
  },
  "appliedAt": "2023-08-15T15:06:48.520Z"
}

Response

{
  "scheduledContract": {
    "id": "contract_1",
    "graphqlId": "aslkdflkdmvl==",
    "memo": "셀러 기본 계약 1",
    "platformFee": {
      "rate": 100000000
    },
    "settlementCycle": {
      "lagDays": 2,
      "method": "weekly",
      "method": {
        "weekly": {
          "daysOfWeek": ["FRI"]
        }
      },
      "datePolicy": "HOLIDAY_BEFORE"
    },
    "platformVatPayer": "PARTNER",
    "isHidden": false,
    "appliedAt": "2023-05-01T00:00:00Z" //예약 시점
  }
}

계약 예약 업데이트 재설정

PUT https://api.portone.io/platform/contracts/{id}/schedule

주어진 아이디에 대응되는 계약에 예약 업데이트를 재설정합니다.

“update” 필드에 업데이트를 예약할 정보를 입력합니다.

“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다.

해당 계약 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다.

Parameter

update dictionary required

예약 업데이트 하고 싶은 계약 정보 기존 계약 수정 API와 동일한 파라미터를 사용합니다.

appliedAt Datetime required

업데이트가 적용되길 원하는 시점 입니다.다.

settlementStartDate 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다.

Response

{
  "scheduledContract": {
    "id": "contract_1",
    "memo": "셀러 기본 계약 1",
    "platformFee": {
      "rate": 10000
    },
    "settlementCycle": {
      "lagDays": 2,
      "method": "weekly",
      "method": {
        "weekly": {
          "daysOfWeek": ["MON"]
        }
      },
      "datePolicy": "HOLIDAY_BEFORE"
    },
    "platformVatPayer": "PARTNER",
    "isHidden": false,
    "appliedAt": "2023-06-01T00:00:00Z" //예약 시점
  }
}

계약 예약 업데이트 조회

GET https://api.portone.io/platform/contracts/{id}/schedule

주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다

Parameter

id required string (url path)

예약 업데이트를 조회할 계약의 아이디

Response

{
  "scheduledContract": {
    "id": "contract_1",
    "memo": "셀러 기본 계약 1",
    "platformFee": {
      "rate": 10000
    },
    "settlementCycle": {
      "lagDays": 2,
      "method": "weekly",
      "method": {
        "weekly": {
          "daysOfWeek": ["MON"]
        }
      },
      "datePolicy": "HOLIDAY_BEFORE"
    },
    "platformFeeVatPayer": "PARTNER",
    "isHidden": false,
    "appliedAt": "2023-06-01T00:00:00Z" //예약 시점
  }
}

계약 예약 업데이트 삭제

DELETE https://api.portone.io/platform/contracts/{id}/schedule

주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다

Parameter

id required string url path

예약 업데이트를 삭제 할 계약의 아이디

Response

200 성공 응답. 삭제된 예약 업데이트는 조회되지 않습니다.

파트너

파트너 객체는 가맹점이 정산해줘야할 대상입니다.

기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다.

Endpoints

POST /platform/partners
POST /platform/partners/batch
GET /platform/partners/{id}
POST /platform/partners/{id}
POST /platform/partners/{id}/schedule
PUT /platform/partners/{id}/schedule
GET /platform/partners/{id}/schedule
DELETE /platform/partners/{id}/schedule
GET /platform/partner-filter-options
GET /platform/partners-dashbaord

파트너 객체

Attributes

id string

파트너 고유 아이디. 전달해 주시거나 발급받으실 수 있습니다.

graphqlId string

파트너 고유 아이디. 포트원 내부 용도

name string

파트너 법인명 혹은 이름.

email string

파트너 이메일

businessRegistrationNumber string

파트너 사업자번호. 개인 혹은 법인 사업자일때만 존재합니다. ’-’ 를 제외해야 합니다.

account dictionary

정산 계좌 Attribute

account.bank enum or string

은행 이름.

- currnecy가 KRW일시 증권사가 제외된 한국 은행 코드별상의 은행값 enum 하단 참고. 해당 은행값 외의 은행은 에러 처리
- currency 가 KRW가 아닐때 해외 은행 string값으로 입력 가능

account.currency enum

화페로써 현재로썬 KRW, JPY, USD만 지원한다.

account.number string

계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다.

account.holder string

예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다.

account.status enum

계좌 상태.

enum	values
VERIFYING	계좌 인증 중
VERIFIED	계좌 인증 완료됨
VERIFY_FAILED	계좌 인증 실패함
EXPIRED	계좌 인증 만료됨
UNKNOWN	알 수 없는 상태

defaultContractId string

파트너의 기본 계약 아이디

기본 계약 아이디란 파트너가 정산을 받을 때 적용되는 계약을 의미합니다. 파트너 정산시 여러개의 계약을 적용 할 수 있으나, 정산 API에 파트너 아이디만 전달 할 경우 기본 계약이 적용됩니다.

memo string

파트너 메모. 내부 구분용으로 사용하실 수 있습니다.

tags list of string

파트너 태그. 내부 구분용으로 사용하실 수 있습니다.

isHidden boolean

파트너 숨김 여부. true일 경우 파트너 목록에서 숨김 처리됩니다.

숨김이란 soft delete이라고 생각하시면 됩니다.

appliedAt Datetime

해당 파트너가 업데이트 된 시각

Response

{
  "partner": {
    "id": "partnerA",
    "graphqlId": "NDpwYXJ0bmVyQQ==",
    "name": "파이썬 강사",
    "email": "kjnkyj12@gmail.com",
    "businessRegistrationNumber": "1178178260",
    "account": {
      "bank": "SHINHAN",
      "currency": "KRW",
      "number": "10358907249",
      "holder": "김준일",
      "status": "VERIFIED"
    },
    "status": "APPROVED",
    "defaultContractId": "contractA",
    "memo": "잭슨 테스트 예시문",
    "tags": ["파이썬"],
    "isHidden": false,
    "appliedAt": "2023-08-11T11:19:58.829787Z"
  }
}

파트너 생성

POST https://api.portone.io/platform/partners

Parameters

id optional

파트너에 부여하는 고유 아이디. 가맹점 서버에 등록된 파트너지칭 아이디와 동일해야 합니다. 따로 없다면 포트원이 발급해 드립니다.

name string required

파트너를 지칭하는 사업자명 및 이름

email string required

파트너 이메일

businessRegistrationNumber string optional

파트너 사업자번호. 검증하지는 않음. 번호 기호 둘다 가능

account dictionary requried

정산 계좌 Attribute

account.bank enum or string required

은행 이름.

account.currency enum required

화페로써 현재로썬 KRW, JPY, USD만 지원한다.

account.number string required

계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다.

account.holder string required

예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다.

defaultContractId string required

이미 존재하는 계약객체의 아이디를 등록해야합니다.

memo string optional

256자까지 가능합니다.

tag list of string optional

최대 10개까지 가능합니다.

Request

{
  "id": "string",
  "name": "string",
  "email": "string",
  "businessRegistrationNumber": "string",
  "account": {
    "bank": "BNP",
    "currency": "AED",
    "number": "string",
    "holder": "string"
  },
  "defaultContractId": "string",
  "memo": "string",
  "tags": ["string"]
}

Response

파트너 객체가 반환됩니다.

{
  "partner": {
    "id": "partnerA",
    "graphqlId": "NDpwYXJ0bmVyQQ==",
    "name": "파이썬 강사",
    "email": "kjnkyj12@gmail.com",
    "businessRegistrationNumber": "1178178260",
    "account": {
      "bank": "SHINHAN",
      "currency": "KRW",
      "number": "10358907249",
      "holder": "김준일",
      "status": "VERIFIED"
    },
    "status": "APPROVED",
    "defaultContractId": "contractA",
    "memo": "잭슨 테스트 예시문",
    "tags": ["파이썬"],
    "isHidden": false,
    "appliedAt": "2023-08-11T11:19:58.829787Z"
  }
}

파트너 조회

GET https://api.portone.io/platform/partners/{id}

Parameters

id required (url path)

조회하고 싶은 파트너 고유 아이디

Response

파트너 객체가 반환됩니다.

{
  "partner": {
    "id": "partnerA",
    "graphqlId": "NDpwYXJ0bmVyQQ==",
    "name": "파이썬 강사",
    "email": "kjnkyj12@gmail.com",
    "businessRegistrationNumber": "1178178260",
    "account": {
      "bank": "SHINHAN",
      "currency": "KRW",
      "number": "10358907249",
      "holder": "김준일",
      "status": "VERIFIED"
    },
    "status": "APPROVED",
    "defaultContractId": "contractA",
    "memo": "잭슨 테스트 예시문",
    "tags": ["파이썬"],
    "isHidden": false,
    "appliedAt": "2023-08-11T11:19:58.829787Z"
  }
}

파트너 다건 조회

GET https://api.portone.io/platform/partners

페이지 기반으로 여러 파트너를 조회합니다.

Parameters

page optional

요청할 페이지 정보

페이지 번호를 통한 다건 조회 API에 필요한 입력 정보

page.size integer required 각 페이지 당 포함할 객체 수. 기본값은 10

page.number integer required 페이지 번호. 0 부터 시작합니다.

filter dictionary

다건 조회시 적용하고 싶은 필터 값.

filter.includeHidden boolean optional

true일 경우 숨김 처리된 파트너가 조회됩니다.

기본값은 false입니다.

filter.tags list of string optional 파트너에게 부여한 태그 리스트 값.

filter.keyword one of dictionary 검색 조건. 조건중 한 값을 지정하여 %like% 검색한다.

- keyword.id 파트너 아이디
- keyword.name 파트너 이름
- keyword.email 파트너 이메일
- keyword.businessRegistrationNumber 파트너 사업자 번호
- keyword.defaultContractId 파트너 기본 계약 아이디
- keyword.memo 파트너 메모
- keyword.accountBank 파트너 계좌 은행
- keyword.accountCurrency 파트너 계좌 통화
- keyword.accountNumber 파트너 계좌 번호
- keyword.accountHolder 파트너 계좌 예금주

filter.banks list of string

파트너 계좌 은행 리스트 값.

filter.accountCurrencies list of enum

파트너 계좌 통화 리스트 값. KRW, USD, JPY

Request

{
  "page": {
    "number": 0,
    "size": 0
  },
  "filter": {
    "includeHidden": true,
    "tags": ["string"],
    "banks": ["BNP"],
    "accountCurrencies": ["AED"],
    "keyword": {
      "id": "string",
      "name": "string",
      "email": "string",
      "businessRegistrationNumber": "string",
      "defaultContractId": "string",
      "memo": "string",
      "accountNumber": "string",
      "accountHolder": "string"
    }
  }
}

Response

여러 파트너 객체들이 리스트 형태로 반환됩니다.

{
  "items": [
    {
      "id": "string",
      "graphqlId": "string",
      "name": "string",
      "email": "string",
      "businessRegistrationNumber": "string",
      "account": {
        "bank": "BNP",
        "currency": "AED",
        "number": "string",
        "holder": "string",
        "status": "EXPIRED"
      },
      "status": "APPROVED",
      "defaultContractId": "string",
      "memo": "string",
      "tags": ["string"],
      "isHidden": true,
      "appliedAt": "2023-08-15T16:06:03.321Z"
    }
  ],
  "page": {
    "number": 0,
    "size": 0,
    "totalCount": 0
  }
}

파트너 수정

PATCH https://api.portone.io/platform/partners/{id}

주어진 아이디에 대응하는 파트너 정보를 업데이트 합니다.

Parameters

id 를 제외한 모든 값을 수정할 수 있습니다. 파트너 생성 API의 파라미터와 동일합니다.

Request

{
  "name": "string",
  "email": "string",
  "businessRegistrationNumber": "string",
  "account": {
    "bank": "BNP",
    "currency": "AED",
    "number": "string",
    "holder": "string"
  },
  "defaultContractId": "string",
  "memo": "string",
  "tags": ["string"],
  "isHidden": true
}

Response

업데이트 된 파트너 객체가 반환됩니다.

{
  "partner": {
    "id": "partnerA",
    "graphqlId": "NDpwYXJ0bmVyQQ==",
    "name": "파이썬 강사",
    "email": "kjnkyj12@gmail.com",
    "businessRegistrationNumber": "1178178260",
    "account": {
      "bank": "SHINHAN",
      "currency": "KRW",
      "number": "10358907249",
      "holder": "김준일",
      "status": "VERIFIED"
    },
    "status": "APPROVED",
    "defaultContractId": "contractA",
    "memo": "잭슨 테스트 예시문",
    "tags": ["파이썬"],
    "isHidden": false,
    "appliedAt": "2023-08-11T11:19:58.829787Z"
  }
}

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

파트너 예약 업데이트

POST https://api.portone.io/platform/partners/{id}/schedule

주어진 아이디에 대응하는 파트너의 업데이트를 예약합니다.

Parameters

id required string url path

파트너 아이디.

update required json dicionary

업데이트 할 파트너의 정보를 담은 json dictionary 파트너 생성 API의 파라미터와 동일합니다.

appliedAt required Datetime

업데이트를 적용할 시간. 정산 시작일(settlementStartDate) 기준으로 시간이 적용됩니다. 예를들어 2일에 파트너 기본계약 업데이트를 예약했으면 1일까지 정산시작일이 되어있는 해당 파트너의 정산 건은 구버전의 계약이 적용되고 2일부터는 새로운 계약이 적용됩니다.

Request

{
  "update": {
    "name": "string",
    "email": "string",
    "businessRegistrationNumber": "string",
    "account": {
      "bank": "BNP",
      "currency": "AED",
      "number": "string",
      "holder": "string"
    },
    "defaultContractId": "string",
    "memo": "string",
    "tags": ["string"],
    "isHidden": true
  },
  "appliedAt": "2023-08-15T16:20:15.312Z"
}

Response

성공 응답으로 예약된 파트너 객체가 반환됩니다.

{
  "scheduledPartner": {
    "id": "string",
    "graphqlId": "string",
    "name": "string",
    "email": "string",
    "businessRegistrationNumber": "string",
    "account": {
      "bank": "BNP",
      "currency": "AED",
      "number": "string",
      "holder": "string",
      "status": "EXPIRED"
    },
    "status": "APPROVED",
    "defaultContractId": "string",
    "memo": "string",
    "tags": ["string"],
    "isHidden": true,
    "appliedAt": "2023-08-15T16:20:15.397Z"
  }
}

파트너 예약 업데이트 재설정

PUT https://api.portone.io/platform/partners/{id}/schedule

주어진 아이디에 대응하는 파트너의 업데이트를 재설정 합니다. 기존에 예약이 예정되어 있는 업데이트가 있다면 취소되고 새로운 업데이트가 예약됩니다.

Parameters

id required string

파트너 아이디.

update required json dicionary

업데이트 할 파트너의 정보를 담은 json dictionary 파트너 생성 API의 파라미터와 동일합니다.

appliedAt required Datetime

Request

{
  "update": {
    "name": "string",
    "email": "string",
    "businessRegistrationNumber": "string",
    "account": {
      "bank": "BNP",
      "currency": "AED",
      "number": "string",
      "holder": "string"
    },
    "defaultContractId": "string",
    "memo": "string",
    "tags": ["string"],
    "isHidden": true
  },
  "appliedAt": "2023-08-15T16:23:15.265Z"
}

Response

성공 응답으로 예약된 파트너 객체가 반환됩니다.

{
  "scheduledPartner": {
    "id": "string",
    "graphqlId": "string",
    "name": "string",
    "email": "string",
    "businessRegistrationNumber": "string",
    "account": {
      "bank": "BNP",
      "currency": "AED",
      "number": "string",
      "holder": "string",
      "status": "EXPIRED"
    },
    "status": "APPROVED",
    "defaultContractId": "string",
    "memo": "string",
    "tags": ["string"],
    "isHidden": true,
    "appliedAt": "2023-08-15T16:23:15.340Z"
  }
}

파트너 예약 업데이트 취소

DELETE https://api.portone.io/platform/partners/{id}/schedule

주어진 아이디에 대응하는 파트너의 업데이트를 취소합니다.

Parameters

id required string

파트너 아이디.

Response 성공 응답(200) 이 반환됩니다.

은행 Enum Values

enum	values
BOK	한국은행
KDB	산업은행
IBK	기업은행
KB	국민은행
SUHYUP	수협은행
EIB	수출입은행
NH	NH농협은행
REGIONAL_NH	지역농축협
WOORI	우리은행
SCB	SC제일은행
CITI	한국씨티은행
DAEGU	대구은행
BUSAN	부산은행
GWANGJU	광주은행
JEJU	제주은행
JEONBUK	전북은행
GYEONGNAM	경남은행
KFCC	새마을금고
CREDIT_UNION	신협
FSB	저축은행
MISC	기타 외국계은행(중국 농업은행 등)
MORGAN_STANLEY	모간스탠리은행
HSBC	HSBC은행
DEUTSCHE	도이치은행
JPMC	제이피모간체이스은행
MIZUHO	미즈호은행
MUFG	엠유에프지은행
BOA	BOA은행
BNP	비엔피파리바은행
NFCF	산림조합중앙회
EPOST	우체국
HANA	하나은행
SHINHAN	신한은행
KBANK	케이뱅크
KAKAO	카카오뱅크
TOSS_BANK	토스뱅크
DAISHIN_SB	대신저축은행
SBI_SB	에스비아이저축은행
HK_SB	에이치케이저축은행
WELCOME_SB	웰컴저축은행
SHINHAN_SB	신한저축은행

할인 정책

할인 정책 객체는 가맹점의 주문건에 대해서 쿠폰 및 포인트와 같은 할인금액이 적용될시 이에대해서 파트너 정산에 할인금과 할인에 따른 파트너와의 분담율을 적용하고자 사용할 수 있는 객체입니다.

할인 정책에 대한 아이디와 메모 그리고 파트너 분담율로 정보 구성이 되어있습니다.

현재 구조로는 할인금액 전달할시 꼭 해당 할인에 대한 할인 정책 아이디를 동반해서 전달해주셔야 합니다.

Endpoints

POST /platform/discount-share-policies
GET /platform/discount-share-policies/{id}
GET /platform/discount-share-policies
PATCH /platform/discount-share/{id}
POST /platform/discount-share/{id}/schedule
GET /platform/discount-share/{id}/schedule
PUT /platform/discount-share/{id}/schedule
DELETE /platform/discount-share/{id}/schedule
GET /platform/discount-share-policy-filter-options (To Be Documented)

할인 정책 생성

POST https://api.portone.io/platform/discount-share-policies

Parameters

id optional

할인 정책 고유아이디. 가맹점 서버에 저장되고 통용되는 아이디로 지정해주세요. 없다면 포트원에서 임의로 발급해드리며 이를 저장해주세요.

partnerShareRate required

할인 분담율. 10^-5처리 값입니다. 예) 10% = 10000

memo optional

할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰

Request

{
  "id": "string",
  "partnerShareRate": 0,
  "memo": "string"
}

Response

생성된 할인 정책 객체가 반환됩니다.

{
  "discountSharePolicy": {
    "id": "string",
    "graphqlId": "string",
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true,
    "appliedAt": "2023-08-15T16:48:24.842Z"
  }
}

할인 정책 조회

GET https://api.portone.io/platform/discount-share-policies/{id}

Parameters

id required (url path)

조회할 할인 정책 아이디

Response

조회 대상 할인 정책이 반환됩니다.

{
  "id": "string",
  "graphqlId": "string",
  "partnerShareRate": 0,
  "memo": "string",
  "isHidden": true,
  "appliedAt": "2023-08-15T16:55:36.587Z"
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError

할인 정책 다건 조회

GET https://api.portone.io/platform/discount-share-policies

Parameters

page optional

페이지 기반의 다건 조회 갯수 조건

page attributes

page.number optional 기본값은 1

검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다.

page.size optional 기본값은 10

각 page당 조회될 할인 정책 객체 갯수.

filter required

검색 조건

filter attributes

filter.includeHidden boolean optional 기본값은 false

true로 설정시 삭제된 할인 정책 객체도 조회됩니다.

filter.partnerShareRates list of int64 optional

파트너 분담율로 구성된 리스트. 해당 리스트에 포함된 분담율과 매칭되는 모든 할인 정책 객체들을 반환한다.

filter.keyword dictionary optional

통합검색을 위한 조건. 할인 정책 다건조회에 대해서는 할인유형 아이디 (id)와 메모 (memo)를 기반으로 검색 가능합니다. 검색 로직은 %like% 검색입니다.

- keyword.memo string
메모 값에 대한 검색. 해당 검색으로 진행시 id 검색을 추가할 수 없습니다.

- keyword.id string
아이디 값에 대한 검색. 해당 검색으로 진행시 메모 검색을 추가할 수 없습니다.

- keyword.all string
메모 및 아이디 값에 대한 검색. 해당 검색으로 진행시 메모 및 아이디 검색을 추가할 수 없습니다.

Request

{
  "page": {
    "number": 0,
    "size": 0
  },
  "filter": {
    "includeHidden": true,
    "partnerShareRates": [0],
    "keyword": {
      "id": "string",
      "memo": "string",
      "all": "string"
    }
  }
}

Response

{
  "items": [
    {
      "id": "string",
      "graphqlId": "string",
      "partnerShareRate": 0,
      "memo": "string",
      "isHidden": true,
      "appliedAt": "2023-08-15T17:00:00.572Z"
    }
  ],
  "page": {
    "number": 0,
    "size": 0,
    "totalCount": 0
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우

할인 정책 수정

주어진 아이디에 대응되는 할인 정책을 업데이트합니다.

PATCH https://api.portone.io/platform/discount-share-policies/{id}

Parameters

id required (url path)

할인 정책 아이디

partnerShareRate optional 기본값은 0

할인 분담율. 10^5처리 값입니다. 예) 10% = 1000

memo optional

할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰

isHidden boolean optional 기본값은 fals본

숨김 처리 여부. true로 설정시 해당 할인 정책은 숨김됩니다

Request

{
  "partnerShareRate": 0,
  "memo": "string",
  "isHidden": true
}

Response

{
  "discountSharePolicy": {
    "id": "string",
    "graphqlId": "string",
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true,
    "appliedAt": "2023-08-15T17:03:19.203Z"
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError

할인 정책 삭제

DELETE https://api.portone.io/platform/discount-share-policies/{id}

Parameters

id required (url path)

Response

200 응답이 떨어집니다.

할인 정책 예약 업데이트

POST https://api.portone.io/platform/discount-share-policies/{id}/schedule

“update” 필드에 업데이트를 예약할 정보를 입력합니다.

“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다

Parameters

id string required (url path)

할인 정책 아이디

update dictionary required

예약 업데이트 하고 싶은 할인 정책 정보

기존 할인 정책 수정 API 와 동일한 파라미터를 사용합니다.

appliedAt Datetime required

업데이트가 적용되길 원하는 시점 입니다

settlementStartDate 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다.

Request

{
  "update": {
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true
  },
  "appliedAt": "2023-08-15T17:09:36.812Z"
}

Response

{
  "scheduledDiscountSharePolicy": {
    "id": "string",
    "graphqlId": "string",
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true,
    "appliedAt": "2023-08-15T17:09:36.816Z"
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError
409	PlatformDiscountSharePolicyScheduleAlreadyExistsError

할인 정책 예약 업데이트 재설정

PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule

“update” 필드에 업데이트를 예약할 정보를 입력합니다.

“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다

해당 정책 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다.

Parameters

id string required (url path)

할인 정책 아이디

update dictionary required

예약 업데이트 하고 싶은 할인 정책 정보

기존 할인 정책 수정 API 와 동일한 파라미터를 사용합니다.

appliedAt Datetime required

업데이트가 적용되길 원하는 시점 입니다

settlementStartDate 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다.

Request

{
  "update": {
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true
  },
  "appliedAt": "2023-08-15T17:09:36.812Z"
}

Response

{
  "scheduledDiscountSharePolicy": {
    "id": "string",
    "graphqlId": "string",
    "partnerShareRate": 0,
    "memo": "string",
    "isHidden": true,
    "appliedAt": "2023-08-15T17:09:36.816Z"
  }
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError

할인 정책 예약 업데이트 조회

PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule

Parameters

id string required (url path)

할인 정책 아이디

Response

{
  "id": "string",
  "graphqlId": "string",
  "partnerShareRate": 0,
  "memo": "string",
  "isHidden": true,
  "appliedAt": "2023-08-15T17:21:52.542Z"
}

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError

할인 정책 예약 업데이트 삭제

PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule

Parameters

id string required (url path)

예약된 업데이트를 제거하고 싶은 할인 정책 아이디의

Response

200 OK

Error Code

Code	Description
400	InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.
401	UnauthorizedError: 인증 정보가 올바르지 않은 경우
403	PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우
404	PlatformDiscountSharePolicyNotFoundError

추가 수수료

추가 수수료 객체는 가맹점의 주문건에 대해서 단순 중개수수료에 더불어 추가로 부여되는 서비스에대한 수수료 입니다. 대표적인 사용 예시로 풀필먼트 수수료, 로켓배송 수수료, 마케팅채널 수수료등이 있습니다.

Endpoints

POST /platform/additional-fee-policies
GET /platform/additional-fee-policies/{id}
GET /platform/additional-fee-policies
PATCH /platform/additional-fee-policies/{id}
POST /platform/additional-fee-policies/{id}/schedule
PATCH /platform/additional-fee-policies/{id}/schedule
GET /platform/additional-fee-policies/{id}/schedule
DELETE /platform/additional-fee-policies/{id}/schedule
GET /platform/additional-fee-policy-filter-options (To Be Documented)

추가 수수료 객체

Parameter

id string

추가수수료의 고유 아이디

fee dictionary

추가 수수료 정보를 보여주는 fee attribute

fees.amount int64

정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.

fees.rate int64

정률일경우 10^-5처리 된다. 10% = 10000

memo string

추가 수수료 내부 구분을 위한 내부 메모

vatPayer enum

해당 계약의 중개수수료에 대해서 부가세 포함 여부. 값: PARTNER, MERCHANT

PARTNER: 부가세 파트너 부담

MERCHANT: 부가세 파트너 미부담

isHidden boolean

숨김처리 여부. 파트너 정산의 객체들에 대해서 삭제는 soft delete임을 참고해 주세요! 이는 삭리시 해당 삭제된 객체와 동일한 아이디를 발급할경우 새롭게 생성된 객체가 overwrite 합니다.

Response

{
  "id": "addtional_fee_1",
  "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
  "fee": {
    "type": "FIXED_RATE",
    "rate": 5000
  },
  "memo": "테스트 추가수수료",
  "vatPayer": "PARTNER",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:41:12.393974Z"
}

추가 수수료 생성

POST https://api.portone.io/platform/additional-fee-policies

Parameters

id required

추가수수료의 고유 아이디

fee required

추가 수수료 정보를 보여주는 fee attribute

fees.amount int64

정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.

fees.rate int64

정률일경우 10^-5처리 된다. 10% = 10000

memo optional

추가 수수료 내부 구분을 위한 내부 메모

vatPayer optional 기본값은 PARTNER

부가세 부담여부

PARTNER: 부가세 파트너 부담

MERCHANT: 부가세 파트너 미부담

Request

{
  "id": "string",
  "fee": {
    "fixedRate": 0,
    "fixedAmount": 0
  },
  "memo": "string",
  "vatPayer": "MERCHANT"
}

Response

추가 수수료 객체가 반환됩니다.

{
  "id": "addtional_fee_1",
  "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
  "fee": {
    "type": "FIXED_RATE",
    "rate": 5000
  },
  "memo": "테스트 추가수수료",
  "vatPayer": "PARTNER",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:41:12.393974Z"
}

추가 수수료 조회

Parameters

id required (url path)

Response

추가 수수료 객체가 반환됩니다.

{
  "id": "addtional_fee_1",
  "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
  "fee": {
    "type": "FIXED_RATE",
    "rate": 5000
  },
  "memo": "테스트 추가수수료",
  "vatPayer": "PARTNER",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:41:12.393974Z"
}

추가 수수료 다건 조회

Parameter

Parameters

page optional

페이지 기반의 다건 조회 갯수 조건

page attributes

page.number optional 기본값은 1

검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다.

page.size optional 기본값은 10

각 page당 조회될 할인 정책 객체 갯수.

filter required

검색 조건

filter attributes

filter.includeHidden boolean optional 기본값은 false

filter.ids optional

추가 수수료 객체 고유 아이디로 구성된 리스트

filter.vatPayers enum

부가세 적용 여부 검색 MERCHANT , PARTNER

Request

{
  "page": {
    "number": 0,
    "size": 0
  },
  "filter": {
    "includeHidden": true,
    "ids": ["string"],
    "vatPayers": ["MERCHANT"]
  }
}

{
  "items": [
    {
      "id": "string",
      "graphqlId": "string",
      "fee": {
        "amount": 0
      },
      "memo": "string",
      "vatPayer": "MERCHANT",
      "isHidden": true,
      "appliedAt": "2023-08-15T17:47:27.702Z"
    }
  ],
  "page": {
    "number": 0,
    "size": 0,
    "totalCount": 0
  }
}

추가 수수료 수정

PATCH https://api.portone.io/platform/additional-fee-policies

Parameters

id required (url path)

추가수수료 고유 아이디

나머지 파라미터는 추가수수료 생성 과 동일합니다.

Request

{
  "fee": {
    "fixedRate": 0,
    "fixedAmount": 0
  },
  "memo": "string",
  "vatPayer": "MERCHANT",
  "isHidden": true
}

Resposne

{
  "id": "addtional_fee_1",
  "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=",
  "fee": {
    "type": "FIXED_RATE",
    "rate": 5000
  },
  "memo": "테스트 추가수수료",
  "vatPayer": "PARTNER",
  "isHidden": false,
  "appliedAt": "2023-08-09T07:41:12.393974Z"
}

파트너 정산 설정

파트너 정산 설정 객체는 가맹점이 파트너에게 정산해줄때 적용될 기본적인 설정을 의미합니다. 정산 계산시 적용될 소수점 처리방식, 각 항목 (중개 수수료, 추가 수수료 ,할인 분담, 결제수수료 (TBA)) 에 대한 구체적 계산 수식을 설정 할 수 있으며 추가로 결제(PG)수수료 파트너 부담여부를 설정 할 수 있습니다.

파트너 정산을 사용하는 가맹점당 단일객체가 발급되며 삭제가 불가능 합니다.

Endpoints

PATCH /platform
GET /platform

파트너 정산 설정 객체

Parameter

merchantId string

포트원이 부여한 가맹점 고유 아이디

roundType enum

정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다.

OFF: 반올림
DOWN: 내림
UP: 올림

settlementFormula dicitionary

전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다. 다만 현재는 해당 값은 관리자콘솔 > 파트너 정산 > 계약관리 > 수식 에서 확인 및 수정하실 수 있으십니다.

settlementFormula.platformFee
중개수수료 수식

settlementFormula.channelFee (TBA)
결제수수료 수식

settlementFormula.discountShare
할인분담금 수식

settlementFormula.additionalFee
추가 수수료 수식

Response

파트너정산을 사용하실수 있는 가맹점은 기본으로 해당 값이 설정이 됩니다.

{
  "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda",
  "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=",
  "roundType": "DOWN",
  "settlementFormula": {
    "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액",
    "discountShare": "할인금액 * 할인분담률",
    "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액"
  }
}

파트너 정산 설정 수정

PATCH https://api.portone.io/platform

Parameter

roundType enum

정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다.

OFF: 반올림
DOWN: 내림
UP: 올림

settlementFormula dicitionary

전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다.

settlementFormula.platformFee
중개수수료 수식

settlementFormula.channelFee (TBA)
결제수수료 수식

settlementFormula.discountShare
할인분담금 수식

settlementFormula.additionalFee
추가 수수료 수식

Request

{
  "roundType": "DOWN",
  "settlementFormula": {
    "platformFee": "string",
    "discountShare": "string",
    "additionalFee": "string"
  }
}

Response

파트너정산을 사용하실수 있는 가맹점은 기본으로 해당 값이 설정이 됩니다.

{
  "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda",
  "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=",
  "roundType": "DOWN",
  "settlementFormula": {
    "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액",
    "discountShare": "할인금액 * 할인분담률",
    "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액"
  }
}

파트너 정산 설정 조회

GET https://api.portone.io/platform

Parameter

없음.가맹점의 플랫폼 정보를 조회합니다. 요청된 Authorization header 를 통해 자동으로 요청자의 가맹점을 특정합니다.

Response

파트너정산을 사용하실수 있는 가맹점은 기본으로 해당 값이 설정이 됩니다.

{
  "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda",
  "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=",
  "roundType": "DOWN",
  "settlementFormula": {
    "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액",
    "discountShare": "할인금액 * 할인분담률",
    "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액"
  }
}