결제 등록

인게임 결제 내역을 등록합니다. 등록된 결제는 유저의 부스트 중인 크리에이터에게 자동 귀속됩니다.

흐름

1. 인게임 결제 완료  →  2. API로 결제 정보 전송  →  3. 크리에이터 귀속 + 정산

요청

cURL
Node SDK
Go SDK

curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "transactionId": "txn_abc123",
    "productId": "gem_pack_100",
    "productName": "100 보석 팩",
    "amount": 9900,
    "currency": "KRW",
    "platform": "Android",
    "distributionType": "MOBILE_STORE",
    "purchasedAt": "2024-01-15T10:30:00.000Z"
  }'

const payment = await server.payments.create({
  userId: 'user_12345',
  transactionId: 'txn_abc123',
  productId: 'gem_pack_100',
  productName: '100 보석 팩',
  amount: 9900,
  currency: 'KRW',
  platform: 'Android',
  distributionType: 'MOBILE_STORE',
  purchasedAt: new Date('2024-01-15T10:30:00Z'),
});

purchasedAt, _ := time.Parse(time.RFC3339, "2024-01-15T10:30:00Z")

payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
    UserID:           "user_12345",
    TransactionID:    "txn_abc123",
    ProductID:        "gem_pack_100",
    ProductName:      playcamp.String("100 보석 팩"),
    Amount:           9900,
    Currency:         "KRW",
    Platform:         playcamp.PaymentPlatformAndroid,
    DistributionType: playcamp.String("MOBILE_STORE"),
    PurchasedAt:      purchasedAt,
})

응답 (201 Created)

{
  "data": {
    "id": 1234,
    "transactionId": "txn_abc123",
    "userId": "user_12345",
    "productId": "gem_pack_100",
    "productName": "100 보석 팩",
    "amount": 9900,
    "currency": "KRW",
    "platform": "Android",
    "campaignId": "campaign_001",
    "creatorKey": "ABC12",
    "status": "COMPLETED",
    "isRefund": false,
    "campaignCurrency": "KRW",
    "purchasedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:05.000Z"
  }
}

필수 파라미터

필드	타입	설명
`userId`	string	게임 내 유저 식별자
`transactionId`	string	플랫폼별 고유 거래 ID (중복 방지용)
`productId`	string	상품 ID
`amount`	number	결제 금액
`currency`	string	통화 코드 (ISO 4217: USD, KRW 권장)
`platform`	string	플랫폼 (iOS, Android, Web, Roblox, Other)

선택 파라미터

필드	타입	설명
`productName`	string	상품명
`distributionType`	string	유통 타입 (미전달 시 `platform`으로 자동 추론, 아래 참조)
`purchasedAt`	string	결제 시각 (ISO 8601, 미전달 시 서버 수신 시각, 아래 참조)
`netAmount`	number	스토어 수수료 차감 후 순금액
`netCurrency`	string	`netAmount`의 통화 코드 (ISO 4217)
`callbackId`	string	웹훅 추적용 ID (웹훅 이벤트에 포함됨)
`isTest`	boolean	테스트 모드 (실제 데이터 생성 안 함)

유통 타입

distributionType은 정산 계산에 사용됩니다. 미전달 시 platform 값으로 자동 추론됩니다.

값	설명	스토어 수수료
`MOBILE_STORE`	모바일 외부 스토어 (Google Play, App Store)	30%
`PC_STORE`	PC 외부 스토어 (Steam 등)	30%
`MOBILE_SELF_STORE`	모바일 자체 결제	0%
`PC_SELF_STORE`	PC 자체 스토어	0%

자동 추론 규칙

`platform`	추론되는 `distributionType`
`iOS`, `Android`	`MOBILE_STORE`
`Web`	`PC_SELF_STORE`
`Roblox`, `Other`	`PC_STORE`

자동 추론값이 실제 유통 채널과 다르면 정산 금액이 어긋납니다. 예를 들어 모바일 자체 결제(MOBILE_SELF_STORE)는 Android에서 MOBILE_STORE로 추론되어 스토어 수수료 30%가 잘못 적용됩니다. 추론값과 실제 채널이 다른 경우 반드시 명시적으로 전달하세요.

정산 계산: Net Amount = 결제금액 × (1 - 스토어 수수료) 후, PlayCamp 플랫폼 수수료와 크리에이터 수수료가 별도 적용됩니다.게임사가 스토어 수수료 차감 후 실제 정산받는 금액을 알고 있으면 netAmount/netCurrency로 함께 전달할 수 있습니다.

결제 시각 (purchasedAt)

정산 귀속은 항상 SDK API가 결제를 인지한 시점을 기준으로 합니다.

purchasedAt을 전달하면 그 값이 기록됩니다.
미전달 시 서버가 요청을 수신한 시각이 기록됩니다.
환불은 항상 서버 수신 시각으로 기록됩니다 (전달 불가).

정산 월 귀속이 이 시각을 기준으로 결정되므로, 결제·환불이 완료되면 즉시 API를 호출하세요. 월말에 처리한 건을 다음 달에 호출하면 다음 달 정산으로 귀속됩니다.

통화 변환

USD가 아닌 통화의 경우 자동으로 USD로 변환됩니다 (amountUsd 필드).

// KRW 결제 예시
{ amount: 9900, currency: "KRW" }
// → amountUsd: 7.62 (자동 계산)

