Payment Registration

Flow

1. In-game payment complete  →  2. Send payment info via API  →  3. Creator attribution + settlement

Create Payment

Request

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 Gem Pack",
    "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 Gem Pack',
  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 Gem Pack"),
    Amount:           9900,
    Currency:         "KRW",
    Platform:         playcamp.PaymentPlatformAndroid,
    DistributionType: playcamp.String("MOBILE_STORE"),
    PurchasedAt:      purchasedAt,
})

Response (201 Created)

{
  "data": {
    "id": 1234,
    "transactionId": "txn_abc123",
    "userId": "user_12345",
    "productId": "gem_pack_100",
    "productName": "100 Gem Pack",
    "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"
  }
}

Required Parameters

Field	Type	Description
`userId`	string	In-game user identifier
`transactionId`	string	Platform-specific unique transaction ID (for deduplication)
`productId`	string	Product ID
`amount`	number	Payment amount
`currency`	string	Currency code (ISO 4217: USD, KRW recommended)
`platform`	string	Platform (iOS, Android, Web, Roblox, Other)

Optional Parameters

Field	Type	Description
`productName`	string	Product name
`distributionType`	string	Distribution type (inferred from `platform` when omitted, see below)
`purchasedAt`	string	Payment timestamp (ISO 8601, server receive time when omitted, see below)
`netAmount`	number	Net amount after store fees
`netCurrency`	string	Currency code of `netAmount` (ISO 4217)
`callbackId`	string	Webhook tracking ID (included in webhook events)
`isTest`	boolean	Test mode (does not create actual data)

Distribution Type

distributionType is used for settlement calculation. When omitted, it is inferred from platform.

Value	Description	Store Fee
`MOBILE_STORE`	Mobile external store (Google Play, App Store)	30%
`PC_STORE`	PC external store (Steam, etc.)	30%
`MOBILE_SELF_STORE`	Mobile self-payment	0%
`PC_SELF_STORE`	PC self-published store	0%

Inference rules

`platform`	Inferred `distributionType`
`iOS`, `Android`	`MOBILE_STORE`
`Web`	`PC_SELF_STORE`
`Roblox`, `Other`	`PC_STORE`

If the inferred value does not match your actual distribution channel, settlement amounts will be wrong. For example, mobile self-payment (MOBILE_SELF_STORE) is inferred as MOBILE_STORE on Android, incorrectly applying a 30% store fee. Always send the value explicitly when it differs from the inferred one.

Settlement Calculation: Net Amount = Payment Amount × (1 - Store Fee), then PlayCamp platform fee and creator fee are applied separately.If your game server already knows the net amount it receives after store fees, you can send it as netAmount/netCurrency.

Payment Timestamp (purchasedAt)

Settlement is always attributed to the moment the SDK API recorded the payment.

When purchasedAt is provided, that value is stored.
When omitted, the server stores the time it received the request.
Refunds always use the server receive time (the value cannot be supplied).

The settlement month is determined by this timestamp, so call the API as soon as a payment or refund completes. A transaction processed at the end of a month but reported the next day is attributed to the next month’s settlement.

Currency Conversion

For non-USD currencies, amount is automatically converted to USD (amountUsd field).

// KRW payment example
{ amount: 9900, currency: "KRW" }
// → amountUsd: 7.62 (auto-calculated)

Refund Payment

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)

Refunded amounts are deducted from settlement.

Error Handling

HTTP	Code	Description
400	`VALIDATION_ERROR`	Missing required parameter
409	`CONFLICT`	Duplicate transactionId

Bulk Payment

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);     // successful count
console.log(result.failed);         // failed count
console.log(result.skipped);        // skipped count

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
})

Response (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" }
      }
    ]
  }
}

Bulk Payment Parameters

Field	Type	Description
`payments`	array	Payment items array (max 1,000). Each item has the same required parameters as single payment
`callbackId`	string	Webhook tracking ID (optional)
`isTest`	boolean	Test mode (optional)

Result Status

Status	Description
`SUCCESS`	Payment registered successfully
`SKIPPED`	Already existing transactionId (duplicate)
`FAILED`	Registration failed (validation error, etc.)

Bulk payments support partial success. Even if some items fail, the remaining items are processed normally. A payment.bulk_created webhook event is triggered when the bulk payment completes.

Platform

For Developers

For Creators

Flow

Create Payment

Required Parameters

Optional Parameters

Distribution Type

Payment Timestamp (purchasedAt)

Currency Conversion

Refund Payment

Error Handling

Bulk Payment

Bulk Payment Parameters

Result Status

​Flow

​Create Payment

​Required Parameters

​Optional Parameters

​Distribution Type

​Payment Timestamp (purchasedAt)

​Currency Conversion

​Refund Payment

​Error Handling

​Bulk Payment

​Bulk Payment Parameters

​Result Status

Flow

Create Payment

Required Parameters

Optional Parameters

Distribution Type

Payment Timestamp (purchasedAt)

Currency Conversion

Refund Payment

Error Handling

Bulk Payment

Bulk Payment Parameters

Result Status