Payments

Payment Flow

Available Payment Methods

ToffeePay supports the following payment methods:

card: Traditional credit/debit card payments
tokenized_card: Saved card tokens for returning customers
apple_pay: Apple Pay for iOS and Safari users
google_pay: Google Pay for Android and Chrome users
paypal: PayPal wallet payments
paylater: PayPal’s buy now, pay later options
venmo: Venmo wallet payments

The available payment methods are automatically displayed to users on the payment page based on their device, browser, and configured options for your game.

Create a Payment Session

Send a server-side request to create a payment session.

TypeScript
Python
Go
API

const { session } = await toffee.sessions.create({
  gameId: "space_shooter",
  userId: "player_42",
  item: {
    title: "50 Gold Coins",
    price: 499,
    currency: "USD",
    image: "data:image/png;base64,...",
  },
  returnUrl: "mygame://payment-complete",
  walletEnabled: true,
});

resp = await toffee.sessions.create(CreateSessionRequest(
    game_id="space_shooter",
    user_id="player_42",
    item=Item(
        title="50 Gold Coins",
        price=499,
        currency="USD",
        image="data:image/png;base64,...",
    ),
    return_url="mygame://payment-complete",
    wallet_enabled=True,
))
session = resp.session

resp, err := toffee.Sessions.Create(ctx, &sdk.CreateSessionRequest{
  GameId: "space_shooter",
  UserId: "player_42",
  Item: &sdk.Item{
    Title:    "50 Gold Coins",
    Price:    499,
    Currency: "USD",
    Image:    "data:image/png;base64,...",
  },
  ReturnUrl:     "mygame://payment-complete",
  WalletEnabled: true,
})
session := resp.GetSession()

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",
    "image": "data:image/png;base64,..."
  },
  "return_url": "mygame://payment-complete",
  "wallet_enabled": true
}

Parameters:

game_id: Your unique game identifier
user_id: Unique identifier for the player
item: The item being purchased
- title: Display name of the item
- price: Price in cents (e.g., 499 = \$4.99)
- currency: Three-letter currency code (USD, EUR, etc.)
- image: Base64-encoded image or URL
return_url: Deep link to return to after payment
wallet_enabled: Boolean flag that specifies whether Toffee Wallet should be enabled or disabled for the session

Response: A Session object with the payment URL.

{
  "id": "sess_abc123",
  "url": "https://pay.toffeepay.com/sess_abc123",
  "status": "pending",
  "user_id": "player_42",
  "game_id": "space_shooter",
  "item": {
    "title": "50 Gold Coins",
    "price": 499,
    "currency": "USD"
  },
  "created_at": "2023-06-01T12:00:00Z"
}

Payment Statuses

Session Statuses

Payment sessions can have the following statuses:

pending: Payment session created but not yet paid
paid: Payment successfully completed
failed: Payment attempt failed
cancelled: Payment session was cancelled
expired: Payment session has expired

Payment Statuses

Individual payment objects (created when processing a session) have these statuses:

processing: Payment is being processed by the payment provider
authorized: Payment has been authorized but not yet captured
succeeded: Payment completed successfully
cancelled: Authorized payment was cancelled before capture
failed: Payment processing failed

Status Flow:

Session starts as pending
When payment begins, a Payment object is created with status processing
Payment can transition to:
- authorized: Payment authorized but not captured
- succeeded: Payment completed successfully (either automatically or via Complete Payment)
- cancelled: Authorized payment was cancelled via Cancel Payment
- failed: Payment processing failed
Note: Whether payments automatically proceed from authorized to succeeded or require manual completion via Complete Payment is configured during game setup.
Session status updates based on final payment status:
- paid (if payment succeeded)
- cancelled (if session was cancelled manually via Cancel Session or after 3 cancelled payment attempts)
- failed (after 3 failed payment attempts)

Timestamp Fields

Both sessions and payments include relevant timestamp fields: Session timestamps:

created_at: When the session was created
paid_at: When the session was successfully paid (if applicable)
failed_at: When the session failed (if applicable)
expired_at: When the session expired (if applicable)
cancelled_at: When the session was cancelled (if applicable)

