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.
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
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>
Create a Payment Session
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"
}
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"
Confirming Payment
To confirm the payment status after returning to the game:
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>
