> ## Documentation Index
> Fetch the complete documentation index at: https://galacticagames.mintlify.site/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](https://galacticagames.mintlify.site/payments.md#payment-flow) page.

***

## Setup

> [tab] 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] 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] 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] 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](https://galacticagames.mintlify.site/authentication.md) page for details on environments and base URLs.

***

## Create a Payment Session

> [tab] 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] 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] 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] 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"
> }
> ```

See the [Create Session](https://galacticagames.mintlify.site/api-reference/sessions/create.md) 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`](https://galacticagames.mintlify.site/api-reference/webhooks/payment.succeeded) webhook to your backend. This is the most reliable way to confirm payments.

See the [Webhooks](https://galacticagames.mintlify.site/webhooks.md) 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:

> [tab] TypeScript
>
> ```typescript theme={null}
> const status = await toffee.sessions.status({ id: "sess_123" });
>
> if (status.status === "paid") {
>   // Grant items
> }
> ```

> [tab] Python
>
> ```python theme={null}
> resp = await toffee.sessions.status(GetSessionStatusRequest(id="sess_123"))
>
> if resp.status == "paid":
>     # Grant items
> ```

> [tab] Go
>
> ```go theme={null}
> resp, err := toffee.Sessions.Status(ctx, &sdk.GetSessionStatusRequest{Id: "sess_123"})
>
> if resp.GetStatus() == "paid" {
>   // Grant items
> }
> ```

> [tab] API
>
> ```http theme={null}
> GET /v1/sessions/sess_123/status
> Authorization: Bearer <your_access_token>
> ```

See the [Payments](https://galacticagames.mintlify.site/payments.md#check-session-status) page for status handling details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.