Payment timestamps:

created_at: When payment processing began
authorized_at: When payment was authorized (if applicable)
succeeded_at: When payment completed successfully (if applicable)
cancelled_at: When payment was cancelled (if applicable)
failed_at: When payment failed (if applicable)

Webhook Events

ToffeePay sends webhooks for the following payment-related events:

Session Events

session.created: When a payment session is created
session.paid: When a session is successfully paid
session.failed: When payment attempt related to this session fails
session.expired: When a session expires without payment
session.cancelled: When session is cancelled by user

Payment Events

payment.created: When a payment is created and processing begins
payment.authorized: When payment is authorized but not yet captured
payment.succeeded: When payment completes successfully
payment.cancelled: When an authorized payment is cancelled
payment.failed: When payment attempt fails

See the Webhooks page for implementation details and signature verification.

Open the Payment Page

Open the returned payment url in the browser or webview. The user will:

View the item details and total price
Pay using Apple Pay, Google Pay, or other supported methods
Be redirected back to your game via the return_url

Internationalization

You can customize the payment page language by adding a locale query parameter to the payment URL:

https://pay.toffeepay.com/sess_abc123?locale=es

The payment page will display all text (buttons, labels, error messages) in the specified language.

Handle Payment Notifications

ToffeePay notifies you of payment events through two methods:

Webhooks

When a payment is completed, ToffeePay sends a signed webhook to your backend. See the Webhooks page for detailed implementation. Sample Payload:

{
  "type": "payment.succeeded",
  "timestamp": "2023-06-01T12:05:00Z",
  "data": {
    // Payment object
  }
}

Return URL

After payment, the user is redirected to your specified return_url. This is typically a custom deep link that your game handles. Example:

"return_url": "mygame://payment-complete"

Frontend Events

The payment page emits events to the parent window via postMessage. This is useful for client-side integrations (e.g., if using an iframe or popup). Event Types: Payment Events (payload includes payment id):

toffeepay-payment-unreached
toffeepay-payment-success
toffeepay-payment-failed

Session Events (payload includes session id):

toffeepay-session-paid
toffeepay-session-failed
toffeepay-session-expired
toffeepay-session-cancelled
toffeepay-session-authorized

Cancel a Payment Session

You can cancel a payment session that is still in pending status:

TypeScript
Python
Go
API

await toffee.sessions.cancel({ id: "sess_abc123" });

await toffee.sessions.cancel(CancelSessionRequest(id="sess_abc123"))

err := toffee.Sessions.Cancel(ctx, &sdk.CancelSessionRequest{Id: "sess_abc123"})

POST /v1/sessions/sess_abc123/cancel
Authorization: Bearer <your_access_token>

When a session is cancelled:

The session status changes to cancelled
The cancelled_at timestamp is set
A session.cancelled webhook event is sent
The session cannot be paid and the payment URL becomes invalid

Check Session Status

To confirm session status (especially when handling return URLs), you can use either endpoint:

Get Session (Full Details)

TypeScript
Python
Go
API

const { session } = await toffee.sessions.get({ id: "sess_abc123" });

resp = await toffee.sessions.get(GetSessionRequest(id="sess_abc123"))
session = resp.session

resp, err := toffee.Sessions.Get(ctx, &sdk.GetSessionRequest{Id: "sess_abc123"})
session := resp.GetSession()

GET /v1/sessions/sess_abc123
Authorization: Bearer <your_access_token>

Response:

{
  "id": "sess_abc123",
  "url": "https://pay.toffeepay.com/sess_abc123",
  "status": "paid",
  "user_id": "player_42",
  "game_id": "space_shooter",
  "item": {
    "title": "50 Gold Coins",
    "price": 499,
    "currency": "USD"
  },
  "tax": {
    "amount": 50
  },
  "created_at": "2023-06-01T12:00:00Z",
  "paid_at": "2023-06-01T12:05:00Z"
}

Get Session Status (Status Only)

TypeScript
Python
Go
API

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

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

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

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

Response:

{
  "id": "sess_abc123",
  "status": "paid"
}

