> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toffeepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Integrate ToffeePay in minutes

This guide walks you through:

1. [Setting up](#setup)
2. [Creating a payment session](#create-a-payment-session)
3. [Opening the payment page](#open-the-payment-page)
4. [Handling payment webhook](#handle-payment-webhook)
5. [Returning to game](#return-to-game)
6. [Confirming payment](#confirming-payment)

For a visual overview of the complete payment flow, see the [Payments](/payments#payment-flow) page.

***

## Setup

<Tabs>
  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @toffeepay/sdk
    ```

    ```typescript theme={null}
    import { Toffee } from "@toffeepay/sdk";

    const toffee = new Toffee({
      accessToken: "your-access-token",
      environment: "sandbox", // omit for production
    });
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install toffeepay-sdk
    ```

    ```python theme={null}
    from toffeepay import Toffee

    toffee = Toffee(
        access_token="your-access-token",
        environment="sandbox",  # omit for production
    )
    ```
  </Tab>

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

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

    toffee := sdk.New(sdk.Config{
      AccessToken: "your-access-token",
      Environment: sdk.Sandbox, // omit for production
    })
    ```
  </Tab>

  <Tab title="API">
    All requests to the ToffeePay API must include your access token in the `Authorization` header:

    ```http theme={null}
    Authorization: Bearer <your_access_token>
    ```

    See the [Authentication](/authentication) page for details on environments and base URLs.
  </Tab>
</Tabs>

***

## Create a Payment Session

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const session = await toffee.checkout({
      gameId: "space_shooter",
      userId: "player_42",
      item: { title: "50 Gold Coins", price: 499, currency: "USD" },
      returnUrl: "mygame://payment-complete",
    });

    console.log(session.url); // redirect the user here
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    session = await toffee.checkout(
        game_id="space_shooter",
        user_id="player_42",
        item=Item(title="50 Gold Coins", price=499, currency="USD"),
        return_url="mygame://payment-complete",
    )

    print(session.url)  # redirect the user here
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    session, err := toffee.Checkout(ctx, &sdk.CreateSessionRequest{
      GameId:    "space_shooter",
      UserId:    "player_42",
      Item:      &sdk.Item{Title: "50 Gold Coins", Price: 499, Currency: "USD"},
      ReturnUrl: "mygame://payment-complete",
    })

    fmt.Println(session.GetUrl()) // redirect the user here
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    POST /v1/sessions
    Authorization: Bearer <your_access_token>
    Content-Type: application/json

    {
      "game_id": "space_shooter",
      "user_id": "player_42",
      "item": { "title": "50 Gold Coins", "price": 499, "currency": "USD" },
      "return_url": "mygame://payment-complete"
    }
    ```
  </Tab>
</Tabs>

See the [Create Session](/api-reference/sessions/create) API reference for the full request/response schema.

***

## Open the Payment Page

Open the returned payment `url` in the browser.

The user will:

* View the list of items and total price
* Pay using Apple Pay or another supported method

***

## Handle Payment Webhook

Once payment is successful, ToffeePay sends a [`payment.succeeded`](/api-reference/webhooks/payment.succeeded) webhook to your backend. This is the most reliable way to confirm payments.

See the [Webhooks](/webhooks) page for signature verification and all available events.

***

## Return to Game

After a successful payment, the player is **redirected to your specified `return_url`**.

This is typically a **custom deep link** that your game handles to:

* Show a success screen
* Confirm the session was paid

**Example:**

```json theme={null}
"return_url": "mygame://payment-complete"
```

Make sure your mobile client is set up to **handle and parse this URI scheme**.

***

## Confirming Payment

To confirm the payment status after returning to the game:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const status = await toffee.sessions.status({ id: "sess_123" });

    if (status.status === "paid") {
      // Grant items
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.sessions.status(GetSessionStatusRequest(id="sess_123"))

    if resp.status == "paid":
        # Grant items
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Sessions.Status(ctx, &sdk.GetSessionStatusRequest{Id: "sess_123"})

    if resp.GetStatus() == "paid" {
      // Grant items
    }
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/sessions/sess_123/status
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

See the [Payments](/payments#check-session-status) page for status handling details.