bldinit Portone Rest API
The portone-rest API from bldinit — 12 operation(s) for portone-rest.
The portone-rest API from bldinit — 12 operation(s) for portone-rest.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mcpweave-com:mcpweave-com-portone-rest-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: mcpweave Portone Rest API
description: Asia-native MCP Gateway — Native pass-through, FastMCP, Paddle+Toss billing
version: '2026-04-27'
tags:
- name: portone-rest
paths:
/api/v1/portone/payments/{paymentId}:
get:
tags:
- portone-rest
summary: 결제 단건 조회
description: 'paymentId 로 결제 정보 조회. 응답 = ``Payment`` (oneOf 7 — 결제 상태별
다른 shape: ReadyPayment / PaidPayment / CancelledPayment 등).
결제 자동화의 가장 빈번한 read endpoint.
oneOf shape 차이 (dogfood 검증 — 2026-05-04):
- PaidPayment: ``pgResponse`` (raw PG json string) 노출 — 토스의
transactionKey, secret (webhook 검증), receipt URL, acquirerCode 등 PG-specific 디테일 포함
- CancelledPayment: ``pgResponse`` 미포함, 대신 top-level ``cancelledAt`` +
``cancellations[]`` 배열
- 모두 공통: ``method.card.number`` PCI 마스킹 형식 ``42424242****424*`` (앞 8 + 뒤 3)
⚠️ 404 응답 inconsistency (PortOne 측 spec gap, PT-ERROR-FIX2):
다른 op 의 404 = ``{"type": "PAYMENT_NOT_FOUND"}`` JSON
get_payment 의 404 = ``"payment not found"`` plain text
mcpweave wrapper 가 둘 다 PortoneNotFoundError 로 정규화 (메시지 그대로 surface).
Native pass-through.'
operationId: portone_get_payment
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: storeId
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Storeid
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments:
get:
tags:
- portone-rest
summary: 결제 다건 조회 (페이지)
description: '페이지 기반 list — 응답 ``{items: [Payment, ...], page: {...}}``.
대용량 polling 용도는 ``portone_list_payments_by_cursor`` 사용.
검색 조건은 query param 다양 — from / until / status 등.'
operationId: portone_list_payments
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: requestBody
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Requestbody
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments-by-cursor:
get:
tags:
- portone-rest
summary: 결제 대용량 다건 조회 (cursor 기반)
description: '대용량 polling 에 적합. since / until / cursor 쿼리 통한 cursor 기반
pagination.
응답 shape 가 list_payments 와 다름 (dogfood 발견 — 2026-05-04):
list_payments : {items: Payment[], page: {number, size, totalCount}}
list_payments_by_cursor: {items: [{payment, cursor}]} ← per-item cursor wrapping
cursor 는 base64 encoded JSON: ``{"createdAt":"...","entityId":""}``
(composite cursor — opaque 처리 권장).
Native pass-through.'
operationId: portone_list_payments_by_cursor
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments/{paymentId}/cancel:
post:
tags:
- portone-rest
summary: 결제 취소 (환불)
description: '결제 취소 / 환불. 부분 취소 가능 (amount 입력). reason 필수.
VAT 자동 계산 (dogfood 검증 — 2026-05-04):
- 100원 환불 → ``{"vatAmount": 9}`` 자동 응답에 포함 (supply 91 + vat 9).
- 가맹점이 vatAmount 명시 안 해도 PortOne 이 자동 분리.
응답 schema (cancellation object):
{
status: "SUCCEEDED",
id: "", ← cancellation 자체 ID
pgCancellationId: "txrd_a01...", ← Toss 의 transactionKey 형식
vatAmount: 9,
trigger: "API" ← enum: API / SDK / ADMIN
}
주의 (ADR-022 §D7 결제 risk policy):
- mcpweave 는 PortOne API forward only — 환불 정책은 가맹점 측 책임.
- audit log 에 (org_id / payment_id / amount / reason / actor) 기록.
본문 X.
body 핵심 필드:
reason (필수) 취소 사유
amount (선택) 부분 취소 금액. 미입력 시 전액 취소.
taxFreeAmount (선택) 부분 취소 중 면세 금액
requester (선택) Customer / Admin
refundAccount (선택) 가상계좌 환불 시 입력
**Destructive write — money flow**.'
operationId: portone_cancel_payment
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: confirmation_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ADR-030: required for irreversible op. First call returns token.'
title: Confirmation Token
description: 'ADR-030: required for irreversible op. First call returns token.'
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments/{paymentId}/confirm:
post:
tags:
- portone-rest
summary: 인증 결제 수동 승인
description: '인증 완료된 결제를 수동 승인 (paymentToken 검증 후 최종 capture).
일반적으로 PortOne SDK 가 자동 처리하지만 server-side 통제가 필요한
경우 사용.
body 핵심 필드:
paymentToken (필수) 인증 시 발급된 토큰
txId (선택) 결제 시도 ID 검증
currency (선택) 통화 검증
totalAmount (선택) 금액 검증
**Destructive write — money flow**.'
operationId: portone_confirm_payment
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: confirmation_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ADR-030: required for irreversible op. First call returns token.'
title: Confirmation Token
description: 'ADR-030: required for irreversible op. First call returns token.'
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments/{paymentId}/instant:
post:
tags:
- portone-rest
summary: 수기 결제 (가맹점 직접)
description: '가맹점이 카드 정보 / 빌링키 등을 server-side 에서 직접 결제 호출
(MOTO / 정기결제 / 자동납부 등). PCI-DSS scope 영향 — mcpweave 는
PortOne 통한 passthrough 만 (카드번호 mcpweave 통과 X 권장).
Body 핵심 구조 (dogfood 검증 — 2026-05-04):
{
"channelKey": "channel-key-...", ← required (channelKey xor channelGroupId)
"currency": "KRW", ← root level (NOT inside amount)
"orderName": "...",
"amount": {"total": 100},
"method": {
"card": {
"credential": {
"number": "4242...", ← required
"expiryYear": "30", "expiryMonth": "12",
"birthOrBusinessRegistrationNumber": "920101" ← required (개인=생년월일 / 법인=사업자번호)
// passwordTwoDigits: sandbox 면제 (실 결제 PG 마다 다름)
}
}
}
}
응답 (성공):
{"payment": {"pgTxId": "tiamp...", "paidAt": "...144698186Z"}}
full PaidPayment 객체는 ``portone_get_payment`` 로 별도 조회 (응답이 minimal).
⚠️ Sandbox 카드 인식 차이 (PT-SANDBOX-CARDS-FIX1):
- instant_payment 는 4242-4242-4242-4242 (Stripe-style test) 인식
- pay_with_billing_key 는 같은 4242 가 INVALID_CARD_NUMBER 502 (PG sandbox 별 정식 test card 차이)
- 정확한 sandbox 카드는 PortOne 콘솔 또는 PG 사 docs 참조
**Destructive write — money flow + PCI-DSS scope**.'
operationId: portone_instant_payment
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: confirmation_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ADR-030: required for irreversible op. First call returns token.'
title: Confirmation Token
description: 'ADR-030: required for irreversible op. First call returns token.'
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments/{paymentId}/billing-key:
post:
tags:
- portone-rest
summary: 빌링키 결제 (정기결제)
description: '발급된 billingKey 로 자동 결제 (SaaS 정기 구독 / 자동 갱신 핵심).
SDK 호출 없이 server 단독 결제 가능.
body 핵심 필드:
billingKey (필수) issueBillingKey 응답의 billingKey
orderName (필수) 결제 명
currency (필수, root level — NOT inside amount)
amount.total (필수)
customer (선택)
⚠️ Sandbox card 검증 strict (dogfood 발견 PT-SANDBOX-CARDS-FIX1):
- issue_billing_key 는 sandbox 가 카드번호 검증 안 함 (어떤 카드든 등록 가능)
- pay_with_billing_key 는 PG 측 실 검증 → 4242 사용 시 502 INVALID_CARD_NUMBER
- 정식 sandbox card (Toss: 5421-9382-1900-0000 등) 필요
502 PG_PROVIDER 응답 형식:
{"type": "PG_PROVIDER", "pgCode": "INVALID_CARD_NUMBER", "pgMessage": "카드번호를 다시 확인해주세요."}
mcpweave wrapper 가 pgCode/pgMessage 모두 surface (PortoneGatewayError).
**Destructive write — money flow**.'
operationId: portone_pay_with_billing_key
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: confirmation_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ADR-030: required for irreversible op. First call returns token.'
title: Confirmation Token
description: 'ADR-030: required for irreversible op. First call returns token.'
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/payments/{paymentId}/resend-webhook:
post:
tags:
- portone-rest
summary: 웹훅 재발송
description: '결제 완료 / 취소 등 이벤트의 webhook 을 수동 재발송. Retry 한계 도달
시 ``MaxWebhookRetryCountReachedError`` 반환 (수동 재시도 제한).
mcpweave 측 webhook event row 가 누락된 경우 또는 forward 실패
복구용.'
operationId: portone_resend_webhook
parameters:
- name: paymentId
in: path
required: true
schema:
type: string
title: Paymentid
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/billing-keys:
post:
tags:
- portone-rest
summary: 빌링키 발급 (정기결제 등록)
description: '고객 정기결제 / 자동납부 등록 핵심. SDK 통한 인증 후 mcpweave 가 server
단독 발급은 method 가 holder 정보로만 충분한 경우 (e.g. 가상계좌 결제).
대부분 카드는 SDK 인증 흐름 거침.
Sandbox 동작 (dogfood 검증 — 2026-05-04):
- sandbox 면 SDK 인증 없이 server-side 단독 발급 가능 (test 환경 면제)
- sandbox 가 카드번호 검증 X — 어떤 카드든 등록됨 (단, ``pay_with_billing_key`` 시 PG 측 검증으로 502)
응답 schema:
{
"billingKey": "billing-key-{UUIDv7}", ← PortOne 발급 namespace
"channels": [{...}], ← multi-channel 동시 사용 가능
"issuedAt": "...441548859Z", ← nanosecond precision
"customer": {...} ← 자동 등록 (안 보내도 생성)
"pgBillingKeyIssueResponses": [...] ← per-channel 발급 결과
}
**Destructive write — billingKey 발급은 PG 측 영구 등록**.'
operationId: portone_issue_billing_key
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
get:
tags:
- portone-rest
summary: 빌링키 다건 조회
description: '가맹점에 등록된 billingKey 목록. 응답 = ``{items: [BillingKeyInfo, ...], page}``.
Native pass-through.'
operationId: portone_list_billing_keys
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/billing-keys/{billingKey}:
delete:
tags:
- portone-rest
summary: 빌링키 삭제 (정기결제 해지)
description: 'billingKey 삭제 = 사용자 정기결제 해지. 이후 ``pay_with_billing_key``
호출 시 거부.
Soft delete pattern (dogfood 검증):
- status: ``ISSUED`` → ``DELETED`` 전이
- ``list_billing_keys`` 에 historical record 보존 (감사 용도, deletedAt 노출)
- 응답 minimal: ``{"deletedAt": "...nanosecond Z"}``
404 응답: ``{"type": "BILLING_KEY_NOT_FOUND"}`` (typed JSON)
**Destructive write — 사용자 정기결제 영구 해지**.'
operationId: portone_delete_billing_key
parameters:
- name: billingKey
in: path
required: true
schema:
type: string
title: Billingkey
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: reason
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Reason
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/cash-receipts:
post:
tags:
- portone-rest
summary: 현금영수증 수동 발급
description: '현금 결제 (가상계좌 / 계좌이체 / 핀번호 결제) 시 한국 법적으로 발급
필수. 일반적으로 PG 가 자동 발급하지만 ``skipWebhook=true`` 또는 수동
발급 필요 시 호출.
body 핵심 필드:
paymentId (필수) 결제 건 ID
channelKey (선택) PG 채널
type (필수) PERSONAL (소득공제) / CORPORATE (지출증빙)
orderName (필수) 결제 명
customer (필수) 발급 대상 (이름 / 식별번호 — 휴대폰번호 또는 사업자번호)
amount (필수) 발급 금액
**Destructive write — 세무 반영**.'
operationId: portone_issue_cash_receipt
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: confirmation_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ADR-030: required for irreversible op. First call returns token.'
title: Confirmation Token
description: 'ADR-030: required for irreversible op. First call returns token.'
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
/api/v1/portone/identity-verifications:
get:
tags:
- portone-rest
summary: 본인인증 내역 다건 조회
description: '본인인증 시도 / 완료 history. send / confirm / resend 는 Phase 2+
(실제 사용자 휴대폰 / PASS 인증은 SDK 통한 client-side 흐름이라
server-side mcpweave 호출의 use case 가 적음).
응답 = ``{items: [IdentityVerification, ...], page}``.'
operationId: portone_list_identity_verifications
parameters:
- name: connection_id
in: query
required: true
schema:
type: string
description: mcpweave connection_id
title: Connection Id
description: mcpweave connection_id
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
- name: mcpweave_session
in: cookie
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Mcpweave Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
default:
description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)