Getting Started

This guide walks you through:

Setting up
Creating a payment session
Opening the payment page
Handling payment webhook
Returning to game
Confirming payment

For a visual overview of the complete payment flow, see the Payments page.

Setup

TypeScript
Python
Go
API

npm install @toffeepay/sdk

import { Toffee } from "@toffeepay/sdk";

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

pip install toffeepay-sdk

from toffeepay import Toffee

toffee = Toffee(
    access_token="your-access-token",
    environment="sandbox",  # omit for production
)

go get github.com/toffeepay/sdk-go

import sdk "github.com/toffeepay/sdk-go"

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

All requests to the ToffeePay API must include your access token in the Authorization header:

Authorization: Bearer <your_access_token>

See the Authentication page for details on environments and base URLs.

Create a Payment Session

TypeScript
Python
Go
API

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

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

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

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 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 webhook to your backend. This is the most reliable way to confirm payments. See the 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:

"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:

TypeScript
Python
Go
API

const status = await toffee.sessions.status({ id: "sess_123" });

if (status.status === "paid") {
  // Grant items
}

resp = await toffee.sessions.status(GetSessionStatusRequest(id="sess_123"))

if resp.status == "paid":
    # Grant items

resp, err := toffee.Sessions.Status(ctx, &sdk.GetSessionStatusRequest{Id: "sess_123"})

if resp.GetStatus() == "paid" {
  // Grant items
}

GET /v1/sessions/sess_123/status
Authorization: Bearer <your_access_token>

See the Payments page for status handling details.

Bootstrap

Core

Integration

Getting Started

Setup

Create a Payment Session

Open the Payment Page

Handle Payment Webhook

Return to Game

Confirming Payment

​Setup

​Create a Payment Session

​Open the Payment Page

​Handle Payment Webhook

​Return to Game

​Confirming Payment

Setup

Create a Payment Session

Open the Payment Page

Handle Payment Webhook

Return to Game

Confirming Payment