결제 환불

cURL
Node SDK
Go SDK

curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments/txn_abc123/refund" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{}'

const refund = await server.payments.refund('txn_abc123');

payment, err := server.Payments.Refund(ctx, "txn_abc123", nil)

환불 시 정산에서 해당 금액이 차감됩니다.

에러 처리

HTTP	코드	설명
400	`VALIDATION_ERROR`	필수 파라미터 누락
409	`CONFLICT`	중복된 transactionId

벌크 결제

최대 1,000건의 결제를 한 번에 등록할 수 있습니다. 요청

cURL
Node SDK
Go SDK

curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments/bulk" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{
    "payments": [
      {
        "userId": "user_1",
        "transactionId": "txn_001",
        "productId": "gem_pack_100",
        "amount": 9900,
        "currency": "KRW",
        "platform": "iOS",
        "distributionType": "MOBILE_STORE",
        "purchasedAt": "2026-03-17T00:00:00Z"
      },
      {
        "userId": "user_2",
        "transactionId": "txn_002",
        "productId": "gem_pack_200",
        "amount": 19900,
        "currency": "KRW",
        "platform": "Android",
        "distributionType": "MOBILE_STORE",
        "purchasedAt": "2026-03-17T00:00:00Z"
      }
    ],
    "callbackId": "bulk-001"
  }'

const result = await server.payments.createBulk({
  payments: [
    {
      userId: 'user_1',
      transactionId: 'txn_001',
      productId: 'gem_pack_100',
      amount: 9900,
      currency: 'KRW',
      platform: 'iOS',
      distributionType: 'MOBILE_STORE',
      purchasedAt: '2026-03-17T00:00:00Z',
    },
    {
      userId: 'user_2',
      transactionId: 'txn_002',
      productId: 'gem_pack_200',
      amount: 19900,
      currency: 'KRW',
      platform: 'Android',
      distributionType: 'MOBILE_STORE',
      purchasedAt: '2026-03-17T00:00:00Z',
    },
  ],
  callbackId: 'bulk-001', // optional
});

console.log(result.totalRequested); // 2
console.log(result.successful);     // 성공 건수
console.log(result.failed);         // 실패 건수
console.log(result.skipped);        // 스킵 건수

purchasedAt, _ := time.Parse(time.RFC3339, "2026-03-17T00:00:00Z")

result, err := server.Payments.CreateBulk(ctx, playcamp.CreateBulkPaymentParams{
    Payments: []playcamp.CreatePaymentParams{
        {
            UserID:           "user_1",
            TransactionID:    "txn_001",
            ProductID:        "gem_pack_100",
            Amount:           9900,
            Currency:         "KRW",
            Platform:         playcamp.PaymentPlatformIOS,
            DistributionType: playcamp.String("MOBILE_STORE"),
            PurchasedAt:      purchasedAt,
        },
        {
            UserID:           "user_2",
            TransactionID:    "txn_002",
            ProductID:        "gem_pack_200",
            Amount:           19900,
            Currency:         "KRW",
            Platform:         playcamp.PaymentPlatformAndroid,
            DistributionType: playcamp.String("MOBILE_STORE"),
            PurchasedAt:      purchasedAt,
        },
    },
    CallbackID: "bulk-001", // optional
})

응답 (200 OK)

{
  "data": {
    "totalRequested": 2,
    "successful": 2,
    "failed": 0,
    "skipped": 0,
    "results": [
      {
        "transactionId": "txn_001",
        "status": "SUCCESS",
        "data": { "id": 1234, "transactionId": "txn_001", "userId": "user_1" }
      },
      {
        "transactionId": "txn_002",
        "status": "SUCCESS",
        "data": { "id": 1235, "transactionId": "txn_002", "userId": "user_2" }
      }
    ]
  }
}

벌크 결제 파라미터

필드	타입	설명
`payments`	array	결제 항목 배열 (최대 1,000건). 각 항목은 단건 결제와 동일한 필수 파라미터
`callbackId`	string	웹훅 추적용 ID (optional)
`isTest`	boolean	테스트 모드 (optional)

결과 상태

상태	설명
`SUCCESS`	결제 등록 성공
`SKIPPED`	이미 존재하는 transactionId (중복)
`FAILED`	등록 실패 (유효성 검증 오류 등)

벌크 결제는 부분 성공을 지원합니다. 일부 항목이 실패해도 나머지 항목은 정상 처리됩니다. 벌크 결제 완료 시 payment.bulk_created 웹훅 이벤트가 발생합니다.

플랫폼

개발사 가이드

크리에이터 가이드

결제 등록

흐름

결제 등록

필수 파라미터

선택 파라미터

유통 타입

결제 시각 (purchasedAt)

통화 변환

결제 환불

에러 처리

벌크 결제

벌크 결제 파라미터

결과 상태

​흐름

​결제 등록

​필수 파라미터

​선택 파라미터

​유통 타입

​결제 시각 (purchasedAt)

​통화 변환

​결제 환불

​에러 처리

​벌크 결제

​벌크 결제 파라미터

​결과 상태

흐름

결제 등록

필수 파라미터

선택 파라미터

유통 타입

결제 시각 (purchasedAt)

통화 변환

결제 환불

에러 처리

벌크 결제

벌크 결제 파라미터

결과 상태