> ## 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.

# Overview

> Architecture and getting started with PlayCamp SDK API integration

## Architecture

PlayCamp SDK API is integrated through the game server.

```mermaid theme={null}
flowchart LR
  subgraph Client
    A[Game Client]
  end
  subgraph YourCompany[Your Company]
    B[Game Server]
  end
  subgraph PlayCamp
    C[SDK API Server]
  end
  A <-->|UI Interaction| B
  B -->|API Calls| C
  C -.->|Webhook Events| B
```

### Role Distribution

| Component            | Role                                                                           |
| -------------------- | ------------------------------------------------------------------------------ |
| **Game Client**      | User interface (creator selection UI, coupon input screen, etc.)               |
| **Game Server**      | API calls, business logic processing, Server Key storage                       |
| **PlayCamp SDK API** | Data storage, settlement calculation, statistics aggregation, webhook delivery |

### Data Flow Example

<Steps>
  <Step title="Creator Selection">
    User selects a creator in the game
  </Step>

  <Step title="Boost Registration">
    Game server calls `POST /v1/server/sponsors`
  </Step>

  <Step title="In-game Payment">
    User makes an in-game payment
  </Step>

  <Step title="Payment Registration">
    Game server calls `POST /v1/server/payments`
  </Step>

  <Step title="Auto Attribution">
    SDK API automatically attributes the payment to the creator
  </Step>

  <Step title="Settlement">
    Creator revenue is calculated at end of month settlement
  </Step>
</Steps>

## Getting Started

### Required Integration APIs

Three Server APIs that **must be integrated** for campaign operation:

| Function            | API                      | Description                                         |
| ------------------- | ------------------------ | --------------------------------------------------- |
| **Create Boost**    | `POST /sponsors`         | User boosts a creator. Core for payment attribution |
| **Validate Coupon** | `POST /coupons/validate` | Validate coupon code                                |
| **Create Payment**  | `POST /payments`         | Register in-game payment. Base data for settlement  |

<Warning>
  **Integration verification required for campaign publishing.** Each of the 3 APIs above must be called at least once on the **Live** environment before your campaign can be published. Without this, the campaign approval screen will show:

  *"Game is not linked with PlayCamp. API integration required."*

  You can use `isTest: true` for these verification calls — test mode requests count toward integration verification while not saving any actual data.
</Warning>

**Integration verification flow:**

<Steps>
  <Step title="Integrate APIs">
    Implement the 3 required APIs in your game server
  </Step>

  <Step title="Call each API on Live">
    Make at least one request per API to the **Live** environment (`https://sdk-api.playcamp.io`). Using `isTest: true` is allowed.
  </Step>

  <Step title="Request campaign approval">
    Once all 3 APIs have been verified, request approval from the PlayCamp admin
  </Step>

  <Step title="Campaign published">
    After approval, the integration warning disappears and the campaign moves to published status
  </Step>
</Steps>

<Note>
  Campaign/Creator queries and webhooks can be integrated optionally.
</Note>

### API Key Issuance

Create a project on the PlayCamp platform to receive API keys.

| Key Type       | Purpose                     | Storage Location             |
| -------------- | --------------------------- | ---------------------------- |
| **Server Key** | All API calls (read/write)  | Game server (store securely) |
| **Client Key** | Query APIs only (read-only) | Game client (optional use)   |

<Warning>
  Never expose Server Key to the client.
</Warning>

### Authentication

All API requests use Bearer Token authentication.

```bash theme={null}
Authorization: Bearer {keyId}:{secret}
```

Example:

```bash theme={null}
Authorization: Bearer ak_server_abc123def456:xyz789secretkey
```

### Server Environments

| Environment | URL                                   | Purpose             |
| ----------- | ------------------------------------- | ------------------- |
| **Sandbox** | `https://sandbox-sdk-api.playcamp.io` | Development/Testing |
| **Live**    | `https://sdk-api.playcamp.io`         | Production          |

<Info>
  Use the Sandbox environment during development. Sandbox is completely isolated from Live.
</Info>

### Integration Flow

```
1. POST /sponsors          → User selects creator (boost)
2. POST /coupons/validate  → Validate coupon code
3. POST /payments          → Register when in-game payment occurs
```

## SDKs

For type-safe integration, use the official SDKs instead of raw HTTP calls:

<Tabs>
  <Tab title="Node SDK">
    ```bash theme={null}
    npm install @playcamp/node-sdk
    ```

    ```typescript theme={null}
    import { PlayCampServer } from '@playcamp/node-sdk';

    const server = new PlayCampServer('your_server_key:your_secret', {
      environment: 'sandbox',
    });
    ```

    See the [Node SDK guide](/guides/developers/game-integration/node-sdk) for full documentation.
  </Tab>

  <Tab title="Go SDK">
    ```bash theme={null}
    go get github.com/playcamp/playcamp-go-sdk
    ```

    ```go theme={null}
    import playcamp "github.com/playcamp/playcamp-go-sdk"

    server, err := playcamp.NewServer("your_server_key:your_secret",
        playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
    )
    ```

    See the [Go SDK guide](/guides/developers/game-integration/go-sdk) for full documentation.
  </Tab>
</Tabs>

## Test Mode

Before campaign launch, use `isTest: true` parameter to test API integration.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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": "test_user",
        "transactionId": "test_txn_001",
        "productId": "gem_pack_100",
        "amount": 9900,
        "currency": "KRW",
        "platform": "Android",
        "distributionType": "MOBILE_STORE",
        "purchasedAt": "2024-01-15T10:30:00.000Z",
        "isTest": true
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const server = new PlayCampServer('your_server_key:your_secret', {
      environment: 'sandbox',
      isTest: true,
    });

    const payment = await server.payments.create({
      userId: 'test_user',
      transactionId: 'test_txn_001',
      productId: 'gem_pack_100',
      amount: 9900,
      currency: 'KRW',
      platform: 'Android',
      distributionType: 'MOBILE_STORE',
      purchasedAt: new Date('2024-01-15T10:30:00Z'),
    });
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    server, _ := playcamp.NewServer("your_server_key:your_secret",
        playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
        playcamp.WithTestMode(true),
    )

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

    payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
        UserID:           "test_user",
        TransactionID:    "test_txn_001",
        ProductID:        "gem_pack_100",
        Amount:           9900,
        Currency:         "KRW",
        Platform:         playcamp.PaymentPlatformAndroid,
        DistributionType: playcamp.String("MOBILE_STORE"),
        PurchasedAt:      purchasedAt,
    })
    ```
  </Tab>
</Tabs>

**Test Mode Features:**

* Request parameter validation is performed identically to production
* Data is not saved to DB
* Returns mock response

<Note>
  **Recommended**: Use `isTest: true` when integrating before campaign launch. `isTest` can be used in both Sandbox and Live environments. Remove the `isTest` parameter for actual campaign operation.
</Note>

See [Test Mode](/guides/developers/game-integration/test-mode) for more details.