{
  "openapi": "3.1.0",
  "info": { "title": "Docenty Pay API", "version": "2.0.0", "description": "v2 commerce surface (pl_002). Errors: {error:{code,message,fix,docUrl,retryAfterSec?,requestId?}}. Idempotency-Key optional on POST /checkouts, /invoices, /invoices/:id/resend|send (scope: app/creator, 24h)." },
  "servers": [{ "url": "https://pay.docenty.ai/api" }],
  "components": {
    "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "x-app-key" }, "bearer": { "type": "http", "scheme": "bearer" }, "earnSignature": { "type": "apiKey", "in": "header", "name": "X-Earn-Signature", "description": "sp_002: v1=HMAC-SHA256(secret[kid], ts\\nnonce\\nbody) with X-Earn-Key-Id, X-Earn-Timestamp, X-Earn-Nonce" } },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fix": { "type": "string" }, "docUrl": { "type": "string" }, "retryAfterSec": { "type": "integer" }, "requestId": { "type": "string" } } } } },
      "CheckoutCreate": { "type": "object", "properties": { "productId": { "type": "string" }, "kind": { "type": "string", "enum": ["tip"] }, "amountKrw": { "type": "integer" }, "buyerRef": { "type": "string" }, "buyerEmail": { "type": "string" }, "provider": { "type": "string", "enum": ["manual_transfer", "portone"] }, "variantId": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 99 }, "fulfillmentData": { "type": "object", "additionalProperties": { "type": "string" } }, "payMethod": { "type": "string", "enum": ["card", "easy_pay", "virtual_account", "manual_transfer"] }, "easyPayProvider": { "type": "string", "enum": ["kakaopay", "naverpay", "tosspay"] } } },
      "Checkout": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["created", "pending", "paid", "failed", "refunded", "partially_refunded", "expired", "pending_review"] }, "payment": { "type": "string" }, "verification": { "type": "string", "enum": ["none", "pending", "verified"] }, "fulfillment": { "type": "string", "enum": ["placed", "paid", "fulfilling", "fulfilled", "cancelled"] }, "hold": { "type": "string", "enum": ["none", "held", "released", "disputed"] }, "mode": { "type": "string", "enum": ["live", "test"] }, "amountKrw": { "type": "integer" }, "qty": { "type": "integer" }, "kind": { "type": "string", "enum": ["one_time", "credit_pack", "tip", "physical", "service", "digital_file", "ticket"] }, "payMethod": { "type": "string" }, "buyerBound": { "type": "boolean" } } },
      "InvoiceCreate": { "type": "object", "required": ["appId", "to"], "properties": { "appId": { "type": "string" }, "to": { "type": "object", "properties": { "phone": { "type": "string" }, "email": { "type": "string" } } }, "productId": { "type": "string" }, "amountKrw": { "type": "integer", "minimum": 100 }, "note": { "type": "string", "maxLength": 500 }, "channel": { "type": "string", "enum": ["alimtalk", "email"] }, "variantId": { "type": "string" }, "qty": { "type": "integer" } } },
      "InvoiceResult": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "checkoutId": { "type": "string" }, "orderUrl": { "type": "string" }, "deliveryStatus": { "type": "string", "enum": ["draft", "queued", "sent", "delivered", "failed", "noop", "viewed", "paid", "expired"] } } },
      "ProductCreate": { "type": "object", "required": ["appId", "name", "kind"], "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": ["one_time", "credit_pack", "tip", "physical", "service", "digital_file", "ticket"] }, "priceKrw": { "type": "integer" }, "variants": { "type": "array", "items": { "type": "object", "required": ["name", "priceKrw"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "priceKrw": { "type": "integer", "minimum": 100 } } } }, "shippingKrw": { "type": "integer" }, "inventory": { "type": ["integer", "null"] }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "descriptionMd": { "type": "string" }, "fulfillment": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "templateKey": { "type": "string" } } },
      "NvLandLead": { "type": "object", "required": ["schemaVersion", "eventId", "leadId", "projectId", "appKey", "contact"], "properties": { "schemaVersion": { "const": 1 }, "eventId": { "type": "string" }, "leadId": { "type": "string" }, "projectId": { "type": "string" }, "appKey": { "type": "string" }, "contact": { "type": "object", "properties": { "phone": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "productId": { "type": "string" }, "orderOptions": { "type": "object" }, "consent": { "type": "object", "properties": { "marketing": { "type": "boolean" }, "at": { "type": "string", "format": "date-time" } } }, "note": { "type": "string" } } }
    }
  },
  "paths": {
    "/checkouts": { "post": { "security": [{ "appKey": [] }], "parameters": [{ "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 128 } }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCreate" } } } }, "responses": { "201": { "description": "checkoutId, url, payUrl, status, amountKrw, qty, kind, mode" }, "400": { "description": "VALIDATION | VARIANT_INVALID | PROVIDER_UNAVAILABLE" }, "409": { "description": "SOLD_OUT | IDEMPOTENCY_CONFLICT" } } } },
    "/checkouts/{id}": { "get": { "security": [{ "appKey": [] }], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "$ref": "#/components/schemas/Checkout" } } } } } } } } },
    "/checkouts/{id}/fulfillment": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["fulfillmentData"], "properties": { "fulfillmentData": { "type": "object" } } } } } }, "responses": { "200": {}, "400": { "description": "FULFILLMENT_REQUIRED {fix: 필수 항목}" } } } },
    "/checkouts/{id}/portone/start": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["payMethod"], "properties": { "payMethod": { "type": "string", "enum": ["card", "easy_pay", "virtual_account"] }, "easyPayProvider": { "type": "string" } } } } } }, "responses": { "200": { "description": "paymentId (`checkoutId-attempt`), attempt, payload (PortOne browser SDK), testMode" }, "400": { "description": "METHOD_UNAVAILABLE | FULFILLMENT_REQUIRED" } } } },
    "/products": { "post": { "security": [{ "bearer": [] }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" } } } }, "responses": { "201": {} } } },
    "/products/{id}": { "patch": { "security": [{ "bearer": [] }], "responses": { "200": {} } } },
    "/templates": { "get": { "responses": { "200": { "description": "templates[] {key,title,who,kind,available,fields,defaults}" } } } },
    "/templates/apply": { "post": { "security": [{ "bearer": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["appId", "template"], "properties": { "appId": { "type": "string" }, "template": { "type": "string", "enum": ["fruit", "consulting"] }, "name": { "type": "string" }, "variants": { "type": "array" }, "shippingKrw": { "type": "integer" }, "inventory": { "type": ["integer", "null"] }, "images": { "type": "array" } } } } } }, "responses": { "201": {}, "400": { "description": "TEMPLATE_UNAVAILABLE" } } } },
    "/invoices": { "post": { "security": [{ "bearer": [] }], "parameters": [{ "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreate" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResult" } } } }, "429": { "description": "INVOICE_LIMIT" } } }, "get": { "security": [{ "bearer": [] }], "responses": { "200": {} } } },
    "/invoices/{id}/resend": { "post": { "security": [{ "bearer": [] }], "responses": { "200": { "description": "new link (old revoked) + new outbox row" } } } },
    "/invoices/{id}/send": { "post": { "security": [{ "bearer": [] }], "description": "NvLand draft → confirm product/amount → send (same invoiceId)", "responses": { "200": {} } } },
    "/o/{token}": { "get": { "description": "masked order view (capability token). Never mutates.", "responses": { "200": {}, "404": { "description": "ORDER_LINK_INVALID" } } } },
    "/o/{token}/actions": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["view_invoice", "claim", "confirm_receipt", "dispute", "refund_account", "message", "stop_reminders"] } } } } } }, "responses": { "200": {} } } },
    "/orders": { "get": { "security": [{ "bearer": [] }], "responses": { "200": {} } } },
    "/orders/{id}/fulfill": { "post": { "security": [{ "bearer": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["event"], "properties": { "event": { "type": "string", "enum": ["ship", "fulfill"] }, "tracking": { "type": "string" } } } } } }, "responses": { "200": {}, "409": { "description": "NOT_VERIFIED (ship before Docenty 입금 확인) | INVALID_STATE" } } } },
    "/buyer-groups": { "get": { "security": [{ "bearer": [] }], "responses": { "200": {} } }, "post": { "security": [{ "bearer": [] }], "responses": { "201": {} } } },
    "/creators/me/kyc": { "put": { "security": [{ "bearer": [] }], "responses": { "200": { "description": "masked view" } } } },
    "/payouts": { "post": { "security": [{ "bearer": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["amountKrw", "idempotencyKey"], "properties": { "amountKrw": { "type": "integer", "minimum": 30000 }, "idempotencyKey": { "type": "string" } } } } } }, "responses": { "201": {}, "409": { "description": "KYC_REQUIRED | PAYOUT_ACTIVE | INSUFFICIENT_BC | IDEMPOTENCY_CONFLICT" } } } },
    "/bill-pay": { "post": { "security": [{ "bearer": [] }], "responses": { "201": {}, "409": { "description": "DUPLICATE_INVOICE" }, "429": { "description": "BILL_PAY_LIMIT" } } } },
    "/creators/me/statement": { "get": { "security": [{ "bearer": [] }], "parameters": [{ "in": "query", "name": "month", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": ["json", "csv"] } }], "responses": { "200": {} } } },
    "/integrations/nvland/leads": { "post": { "security": [{ "earnSignature": [] }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NvLandLead" } } } }, "responses": { "202": { "description": "{invoiceId, status:'draft'} (new)" }, "200": { "description": "existing invoiceId (idempotent)" }, "401": { "description": "signature errors" }, "409": { "description": "NONCE_REPLAY" } } } }
  }
}