Status handling:

If status is paid, grant the items and show success
If status is pending, show a waiting screen
If status is failed, cancelled or expired, inform the user and offer to retry

Complete Payment

When your game wants to control when an authorized payment is captured, use Complete Payment. This is useful for scenarios where you want to authorize payment but only capture it after fulfilling the order (e.g., confirming item availability).

TypeScript
Python
Go
API

await toffee.payments.complete({ id: "pay_xyz789" });

await toffee.payments.complete(CompletePaymentRequest(id="pay_xyz789"))

err := toffee.Payments.Complete(ctx, &sdk.CompletePaymentRequest{Id: "pay_xyz789"})

POST /v1/payments/pay_xyz789/complete
Authorization: Bearer <your_access_token>

Cancel Payment

Cancel an authorized payment before it’s captured. This releases the hold on the customer’s payment method.

TypeScript
Python
Go
API

await toffee.payments.cancel({ id: "pay_xyz789" });

await toffee.payments.cancel(CancelPaymentRequest(id="pay_xyz789"))

err := toffee.Payments.Cancel(ctx, &sdk.CancelPaymentRequest{Id: "pay_xyz789"})

POST /v1/payments/pay_xyz789/cancel
Authorization: Bearer <your_access_token>

Get Payment Details

Retrieve details of a payment:

TypeScript
Python
Go
API

const { payment } = await toffee.payments.get({ id: "pay_xyz789" });

resp = await toffee.payments.get(GetPaymentRequest(id="pay_xyz789"))
payment = resp.payment

resp, err := toffee.Payments.Get(ctx, &sdk.GetPaymentRequest{Id: "pay_xyz789"})
payment := resp.GetPayment()

GET /v1/payments/pay_xyz789?with_extra_data=true
Authorization: Bearer <your_access_token>

Response:

{
  "id": "pay_xyz789",
  "session_id": "sess_abc123",
  "status": "succeeded",
  "amount": 499,
  "currency": "USD",
  "method": "apple_pay",
  "details": "50 Gold Coins",
  "created_at": "2023-06-01T12:05:00Z",
  "succeeded_at": "2023-06-01T12:05:30Z",
  "extra_data": {
    "real_amount": 499
  }
}

List Sessions

Retrieve historical sessions for audit and analytics:

TypeScript
Python
Go
API

const { sessions } = await toffee.sessions.list({
  gameId: "space_shooter",
  userId: "player_42",
});

resp = await toffee.sessions.list(ListSessionsRequest(
    game_id="space_shooter",
    user_id="player_42",
))
sessions = resp.sessions

resp, err := toffee.Sessions.List(ctx, &sdk.ListSessionsRequest{
  GameId: "space_shooter",
  UserId: "player_42",
})
sessions := resp.GetSessions()

GET /v1/sessions?game_id=space_shooter&user_id=player_42&status=paid&limit=50&offset=0
Authorization: Bearer <your_access_token>

Response:

[
  {
    "id": "sess_abc123",
    "status": "paid",
    "user_id": "player_42",
    "game_id": "space_shooter",
    "item": {
      "title": "50 Gold Coins",
      "price": 499,
      "currency": "USD"
    },
    "tax": {
      "amount": 50
    },
    "created_at": "2023-06-01T12:00:00Z",
    "paid_at": "2023-06-01T12:05:00Z"
  }
]

List Payments

Retrieve historical payments (successful transactions only):

TypeScript
Python
Go
API

const { payments } = await toffee.payments.list({
  gameId: "space_shooter",
  userId: "player_42",
});

resp = await toffee.payments.list(ListPaymentsRequest(
    game_id="space_shooter",
    user_id="player_42",
))
payments = resp.payments

resp, err := toffee.Payments.List(ctx, &sdk.ListPaymentsRequest{
  GameId: "space_shooter",
  UserId: "player_42",
})
payments := resp.GetPayments()

GET /v1/payments?game_id=space_shooter&user_id=player_42&limit=50&offset=0&with_extra_data=true
Authorization: Bearer <your_access_token>

Response:

