> ## Documentation Index > Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # 벌크 결제 등록 > 최대 1,000건의 결제를 한 번에 등록합니다. **부분 성공:** 각 항목은 독립적으로 처리되며 SUCCESS/SKIPPED/FAILED 상태를 반환합니다. 기존 transactionId가 존재하면 SKIPPED 처리됩니다. ## OpenAPI ````yaml /api_docs/openapi-ko.yaml post /v1/server/payments/bulk openapi: 3.0.3 info: title: PlayCamp SDK API description: | PlayCamp SDK API - 게임 분석 및 크리에이터 캠페인 연동 API ## 필수 연동 API (Server API) 캠페인 진행을 위해 반드시 연동해야 하는 API 3개: - `POST /v1/server/sponsors` - 유저가 크리에이터를 부스트 - `POST /v1/server/coupons/validate` - 쿠폰 코드 유효성 검사 - `POST /v1/server/payments` - 인게임 결제 등록 ## 인증 방식 - **Client API**: `Authorization: Bearer {CLIENT_KEY_ID}:{CLIENT_SECRET}` - **Server API**: `Authorization: Bearer {SERVER_KEY_ID}:{SERVER_SECRET}` ## 서버 - **Live**: https://sdk-api.playcamp.io (실제 데이터) - **Sandbox**: https://sandbox-sdk-api.playcamp.io (테스트 데이터) ## 키 타입 - **Client 키**: 게임 클라이언트용 (읽기 전용 - 캠페인, 크리에이터 조회) - **Server 키**: 게임 서버용 (읽기/쓰기 - 쿠폰 사용, 결제 등록 등) ## 테스트 모드 (isTest) 캠페인 실행 전에 `isTest: true` 파라미터를 사용하여 API 연동을 테스트할 수 있습니다. - 요청 파라미터 검증은 실제와 동일하게 수행 - 모의 데이터를 반환하며 실제 DB에 기록되지 않음 - 캠페인 시작 전 Sandbox 환경에서 연동 검증 후, 실제 캠페인 시 `isTest` 파라미터 제거 version: 1.1.0 contact: name: PlayCamp Support servers: - url: https://sdk-api.playcamp.io description: Live Server - url: https://sandbox-sdk-api.playcamp.io description: Sandbox Server - url: http://localhost:3001 description: Local Live Server - url: http://localhost:3003 description: Local Sandbox Server security: [] tags: - name: Health description: 서버 상태 확인 - name: Client Campaign description: 캠페인 조회 (Client API) - name: Client Creator description: 크리에이터 조회 (Client API) - name: Client Coupon description: 쿠폰 유효성 검사 (Client API) - name: Client Sponsor description: 부스트 상태 조회 — Sponsor API (Client API) - name: Server Campaign description: 캠페인 조회 (Server API) - name: Server Creator description: 크리에이터 조회 (Server API) - name: Server Coupon description: 쿠폰 관리 (Server API) - name: Server Sponsor description: 부스트 관리 — Sponsor API (Server API) - name: Server Payment description: 결제 관리 (Server API) - name: Server Playtime description: 플레이타임 세션 관리 (Server API) - name: Server Webhook description: 웹훅 관리 (Server API) - name: Server Webview description: WebView 관리 (Server API) paths: /v1/server/payments/bulk: post: tags: - Server Payment summary: 벌크 결제 등록 description: | 최대 1,000건의 결제를 한 번에 등록합니다. **부분 성공:** 각 항목은 독립적으로 처리되며 SUCCESS/SKIPPED/FAILED 상태를 반환합니다. 기존 transactionId가 존재하면 SKIPPED 처리됩니다. operationId: serverCreateBulkPayment requestBody: required: true content: application/json: schema: type: object required: - payments properties: payments: type: array maxItems: 1000 items: type: object required: - userId - transactionId - productId - amount - currency - platform - distributionType - purchasedAt properties: userId: type: string transactionId: type: string productId: type: string productName: type: string amount: type: number minimum: 0.01 currency: type: string pattern: ^[A-Z]{3}$ platform: type: string enum: - iOS - Android - Web - Roblox - Other distributionType: type: string enum: - MOBILE_STORE - MOBILE_SELF_STORE - PC_STORE - PC_SELF_STORE purchasedAt: type: string format: date-time callbackId: type: string description: 웹훅 추적용 ID isTest: type: boolean default: false description: 테스트 모드 (실제 데이터 생성 안 함) responses: '200': description: 성공 content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/BulkPaymentResult' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' security: - ServerAuth: [] components: schemas: BulkPaymentResult: type: object description: 벌크 결제 결과 properties: totalRequested: type: integer description: 요청한 결제 항목 수 successful: type: integer description: 성공한 결제 수 failed: type: integer description: 실패한 결제 수 skipped: type: integer description: 스킵된 결제 수 (중복 transactionId) results: type: array items: type: object properties: transactionId: type: string status: type: string enum: - SUCCESS - SKIPPED - FAILED data: $ref: '#/components/schemas/Payment' error: type: string description: 에러 메시지 (FAILED 상태일 때만) Payment: type: object properties: id: type: integer transactionId: type: string userId: type: string productId: type: string productName: type: string amount: type: number currency: type: string amountUsd: type: number description: USD 환산 금액 (자동 계산) platform: type: string enum: - iOS - Android - Web - Roblox - Other distributionType: type: string enum: - MOBILE_STORE - MOBILE_SELF_STORE - PC_STORE - PC_SELF_STORE description: | 유통 타입 (스토어 수수료 결정): - `MOBILE_STORE`: 모바일 외부 스토어 (Google Play, App Store) - 30% - `PC_STORE`: PC 외부 스토어 (Steam 등) - 30% - `MOBILE_SELF_STORE`: 모바일 자체 결제 - 0% - `PC_SELF_STORE`: PC 자체 스토어 - 0% status: type: string enum: - COMPLETED - REFUNDED campaignId: type: string creatorKey: type: string purchasedAt: type: string format: date-time createdAt: type: string format: date-time ValidationError: type: object required: - status - error - message - code - details properties: status: type: integer example: 400 error: type: string example: Bad Request message: type: string example: Validation failed code: type: string example: VALIDATION_ERROR details: type: array items: type: object properties: path: type: string description: 오류가 발생한 필드 경로 message: type: string description: 오류 메시지 example: - path: userId message: Required - path: amount message: Expected number, received string Error: type: object required: - status - error - message - code properties: status: type: integer description: HTTP 상태 코드 error: type: string description: HTTP 상태 이름 message: type: string description: 상세 에러 메시지 code: type: string description: | 에러 코드: - `VALIDATION_ERROR`: 요청 파라미터 검증 실패 - `BAD_REQUEST`: 잘못된 요청 - `UNAUTHORIZED`: 인증 실패 (API 키 오류) - `FORBIDDEN`: 권한 없음 - `NOT_FOUND`: 리소스를 찾을 수 없음 - `CONFLICT`: 중복 리소스 (이미 존재) - `INTERNAL_ERROR`: 서버 내부 오류 details: type: array description: 검증 오류 상세 (VALIDATION_ERROR의 경우) items: type: object properties: path: type: string message: type: string example: status: 404 error: Not Found message: 'Payment not found: txn-12345' code: NOT_FOUND responses: ValidationError: description: 요청 파라미터 검증 실패 content: application/json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: 인증 실패 (API 키 오류) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 401 error: Unauthorized message: Invalid API key code: UNAUTHORIZED securitySchemes: ServerAuth: type: http scheme: bearer description: 'Server API Key (format: {keyId}:{secret})' ````