openapi: 3.1.1 info: title: 서버 연동 레퍼런스 description: | point3 결제창을 사용하기 위해 가맹점 서버에서 호출하는 API입니다. 가맹점 화면에서 호출하지 마세요. version: 0.3.0 servers: - url: https://api.point3.io description: 운영 API security: - bearerAuth: [] tags: - name: payment x-displayName: 결제 x-zudoku-collapsible: false description: | 결제창을 열기 전에 결제 세션을 만들고, 구매자가 결제를 진행한 뒤 결제 결과를 확인합니다. - name: refund x-displayName: 결제 취소 x-zudoku-collapsible: false description: | 승인 완료된 결제를 가맹점 서버에서 전부 또는 일부 취소합니다. - name: delegated x-displayName: 위임 인증 x-zudoku-collapsible: false description: > 가맹점에 로그인한 회원이 point3 결제창의 문자 인증 없이 결제하도록 합니다. 가맹점 서버가 회원 정보에 저장된 구매자 아이디(payerId)로 위임 인증을 생성해 결제창에 전달하면, 구매자는 문자 인증 없이 바로 결제를 진행할 수 있습니다. 자세한 내용은 [위임 인증](/delegated-authentication)과 [위임 인증 생성](/delegated-creation)을 확인하세요. x-tagGroups: - name: payment tags: - payment - name: refund tags: - refund - name: delegated tags: - delegated paths: /authn/v2/delegation: post: tags: - delegated operationId: createDelegation summary: 위임 인증 생성 description: > 로그인한 회원의 `payerId`로 위임 인증을 생성합니다. 응답의 `authorization_url`을 JavaScript SDK `widgets()`의 `brandpay.redirectUrl`로 전달하세요. 위임 인증은 300초 동안 유효하며 한 번의 결제창 실행에만 사용할 수 있습니다. 가맹점은 API 키로 식별하므로 요청 본문에 가맹점 정보를 넣지 않습니다. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateDelegationRequest" examples: 위임 인증 생성: value: payer_id: payer:00000000000000000000000000 responses: "200": description: 위임 인증 생성 성공 content: application/json: schema: $ref: "#/components/schemas/CreateDelegationResponse" examples: 성공: value: delegation_id: dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw expires_in: 300 authorization_url: https://auth.point3.io/delegated?delegation_id=dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw "400": description: 요청 본문 형식 오류 또는 허용되지 않은 필드 포함 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: 요청 형식 오류: value: status: 400 timestamp: 2026-10-26T00:00:00.000Z result: code: HTTP_ERROR message: 요청 본문이 유효하지 않습니다. "401": description: API 키 누락 또는 검증 실패 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: 구매자가 없거나, 비활성이거나, 다른 가맹점 소속 (구분하지 않음) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: 구매자 없음: value: status: 404 timestamp: 2026-10-26T00:00:00.000Z result: code: PAYER_NOT_FOUND message: Payer not found in identity plane "503": description: 일시적 장애. 위임 인증 없이 결제창을 여세요. /payment/v3/session/{sessionId}: get: tags: - payment operationId: getPaymentSession summary: 결제 세션 조회 description: > 결제 세션 아이디로 결제 세션 정보를 조회합니다. 정상 조회는 HTTP 200으로 반환되며 응답 본문의 `status`로 진행 상태와 최종 결과를 판단합니다. `processing`이면 잠시 기다렸다가 같은 세션을 다시 조회하세요. `captured` 또는 `failed`가 확인되면 결제 결과가 확정된 것입니다. parameters: - name: sessionId in: path required: true description: 조회할 결제 세션 식별자 schema: type: string examples: default: value: pymt_sess-019f0000-0000-7000-9000-000000000000 responses: "200": description: 결제 세션 조회 성공 content: application/json: schema: $ref: "#/components/schemas/PaymentSessionResponse" examples: 결제 성공: value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 status: captured clientId: client-019f0000-0000-7000-9000-000000000001 amount: 10000 currency: KRW supplyAmount: 9091 taxFreeAmount: 0 vat: 909 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 tradeOpt: GENERAL createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:01:40.000Z payerId: payer:00000000000000000000000000 승인 처리 중: value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 status: processing clientId: client-019f0000-0000-7000-9000-000000000001 amount: 10000 currency: KRW supplyAmount: 9091 taxFreeAmount: 0 vat: 909 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 tradeOpt: GENERAL createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:01:35.000Z payerId: payer:00000000000000000000000000 결제 실패: value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 status: failed clientId: client-019f0000-0000-7000-9000-000000000001 amount: 10000 currency: KRW supplyAmount: 9091 taxFreeAmount: 0 vat: 909 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 tradeOpt: GENERAL createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:01:40.000Z payerId: payer:00000000000000000000000000 "400": description: 잘못된 요청입니다. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "401": description: 인증에 실패했습니다. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "403": description: 요청이 허용되지 않았습니다. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "404": description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "500": description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "503": description: 결제 상태를 일시적으로 확인할 수 없습니다. 잠시 기다렸다가 같은 세션을 다시 조회하세요. content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" examples: default: value: error: type: serviceUnavailableError code: temporarilyUnavailable message: 결제 상태를 일시적으로 조회할 수 없습니다. /payment/v3/session: post: tags: - payment operationId: createPaymentSession summary: 결제 세션 생성 description: | 가맹점 서버가 주문과 결제 금액을 확인한 뒤 결제창을 열기 전에 호출합니다. 매일 23:30 이상 다음 날 00:30 미만(Asia/Seoul)에는 EOB 점검으로 생성을 차단합니다. 차단된 요청은 세션을 저장하지 않습니다. 성공하면 생성된 결제 세션 리소스를 직접 반환합니다. 응답의 `id`는 `sessionId`로서 주문과 함께 저장하세요. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePaymentSessionRequest" examples: 일반 상품: value: amount: 10000 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 전액 면세 상품: value: amount: 10000 taxFreeAmount: 10000 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 복합 과세 상품: value: amount: 11000 taxFreeAmount: 1000 productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 responses: "200": description: 결제 세션 생성 성공 content: application/json: schema: $ref: "#/components/schemas/CreatePaymentSessionResponse" examples: 성공: value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 status: created clientId: client-019f0000-0000-7000-9000-000000000001 amount: 10000 currency: KRW supplyAmount: 9091 taxFreeAmount: 0 vat: 909 taxationType: TAXABLE productName: 아메리카노 외 1건 displayMerchantName: 포인트쓰리 스토어 tradeOpt: GENERAL createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:00:00.000Z "400": description: 요청값 오류 content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "401": description: 인증 실패 또는 허용되지 않은 접근 content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" "503": description: 현재 EOB 점검 구간 content: application/json: schema: $ref: "#/components/schemas/PaymentSessionErrorResponse" examples: EOB 점검 구간: value: error: type: serviceUnavailableError code: temporarilyUnavailable message: 시스템 점검 시간에는 결제를 진행할 수 없습니다. 2026-09-16T00:30:00+09:00 (Asia/Seoul) 이후 다시 시도해주세요. eob: startsAt: 2026-09-15T23:30:00+09:00 endsAt: 2026-09-16T00:30:00+09:00 timeZone: Asia/Seoul /capture/v2/{sessionId}: post: tags: - payment operationId: capturePayment summary: 결제 승인 description: > 가맹점 화면이 `successUrl`로 이동한 뒤 가맹점 서버가 호출합니다. 결제가 커밋된 날의 다음 날 00:00(KST)부터는 승인할 수 없습니다. 주문의 최종 결제 결과는 응답의 `status` 또는 결제 세션 조회 API를 호출하여 확인하세요. 실패가 확정된 경우에도 HTTP `200`을 반환합니다. `status`가 `failed`이면 `outcome.code`로 사유를 구분하세요. `outcome.message` 문구는 바뀔 수 있으므로 분기 조건으로 쓰지 마세요. | `outcome.code` | `outcome.type` | 의미 | 처리 | | --- | --- | --- | --- | | `PAYMENT_METHOD_DECLINED` | `declined` | 결제수단 승인 거절. 잔액 부족, 출금 가능 잔액 부족 등 | 잔액 확인 또는 다른 계좌 선택 안내 | | `PAYMENT_METHOD_LIMIT_EXCEEDED` | `failed` | 이체한도 초과 | 이체한도 확인 또는 다른 계좌 선택 안내 | | `PAYMENT_CAPTURE_REJECTED` | `rejected` | 세부 사유가 분류되지 않은 이체 실패 | 주문·결제 상태 확인, 필요하면 문의 | | `PAYMENT_CAPTURE_ALREADY_FAILED` | `failed` | 이미 실패한 결제를 다시 승인 요청함. 원래 사유는 포함되지 않음 | 처음 받은 실패 응답의 기록 확인 | 처음 받은 실패 응답의 `outcome.code`를 주문·`sessionId`와 함께 저장하고, 이후 응답으로 덮어쓰지 마세요. HTTP `202`(`status: processing`)는 아직 처리 중이라는 뜻이며 실패가 아닙니다. 응답을 받지 못했을 때와 같이 `sessionId`로 결제 세션을 조회해 결과를 확인하세요. parameters: - name: sessionId in: path required: true description: 결제 세션 생성 응답으로 받은 현재 주문의 세션 식별값 schema: type: string examples: default: value: pymt_sess-019f0000-0000-7000-9000-000000000000 responses: "200": description: 승인 완료 또는 확정된 실패 content: application/json: schema: $ref: "#/components/schemas/CapturePaymentResponse" examples: 승인 성공: value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 object: paymentCapture status: captured outcome: type: succeeded code: PAYMENT_CAPTURED message: 결제승인 성공적으로 완료되었습니다. committedAt: 2026-08-21 승인 실패 (잔액 부족): summary: 잔액 부족 등으로 결제수단 승인이 거절된 경우 value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 object: paymentCapture status: failed outcome: type: declined code: PAYMENT_METHOD_DECLINED message: 결제수단 승인이 거절되었습니다. committedAt: 2026-08-21 승인 실패 (이체한도 초과): summary: 이체한도를 초과한 경우 value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 object: paymentCapture status: failed outcome: type: failed code: PAYMENT_METHOD_LIMIT_EXCEEDED message: 결제수단의 이체한도를 초과했습니다. committedAt: 2026-08-21 이미 실패한 결제 재요청: summary: 원래 실패 사유는 포함되지 않습니다 value: id: pymt_sess-019f0000-0000-7000-9000-000000000000 object: paymentCapture status: failed outcome: type: failed code: PAYMENT_CAPTURE_ALREADY_FAILED message: 이미 실패 처리된 결제입니다. committedAt: 2026-08-21 "202": description: 현재 승인 요청의 이체 처리 중 content: application/json: schema: $ref: "#/components/schemas/CapturePaymentProcessingResponse" "400": description: 요청 형식 오류 content: application/json: schema: $ref: "#/components/schemas/CaptureInvalidRequestErrorResponse" "401": description: 인증 실패 content: application/json: schema: $ref: "#/components/schemas/CaptureAuthenticationErrorResponse" "403": description: 접근 거부 content: application/json: schema: $ref: "#/components/schemas/CapturePermissionErrorResponse" "404": description: 결제를 찾을 수 없음 content: application/json: schema: $ref: "#/components/schemas/CaptureNotFoundErrorResponse" "422": description: 승인 기한 만료. 새 결제 세션으로 다시 시작해야 합니다. content: application/json: schema: $ref: "#/components/schemas/CaptureExpiredErrorResponse" "500": description: 서버 내부 오류 content: application/json: schema: $ref: "#/components/schemas/CaptureApiErrorResponse" /refunds/v1/{sessionId}: get: tags: - refund operationId: getPaymentRefund summary: 결제 취소 상태 조회 description: | 결제 세션의 취소 상태, 취소 이력과 취소 가능 금액을 조회합니다. 취소 요청의 응답을 받지 못했거나 결과가 확실하지 않을 때 사용하세요. parameters: - name: sessionId in: path required: true description: 승인 완료된 원 결제의 세션 식별값 schema: type: string examples: default: value: pymt_sess-019f0000-0000-7000-9000-000000000000 responses: "200": description: 결제 취소 상태 조회 성공 content: application/json: schema: $ref: "#/components/schemas/PaymentRefundStatusResponse" examples: 부분 취소 완료: value: paymentSessionId: pymt_sess-019f0000-0000-7000-9000-000000000000 clientId: client-019f0000-0000-7000-9000-000000000001 status: partiallyRefunded originalAmount: 10000 currency: KRW refundableAmount: 5000 productName: 아메리카노 외 1건 canCreateRefund: true refunds: - id: ref-019f0000-0000-7000-9000-000000000000 status: completed amount: 5000 currency: KRW taxFreeAmount: 0 vat: 455 fee: 100 reason: 고객 요청 failure: null createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:00:01.000Z "401": description: 인증 실패 또는 허용되지 않은 접근 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: 취소 정보를 찾을 수 없음 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: 서버 내부 오류 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" post: servers: - url: https://api.point3.io description: 운영 결제 취소 API tags: - refund operationId: createPaymentRefund summary: 결제 취소 description: > 승인 완료된 결제를 전부 또는 일부 취소합니다. 세금을 자동으로 계산하지 않으므로 `refundAmount`, `refundTaxFreeAmount`, `refundVat`를 모두 지정해야 합니다. 취소 결과가 확실하지 않으면 취소 상태 조회 API로 확인하세요. security: - bearerAuth: [] parameters: - name: sessionId in: path required: true description: 승인 완료된 원 결제의 세션 식별값 schema: type: string examples: default: value: pymt_sess-019f0000-0000-7000-9000-000000000000 - name: Idempotency-Key in: header required: false description: 24시간 동안 같은 취소 요청의 중복 처리를 막는 선택 값입니다. schema: type: string maxLength: 300 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePaymentRefundRequest" examples: 부분취소: value: refundAmount: 10000 refundTaxFreeAmount: 0 refundVat: 909 reason: 고객 요청 responses: "200": description: 결제 취소 완료 content: application/json: schema: $ref: "#/components/schemas/PaymentRefundResponse" examples: 완료: value: id: ref-019f0000-0000-7000-9000-000000000000 paymentSessionId: pymt_sess-019f0000-0000-7000-9000-000000000000 clientId: client-019f0000-0000-7000-9000-000000000001 productName: 아메리카노 외 1건 status: completed amount: 10000 currency: KRW taxFreeAmount: 0 vat: 909 fee: 100 reason: 고객 요청 createdAt: 2026-08-21T00:00:00.000Z updatedAt: 2026-08-21T00:00:01.000Z "400": description: 요청값 또는 세금 구성 오류 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: 인증 실패 또는 허용되지 않은 접근 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: 결제 세션 또는 취소 대상 없음 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "409": description: 중복 요청, 처리 중인 취소 또는 정책상 요청 불가. `result.code`를 확인하세요. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: 결과미확정: value: status: 409 timestamp: 2026-08-21T00:00:00.000Z result: code: REFUND_TEMPORARY_UNAVAILABLE message: 환불 처리 결과가 아직 확정되지 않았습니다 details: paymentSessionId: pymt_sess-019f0000-0000-7000-9000-000000000000 refundEntryId: ref-019f0000-0000-7000-9000-000000000000 중복키: value: status: 409 timestamp: 2026-08-21T00:00:00.000Z result: code: REFUND_DUPLICATE_REQUEST message: 동일한 Idempotency-Key로 요청이 이미 접수되었습니다 진행중취소: value: status: 409 timestamp: 2026-08-21T00:00:00.000Z result: code: REFUND_ACTIVE_REQUEST_EXISTS message: 활성 환불 항목이 존재할 때 새로운 환불 항목을 추가할 수 없습니다 EOB차단: value: status: 409 timestamp: 2026-08-21T00:00:00.000Z result: code: EOB_WINDOW_BLOCKED message: EOB 차단 시간대에는 환불을 요청할 수 없습니다 "422": description: 취소 가능 금액 초과 또는 취소 요청 거절 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: 서버 내부 오류 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: 취소 처리 서비스 일시 사용 불가 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /refunds/v1/{sessionId}/resume: post: tags: - refund operationId: resumePaymentRefund summary: 결제 취소 처리 재개 description: | `processing` 상태인 취소 처리를 재개합니다. 먼저 취소 상태를 조회하고 처리 중인 취소가 있을 때만 호출하세요. parameters: - name: sessionId in: path required: true description: 원 결제의 세션 식별값 schema: type: string examples: default: value: pymt_sess-019f0000-0000-7000-9000-000000000000 responses: "200": description: 결제 취소 처리 재개 성공 content: application/json: schema: $ref: "#/components/schemas/PaymentRefundStatusResponse" "401": description: 인증 실패 또는 허용되지 않은 접근 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: 취소 정보를 찾을 수 없음 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: 서버 내부 오류 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: 취소 처리 서비스 일시 사용 불가 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" components: securitySchemes: bearerAuth: type: http scheme: bearer description: "point3가 발급한 API 키를 가맹점 서버에만 보관하고 `Authorization: Bearer {token}` 형식으로 사용합니다." schemas: CreatePaymentSessionRequest: type: object required: - amount - productName properties: amount: type: integer description: 사용자가 지불할 결제 총액입니다. 대한민국 원(KRW) 단위입니다. examples: - 10000 productName: type: string description: 결제창에 표시할 상품명입니다. examples: - 아메리카노 외 1건 displayMerchantName: type: string description: 결제 UI에 표시할 가맹점 상호명입니다. 미지정 시 `productName` 을 사용합니다. examples: - 포인트쓰리 스토어 vat: type: integer description: 부가세 금액입니다. 서버가 자동으로 계산하며, 수동 설정이 필요할 경우 지정합니다. 자세한 내용은 [세금 처리](/tax-processing)를 확인하세요. examples: - 909 taxFreeAmount: type: integer default: 0 description: 면세 금액입니다. 면세 상품의 경우 지정합니다. 자세한 내용은 [세금 처리](/tax-processing)를 확인하세요. examples: - 0 tradeOpt: type: string enum: - GENERAL - BOOK_CULTURE - PUBLIC_TRANSPORT default: GENERAL description: 세금 처리를 위한 결제 분류입니다. 세법 상 도서·문화 또는 대중교통 분류 상품의 경우 지정합니다. CreatePaymentSessionResponse: type: object description: 생성된 결제 세션 리소스입니다. 별도의 성공 응답 래퍼 없이 직접 반환됩니다. required: - id - status - clientId - amount - currency - supplyAmount - taxFreeAmount - vat - taxationType - productName - tradeOpt - createdAt - updatedAt properties: id: type: string description: 결제 세션 식별값입니다. 가맹점 화면과 결제 세션 조회 요청에서 `sessionId`로 사용합니다. examples: - pymt_sess-019f0000-0000-7000-9000-000000000000 status: type: string enum: - created description: 생성 직후의 공개 결제 세션 상태 clientId: type: string description: 결제 세션을 생성한 가맹점 클라이언트 식별값 examples: - client-019f0000-0000-7000-9000-000000000001 amount: type: integer minimum: 1 description: VAT를 포함한 최종 결제 총액(원) examples: - 10000 currency: type: string enum: - KRW description: 결제 통화 supplyAmount: type: integer minimum: 0 description: point3에서 계산한 과세 공급가액 입니다. 계산 규칙은 [세금 처리](/tax-processing)를 확인하세요. examples: - 9091 taxFreeAmount: type: integer minimum: 0 description: 총액에 포함된 면세 금액(원) examples: - 0 vat: type: integer minimum: 0 description: 확정된 부가세 금액(원) examples: - 909 productName: type: string description: 결제 상품명 examples: - 아메리카노 외 1건 displayMerchantName: type: string description: 결제 UI에 표시되는 가맹점 상호명 examples: - 포인트쓰리 스토어 tradeOpt: type: string enum: - GENERAL - BOOK_CULTURE - PUBLIC_TRANSPORT description: 현금영수증 분류입니다. createdAt: type: string format: date-time description: 결제 세션 생성 시각 examples: - 2026-08-21T00:00:00.000Z updatedAt: type: string format: date-time description: 결제 세션 최종 수정 시각 examples: - 2026-08-21T00:00:00.000Z PaymentSessionResponse: type: object description: 조회된 결제 세션 리소스입니다. required: - id - status - clientId - amount - currency - supplyAmount - taxFreeAmount - vat - taxationType - productName - tradeOpt - createdAt - updatedAt properties: id: type: string description: 결제 세션 식별값입니다. examples: - pymt_sess-019f0000-0000-7000-9000-000000000000 status: type: string enum: - created - identified - initiated - committed - processing - captured - failed - expired description: 현재 결제 세션 상태입니다. processing이면 다시 조회하고, captured 또는 failed가 확인되면 결제 결과가 확정된 것입니다. expired는 결제 승인 기한이 지나 더 이상 결제할 수 없는 세션입니다. examples: - captured clientId: type: string description: 결제 세션을 생성한 가맹점 클라이언트 식별값 examples: - client-019f0000-0000-7000-9000-000000000001 amount: type: integer minimum: 1 description: VAT를 포함한 최종 결제 총액(원) examples: - 10000 currency: type: string enum: - KRW description: 결제 통화 supplyAmount: type: integer minimum: 0 description: 과세 공급가액(원) examples: - 9091 taxFreeAmount: type: integer minimum: 0 description: 총액에 포함된 면세 금액(원) examples: - 0 vat: type: integer minimum: 0 description: 확정된 부가세 금액(원) examples: - 909 productName: type: string description: 결제 상품명 examples: - 아메리카노 외 1건 displayMerchantName: type: string description: 결제 UI에 표시되는 가맹점 상호명 examples: - 포인트쓰리 스토어 tradeOpt: type: string enum: - GENERAL - BOOK_CULTURE - PUBLIC_TRANSPORT description: 현금영수증 분류 createdAt: type: string format: date-time description: 결제 세션 생성 시각 examples: - 2026-08-21T00:00:00.000Z updatedAt: type: string format: date-time description: 결제 세션 최종 수정 시각 examples: - 2026-08-21T00:00:00.000Z payerId: type: string description: 본인인증 완료(identified 이상) 후 공개되는 결제자 식별자입니다. examples: - payer:00000000000000000000000000 CapturePaymentResponse: description: 결제 승인 요청이 완료된 결과입니다. type: object additionalProperties: false required: - id - object - status - outcome - committedAt properties: id: type: string description: 결제 세션 식별값입니다. examples: - pymt_sess-019f0000-0000-7000-9000-000000000000 object: type: string enum: - paymentCapture description: 응답 객체 종류 examples: - paymentCapture status: type: string enum: - captured - failed description: 승인 요청의 결과 상태. `failed`는 확정된 실패입니다. outcome: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - succeeded - declined - paymentMethodUnavailable - serviceUnavailable - rejected - failed code: type: string enum: - PAYMENT_CAPTURED - PAYMENT_METHOD_DECLINED - PAYMENT_METHOD_LIMIT_EXCEEDED - PAYMENT_METHOD_UNAVAILABLE - PAYMENT_SERVICE_UNAVAILABLE_HOURS - PAYMENT_CAPTURE_REJECTED - PAYMENT_CAPTURE_ALREADY_FAILED description: > 결과 코드. 분기 조건으로는 `message`가 아니라 이 값을 사용하세요. - `PAYMENT_METHOD_DECLINED`: 결제수단 승인 거절. 잔액 부족, 출금 가능 잔액 부족 등 - `PAYMENT_METHOD_LIMIT_EXCEEDED`: 이체한도 초과 - `PAYMENT_CAPTURE_REJECTED`: 세부 사유가 분류되지 않은 이체 실패 - `PAYMENT_CAPTURE_ALREADY_FAILED`: 이미 실패한 결제의 재요청. 원래 사유는 포함되지 않음 message: type: string description: 가맹점에 공개되는 결제 승인 결과 설명 committedAt: type: string format: date description: 결제 커밋 기준일(KST) examples: - 2026-08-21 CapturePaymentProcessingResponse: description: 현재 결제 승인 요청의 이체가 처리 중인 결과입니다. type: object additionalProperties: false required: - id - object - status - outcome - committedAt properties: id: type: string description: 결제 세션 식별값 object: type: string enum: - paymentCapture status: type: string enum: - processing outcome: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - processing code: type: string enum: - PAYMENT_CAPTURE_PROCESSING message: type: string committedAt: type: string format: date description: 결제 커밋 기준일(KST) CaptureInvalidRequestErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - invalidRequestError code: type: string enum: - invalidRequest message: type: string enum: - 잘못된 요청입니다. CaptureAuthenticationErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - authenticationError code: type: string enum: - authenticationRequired message: type: string enum: - 인증에 실패했습니다. CapturePermissionErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - permissionError code: type: string enum: - permissionDenied message: type: string enum: - 요청이 허용되지 않았습니다. CaptureNotFoundErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - notFoundError code: type: string enum: - resourceMissing message: type: string enum: - 결제 정보를 찾을 수 없습니다. CaptureExpiredErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - invalidRequestError code: type: string enum: - paymentCaptureExpired message: type: string enum: - 결제 캡처 가능 시간이 만료되었습니다. CaptureApiErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string enum: - apiError code: type: string enum: - internalError message: type: string enum: - 서버 내부 오류가 발생했습니다. CreatePaymentRefundRequest: type: object required: - refundAmount - refundTaxFreeAmount - refundVat - reason description: 취소할 금액과 세금 구성을 입력합니다. properties: refundAmount: type: integer minimum: 1 maximum: 9007199254740991 description: 취소할 총 금액 examples: - 10000 refundTaxFreeAmount: type: integer minimum: 0 maximum: 9007199254740991 description: 취소 금액에 포함된 면세 금액 examples: - 0 refundVat: type: integer minimum: 0 maximum: 9007199254740991 description: 취소 금액에 포함된 부가세 examples: - 909 reason: type: string maxLength: 200 description: 취소 사유 examples: - 고객 요청 PaymentRefundResponse: type: object required: - id - paymentSessionId - clientId - productName - status - amount - currency - taxFreeAmount - vat - fee - reason - createdAt - updatedAt properties: id: type: string description: 생성된 환불 항목 식별값 paymentSessionId: type: string description: 원 결제 세션 식별값 clientId: type: string description: 가맹점 클라이언트 식별값 productName: type: - string - "null" description: 원 결제 상품명 status: type: string enum: - completed amount: type: integer description: 완료된 취소 금액 currency: type: string enum: - KRW taxFreeAmount: type: integer description: 완료된 취소의 면세 금액 vat: type: integer description: 완료된 취소의 부가세 금액 fee: type: integer description: 취소 처리 수수료 reason: type: - string - "null" description: 취소 사유 createdAt: type: string format: date-time updatedAt: type: string format: date-time PaymentRefundFailure: type: - object - "null" required: - code - message properties: code: type: string enum: - refundMethodDeclined - refundMethodUnavailable - refundServiceUnavailable - refundRejected - refundFailed description: 취소 실패 코드 message: type: string description: 취소 실패 설명 PaymentRefundEntry: type: object required: - id - status - amount - currency - taxFreeAmount - vat - fee - reason - failure - createdAt - updatedAt properties: id: type: string description: 개별 취소 항목 식별값 status: type: string enum: - processing - completed - failed amount: type: integer description: 개별 취소 총액 currency: type: string enum: - KRW taxFreeAmount: type: integer description: 개별 취소의 면세 금액 vat: type: integer description: 개별 취소의 부가세 금액 fee: type: integer description: 개별 취소 처리 수수료 reason: type: - string - "null" description: 취소 사유 failure: $ref: "#/components/schemas/PaymentRefundFailure" createdAt: type: string format: date-time updatedAt: type: string format: date-time PaymentRefundStatusResponse: type: object required: - paymentSessionId - clientId - status - originalAmount - currency - refundableAmount - productName - canCreateRefund - refunds properties: paymentSessionId: type: string description: 원 결제 세션 식별값 clientId: type: string description: 가맹점 클라이언트 식별값 status: type: string enum: - refundable - processing - partiallyRefunded - fullyRefunded description: 결제 세션 단위의 전체 취소 상태 originalAmount: type: integer description: 원 결제 총액 currency: type: string enum: - KRW refundableAmount: type: integer description: 현재 추가로 취소할 수 있는 금액 productName: type: - string - "null" description: 원 결제 상품명 canCreateRefund: type: boolean description: 새 취소 요청 가능 여부 refunds: type: array description: 개별 취소 이력 items: $ref: "#/components/schemas/PaymentRefundEntry" PaymentSessionErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - code - message properties: type: type: string description: HTTP 상태에 대응하는 오류 유형 code: type: string description: 프로그램에서 분기할 오류 코드 message: type: string description: 사용자에게 표시할 수 있는 안전한 오류 메시지 eob: type: object additionalProperties: false description: EOB 점검으로 차단된 경우에만 포함되는 현재 날짜 구간 required: - startsAt - endsAt - timeZone properties: startsAt: type: string format: date-time description: 차단 구간 시작 시각(포함), UTC offset 포함 examples: - 2026-09-15T23:30:00+09:00 endsAt: type: string format: date-time description: 차단 구간 종료 시각(미포함), UTC offset 포함 examples: - 2026-09-16T00:30:00+09:00 timeZone: type: string description: 반복 점검 일정을 해석하는 IANA timezone examples: - Asia/Seoul CreateDelegationRequest: type: object additionalProperties: false required: - payer_id properties: payer_id: type: string maxLength: 128 pattern: "^payer:" description: 로그인한 회원의 `payerId`입니다. 호출한 가맹점 소속의 활성 구매자여야 합니다. examples: - payer:00000000000000000000000000 CreateDelegationResponse: type: object required: - delegation_id - expires_in - authorization_url properties: delegation_id: type: string description: 위임 인증 식별값입니다. examples: - dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw expires_in: type: integer description: 위임 인증의 유효 시간(초)입니다. examples: - 300 authorization_url: type: string format: uri description: 결제창에 전달할 URL입니다. 값을 바꾸지 말고 `widgets()`의 `brandpay.redirectUrl`로 그대로 전달하세요. examples: - https://auth.point3.io/delegated?delegation_id=dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw ErrorResponse: type: object required: - status - timestamp - result properties: status: type: integer examples: - 401 timestamp: type: string format: date-time examples: - 2026-07-23T00:00:00.000Z result: type: object required: - code - message properties: code: type: string examples: - UNAUTHORIZED message: type: string examples: - 인증 정보가 유효하지 않습니다. details: type: object additionalProperties: true description: 오류와 관련된 추가 정보