[
  {
    "id": "pay_xyz789",
    "session_id": "sess_abc123",
    "status": "succeeded",
    "amount": 499,
    "currency": "USD",
    "method": "apple_pay",
    "details": "50 Gold Coins",
    "created_at": "2023-06-01T12:05:00Z",
    "succeeded_at": "2023-06-01T12:05:30Z",
    "extra_data": {
      "real_amount": 499
    }
  }
]

Tax Handling

ToffeePay automatically calculates and applies taxes based on the customer’s location. Tax information is included in session responses when the session is completed.

Tax Structure

The tax object in session responses contains:

amount: Tax amount in cents (same currency as the item price)

Example

For a \

4.99 item with \\

0.50 tax:

{
  "item": {
    "price": 499,
    "currency": "USD"
  },
  "tax": {
    "amount": 50
  }
}

The customer will be charged the total amount (item price + tax = \$5.49 in this example). Note: Tax calculations are handled automatically during payment processing. The tax amount is determined at the time of payment based on the customer’s billing address.

Image Requirements

Item images must meet these requirements:

Format: PNG, JPG, WebP
Size: ≤ 300 KB recommended
Encoding: Base64 with MIME prefix or direct URL

Base64 format:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

URL format:

https://yourgame.com/images/gold-coins.png

Best Practices

Authentication: See Authentication for access token management
Idempotency: Use Idempotency-Key header to prevent duplicate operations
Webhook verification: Always verify webhook signatures (see Webhooks)
Error handling: Implement proper error handling for all payment statuses
User experience: Show loading states and clear success/failure messages
Security: Use HTTPS for all webhook endpoints and return URLs
Testing: Use sandbox mode for development and testing

Error Handling

Common payment errors and how to handle them:

invalid_game_id: Check your game registration and access token (see Authentication)
invalid_currency: Ensure currency code is supported (USD, EUR, etc.)
invalid_price: Price must be a positive integer in cents
invalid_image: Check image format and size requirements
session_expired: Payment session has expired, create a new one
insufficient_funds: User’s payment method was declined

Testing

Use the Sandbox environment for development and testing. Test cards and OTP codes are available there.

Bootstrap

Core

Integration

Payment Flow

Available Payment Methods

Create a Payment Session

Payment Statuses

Session Statuses

Payment Statuses

Timestamp Fields

Webhook Events

Session Events

Payment Events

Open the Payment Page

Internationalization

Handle Payment Notifications

Webhooks

Return URL

Frontend Events

Cancel a Payment Session

Check Session Status

Get Session (Full Details)

Get Session Status (Status Only)

Complete Payment

Cancel Payment

Get Payment Details

List Sessions

List Payments

Tax Handling

Tax Structure

Example

Image Requirements

Best Practices

Error Handling

Testing

Bootstrap

Core

Integration

Documentation Index

​Payment Flow

​Available Payment Methods

​Create a Payment Session

​Payment Statuses

​Session Statuses

​Payment Statuses

​Timestamp Fields

​Webhook Events

​Session Events

​Payment Events

​Open the Payment Page

​Internationalization

​Handle Payment Notifications

​Webhooks

​Return URL

​Frontend Events

​Cancel a Payment Session

​Check Session Status

​Get Session (Full Details)

​Get Session Status (Status Only)

​Complete Payment

​Cancel Payment

​Get Payment Details

​List Sessions

​List Payments

​Tax Handling

​Tax Structure

​Example

​Image Requirements

​Best Practices

​Error Handling

​Testing

Payment Flow

Available Payment Methods

Create a Payment Session

Payment Statuses

Session Statuses

Payment Statuses

Timestamp Fields

Webhook Events

Session Events

Payment Events

Open the Payment Page

Internationalization

Handle Payment Notifications

Webhooks

Return URL

Frontend Events

Cancel a Payment Session

Check Session Status

Get Session (Full Details)

Get Session Status (Status Only)

Complete Payment

Cancel Payment

Get Payment Details

List Sessions

List Payments

Tax Handling

Tax Structure

Example

Image Requirements

Best Practices

Error Handling

Testing