### Install

Source: https://docs.toffeepay.com/sdks/go

Install the ToffeePay Go SDK using go get.

```APIDOC
## Install

```bash
go get github.com/toffeepay/sdk-go
```
```

--------------------------------

### Install Go SDK

Source: https://docs.toffeepay.com/sdks/go

Use the go get command to install the ToffeePay SDK for Go.

```bash
go get github.com/toffeepay/sdk-go
```

--------------------------------

### Setup Go SDK

Source: https://docs.toffeepay.com/getting-started

Install the Go SDK and initialize the Toffee client with an access token and sandbox environment. Omit the environment option for production.

```bash
go get github.com/toffeepay/sdk-go
```

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

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

--------------------------------

### Setup Python SDK

Source: https://docs.toffeepay.com/getting-started

Install the Python SDK and initialize the Toffee client with an access token and sandbox environment. Omit the environment option for production.

```bash
pip install toffeepay-sdk
```

```python
from toffeepay import Toffee

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

--------------------------------

### Setup TypeScript SDK

Source: https://docs.toffeepay.com/getting-started

Install the TypeScript SDK and initialize the Toffee client with an access token and sandbox environment. Omit the environment option for production.

```bash
npm install @toffeepay/sdk
```

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

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

--------------------------------

### Installation

Source: https://docs.toffeepay.com/sdks/python

Install the ToffeePay SDK via pip.

```APIDOC
## Install

```bash
pip install toffeepay-sdk
```
```

--------------------------------

### Install ToffeePay SDK with pip

Source: https://docs.toffeepay.com/sdks/python

Install the ToffeePay Python SDK using pip.

```bash
pip install toffeepay-sdk
```

--------------------------------

### Get Account Response JSON

Source: https://docs.toffeepay.com/wallet

Example JSON response for the Get Account endpoint. Shows the account object with id, users array, currency, and balance split into real and bonus amounts.

```json
{
  "id": "acc_xyz123",
  "users": [
    { "game_id": "space_shooter", "user_id": "player_42" }
  ],
  "currency": "USD",
  "balance": {
    "real": 2499,
    "bonus": 500
  }
}
```

--------------------------------

### Install @toffeepay/sdk

Source: https://docs.toffeepay.com/sdks/typescript

Install the ToffeePay TypeScript SDK via npm.

```bash
npm install @toffeepay/sdk
```

--------------------------------

### Get Session (Full Details) - Response

Source: https://docs.toffeepay.com/payments

Example JSON response for the Get Session endpoint, showing a paid session with full details including item, tax, and timestamps.

```json
{
  "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 Payment Details - JSON Response

Source: https://docs.toffeepay.com/payments

Example JSON response for the get payment operation, showing payment details including status, amount, and extra_data.

```json
{
  "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 Example - JSON

Source: https://docs.toffeepay.com/payments

Example of a tax object in a session response for a $4.99 item with $0.50 tax. The `amount` field is in cents. The customer is charged the total amount (item price + tax).

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

--------------------------------

### Return URL deep link example

Source: https://docs.toffeepay.com/getting-started

Example of a custom deep link used as the return_url after a successful payment. The player is redirected to this URI, and the mobile client must be set up to handle and parse this scheme.

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

--------------------------------

### Image URL Format Example

Source: https://docs.toffeepay.com/payments

Shows the alternative format for providing an item image via a direct URL. Use this when the image is hosted externally.

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

--------------------------------

### Use different idempotency keys per operation

Source: https://docs.toffeepay.com/idempotency

TypeScript example showing good practice of using distinct keys for different operations, and a bad example of reusing the same key.

```typescript
// Good: Different keys for different operations
const sessionKey = `session-${userId}-${itemId}-${Date.now()}`;
const refundKey = `refund-${paymentId}-${Date.now()}`;

// Bad: Reusing the same key across different operations
const key = "my-operation-key"; // Don't do this
```

--------------------------------

### Account resource methods

Source: https://docs.toffeepay.com/sdks/typescript

Account resource methods: get and list.

```typescript
const { account } = await toffee.accounts.get({ id: "acc_123" });
const { accounts } = await toffee.accounts.list({ gameId: "game_1" });
```

--------------------------------

### Get Account by ID (TypeScript, Python, Go, API)

Source: https://docs.toffeepay.com/wallet

Retrieve account details by ID using the Toffee Wallet SDK. The TypeScript, Python, and Go examples call the accounts.get method with an account ID, while the API example shows the corresponding HTTP GET request. The response includes the account's balance split into real and bonus funds.

```typescript
const { account } = await toffee.accounts.get({ id: "acc_xyz123" });
```

```python
resp = await toffee.accounts.get(GetAccountRequest(id="acc_xyz123"))
account = resp.account
```

```go
resp, err := toffee.Accounts.Get(ctx, &sdk.GetAccountRequest{Id: "acc_xyz123"})
account := resp.GetAccount()
```

```http
GET /v1/accounts/acc_xyz123
Authorization: Bearer <your_access_token>
```

--------------------------------

### Expose Local Server with ngrok for Webhook Testing

Source: https://docs.toffeepay.com/sandbox

Command to start ngrok and create a public URL forwarding to local port 3000, used for receiving sandbox webhooks.

```bash
ngrok http 3000
```

--------------------------------

### Get Session Status (Status Only) - Response

Source: https://docs.toffeepay.com/payments

Example JSON response for the Get Session Status endpoint, showing a paid session with only the id and status fields.

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

--------------------------------

### List Accounts by Game ID (TypeScript, Python, Go, API)

Source: https://docs.toffeepay.com/wallet

List accounts for a game using the Toffee Wallet SDK. The TypeScript, Python, and Go examples call the accounts.list method with a game ID, while the API example shows the corresponding HTTP GET request with query parameters for pagination.

```typescript
const { accounts } = await toffee.accounts.list({ gameId: "space_shooter" });
```

```python
resp = await toffee.accounts.list(ListAccountsRequest(game_id="space_shooter"))
accounts = resp.accounts
```

```go
resp, err := toffee.Accounts.List(ctx, &sdk.ListAccountsRequest{
  GameId: "space_shooter",
})
accounts := resp.GetAccounts()
```

```http
GET /v1/accounts?game_id=space_shooter&limit=100&offset=0
Authorization: Bearer <your_access_token>
```

--------------------------------

### List Disputes - Go

Source: https://docs.toffeepay.com/disputes

Server-side Go example using the ToffeePay SDK to list disputes with a ListDisputesRequest, filtering by payment ID and limiting results.

```go
paymentId := "pay_xyz789"
limit := int32(50)
resp, err := toffee.Disputes.List(ctx, &sdk.ListDisputesRequest{
  PaymentId: &paymentId,
  Limit:     &limit,
})
disputes := resp.GetDisputes()
```

--------------------------------

### Deposit resource methods

Source: https://docs.toffeepay.com/sdks/typescript

Deposit resource methods: get and list.

```typescript
const { deposit } = await toffee.deposits.get({ id: "dep_123" });
const { deposits } = await toffee.deposits.list({ gameId: "game_1" });
```

--------------------------------

### Refund resource methods

Source: https://docs.toffeepay.com/sdks/typescript

Refund resource methods: create, get, and list.

```typescript
const { refund } = await toffee.refunds.create({ paymentId: "pay_123" });
const { refund } = await toffee.refunds.get({ id: "ref_123" });
const { refunds } = await toffee.refunds.list({ paymentId: "pay_123" });
```

--------------------------------

### Create a payment session with the Toffee SDK (Go)

Source: https://docs.toffeepay.com/payments

Use the Go SDK to create a payment session. The example uses sdk.CreateSessionRequest and sdk.Item structs, with camelCase field names. The response is obtained via resp.GetSession().

```go
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()
```

--------------------------------

### Session resource methods

Source: https://docs.toffeepay.com/sdks/typescript

Session resource methods: create, get, status, list, and cancel.

```typescript
const { session } = await toffee.sessions.create({ ... });
const { session } = await toffee.sessions.get({ id: "sess_123" });
const { status }  = await toffee.sessions.status({ id: "sess_123" });
const { sessions } = await toffee.sessions.list({ gameId: "game_1" });
await toffee.sessions.cancel({ id: "sess_123" });
```

--------------------------------

### Payment session response (JSON)

Source: https://docs.toffeepay.com/payments

Example response from creating a payment session. Contains the session ID, payment URL, status, user and game IDs, item details, and creation timestamp.

```json
{
  "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"
}
```

--------------------------------

### List Disputes - Python

Source: https://docs.toffeepay.com/disputes

Server-side Python example using the ToffeePay SDK to list disputes with a ListDisputesRequest, filtering by payment ID and limiting results.

```python
resp = await toffee.disputes.list(ListDisputesRequest(
    payment_id="pay_xyz789",
    limit=50,
))
disputes = resp.disputes
```

--------------------------------

### Create a payment session with the Toffee SDK (Python)

Source: https://docs.toffeepay.com/payments

Use the Python SDK to create a payment session. The example uses CreateSessionRequest and Item objects, with snake_case parameter names. The response is accessed via resp.session.

```python
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
```

--------------------------------

### List Accounts Response JSON

Source: https://docs.toffeepay.com/wallet

Example JSON response for the List Accounts endpoint. Shows an array of account objects, each with id, users, currency, and balance split into real and bonus amounts.

```json
[
  {
    "id": "acc_xyz123",
    "users": [
      { "game_id": "space_shooter", "user_id": "player_42" }
    ],
    "currency": "USD",
    "balance": {
      "real": 2499,
      "bonus": 500
    }
  }
]
```

--------------------------------

### Base64 Image Format Example

Source: https://docs.toffeepay.com/payments

Shows the required format for embedding an image as a Base64 string with a MIME prefix. Use this when providing item images directly in the request payload.

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

--------------------------------

### Create a payment session with the Toffee SDK (TypeScript)

Source: https://docs.toffeepay.com/payments

Use the TypeScript SDK to create a payment session. The example sets gameId, userId, item details, returnUrl, and walletEnabled. The response contains the session object with the payment URL.

```typescript
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,
});
```

--------------------------------

### List Disputes - TypeScript

Source: https://docs.toffeepay.com/disputes

Server-side TypeScript example using the ToffeePay SDK to list disputes, filtering by payment ID and limiting results.

```typescript
const { disputes } = await toffee.disputes.list({
  paymentId: "pay_xyz789",
  limit: 50,
});
```

--------------------------------

### Get Payment Details - REST API

Source: https://docs.toffeepay.com/payments

Sends a GET request to the ToffeePay REST API to retrieve a payment by ID. The 'with_extra_data' query parameter includes additional data in the response.

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

--------------------------------

### Deposit resource operations

Source: https://docs.toffeepay.com/sdks/python

Get and list deposits using the deposits resource.

```python
resp = await toffee.deposits.get(GetDepositRequest(id="dep_123"))
deposit = resp.deposit

resp = await toffee.deposits.list(ListDepositsRequest(account_id="acc_123"))
deposits = resp.deposits
```

--------------------------------

### Account resource operations

Source: https://docs.toffeepay.com/sdks/python

Get and list accounts using the accounts resource.

```python
resp = await toffee.accounts.get(GetAccountRequest(id="acc_123"))
account = resp.account

resp = await toffee.accounts.list(ListAccountsRequest(game_id="game_1"))
accounts = resp.accounts
```

--------------------------------

### GET /v1/accounts

Source: https://docs.toffeepay.com/api-reference/accounts/list

Lists accounts. Requires a game_id query parameter. Returns an array of account objects with id, users, currency, and balance.

```APIDOC
## GET /v1/accounts

### Description
List accounts

### Method
GET

### Endpoint
/v1/accounts

### Parameters
#### Query Parameters
- **game_id** (string) - Required - The game identifier to filter accounts.
- **user_id** (string) - Optional - The user identifier to filter accounts.
- **limit** (integer, int32) - Optional - Maximum number of accounts to return. Default: 100. Maximum: 250. Must be greater than 0.
- **offset** (integer, int32) - Optional - Number of accounts to skip. Minimum: 0.
- **from** (string, date-time) - Optional - Start date for filtering accounts.
- **to** (string, date-time) - Optional - End date for filtering accounts.

### Response
#### Success Response (200)
Returns an array of account objects. Each account has the following properties:
- **id** (string) - Required - Account identifier.
- **users** (array of GameUser) - Optional - All game users linked to this account. Each GameUser has:
  - **game_id** (string) - Required - Game identifier.
  - **user_id** (string) - Required - User identifier.
- **currency** (string) - Required - Currency of the account. Enum: USD, GBP, EUR.
- **balance** (Balance) - Required - Balance details. Contains:
  - **real** (integer, int32) - Optional - Real balance. Minimum: 0.
  - **bonus** (integer, int32) - Optional - Bonus balance. Minimum: 0.

#### Response Example
```json
[
  {
    "id": "string",
    "users": [
      {
        "game_id": "string",
        "user_id": "string"
      }
    ],
    "currency": "USD",
    "balance": {
      "real": 0,
      "bonus": 0
    }
  }
]
```

### Authentication
Bearer token (JWT) required.
```

--------------------------------

### OpenAPI Specification for GET /v1/deposits/{id}

Source: https://docs.toffeepay.com/api-reference/deposits/get

Defines the GET /v1/deposits/{id} endpoint, including request parameters, response schema, and security scheme. The response includes deposit fields such as status, amount, currency, and method. The status can be processing, authorized, cancelled, succeeded, failed, or refunded.

```yaml
openapi: 3.1.0
info:
  title: ToffeePay API
  description: Public API for game partners
  version: 0.2.0
servers:
  - url: https://api.toffeepay.com
    description: Production
  - url: https://api.sandbox.toffeepay.com
    description: Sandbox
security:
  - BearerAuth: []
paths:
  /v1/deposits/{id}:
    get:
      summary: GetDeposit
      description: Returns deposit details by its id
      operationId: AccountService_GetDeposit
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet.v1.Deposit'
                title: deposit
components:
  schemas:
    wallet.v1.Deposit:
      type: object
      properties:
        id:
          type: string
          title: id
        account_id:
          type: string
          title: account_id
        status:
          type: string
          title: status
          enum:
            - processing
            - authorized
            - cancelled
            - succeeded
            - failed
            - refunded
        amount:
          type: integer
          title: amount
          minimum: 0
          format: int32
        currency:
          type: string
          title: currency
          enum:
            - USD
            - GBP
            - EUR
        method:
          type: string
          title: method
          enum:
            - card
            - tokenized_card
            - apple_pay
            - google_pay
        details:
          type: string
          title: details
        created_at:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
        authorized_at:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: authorized_at
        cancelled_at:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: cancelled_at
        succeeded_at:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: succeeded_at
        failed_at:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: failed_at
        refunded_at:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: refunded_at
      title: Deposit
      required:
        - id
        - account_id
        - status
        - amount
        - currency
        - method
        - details
        - created_at
      additionalProperties: false
    google.protobuf.Timestamp:
      type: string
      format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

```

--------------------------------

### GET /v1alpha1/offers/{id}

Source: https://docs.toffeepay.com/api-reference/offers/get

Retrieves a hub offer by its unique identifier.

```APIDOC
## GET /v1alpha1/offers/{id}

### Description
Get hub offer by its id.

### Method
GET

### Endpoint
/v1alpha1/offers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the offer.

### Response
#### Success Response (200)
Returns the offer object with the following fields:
- **id** (string) - Offer ID.
- **game_id** (string) - Game ID associated with the offer.
- **user_id** (string|null) - User ID if the offer is user-specific.
- **reference** (string|null) - External reference.
- **title** (string) - Offer title.
- **description** (string|null) - Offer description.
- **image** (string) - Image URL (must start with http(s):// or data:).
- **category** (string) - Offer category.
- **label** (string|null) - Optional label.
- **status** (string) - Offer status: `inactive` or `active`.
- **items** (array of OfferItem) - List of offer items (at least 1).
- **price** (integer) - Price in minor units (exclusiveMinimum: 0).
- **currency** (string) - Currency code: `USD`, `GBP`, or `EUR`.
- **stock** (integer|null) - Available stock (exclusiveMinimum: 0).
- **country** (string) - ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE").
- **return_url** (string) - Return URL (URI format).
- **wallet_enabled** (boolean) - Whether wallet payment is enabled.
- **created_at** (string) - Creation timestamp (date-time format).
- **updated_at** (string) - Last update timestamp (date-time format).

#### Response Example
```json
{
  "id": "offer_123",
  "game_id": "game_456",
  "user_id": null,
  "reference": null,
  "title": "Starter Pack",
  "description": "A pack for new players",
  "image": "https://example.com/image.png",
  "category": "starter",
  "label": null,
  "status": "active",
  "items": [
    {
      "id": "item_1",
      "icon": "https://example.com/icon.png",
      "amount": 100
    }
  ],
  "price": 499,
  "currency": "USD",
  "stock": 100,
  "country": "US",
  "return_url": "https://example.com/return",
  "wallet_enabled": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### Authentication
Requires a Bearer token (JWT) in the Authorization header.

### Servers
- Production: `https://api.toffeepay.com`
- Sandbox: `https://api.sandbox.toffeepay.com`
```

--------------------------------

### Session resource operations

Source: https://docs.toffeepay.com/sdks/python

Create, get, status, list, and cancel sessions using the sessions resource.

```python
resp = await toffee.sessions.create(CreateSessionRequest(...))
session = resp.session

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

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

resp = await toffee.sessions.list(ListSessionsRequest(game_id="game_1"))
sessions = resp.sessions

await toffee.sessions.cancel(CancelSessionRequest(id="sess_123"))
```

--------------------------------

### Refund resource operations

Source: https://docs.toffeepay.com/sdks/python

Create, get, and list refunds using the refunds resource.

```python
resp = await toffee.refunds.create(CreateRefundRequest(payment_id="pay_123"))
refund = resp.refund

resp = await toffee.refunds.get(GetRefundRequest(id="ref_123"))
refund = resp.refund

resp = await toffee.refunds.list(ListRefundsRequest(payment_id="pay_123"))
refunds = resp.refunds
```

--------------------------------

### Get Session (Full Details) - Python

Source: https://docs.toffeepay.com/payments

Use this to fetch full session details in Python. The response includes the session object with fields like id, url, status, user_id, game_id, item, tax, and timestamps.

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

--------------------------------

### Payment resource methods

Source: https://docs.toffeepay.com/sdks/typescript

Payment resource methods: get, list, complete, and cancel.

```typescript
const { payment } = await toffee.payments.get({ id: "pay_123" });
const { payments } = await toffee.payments.list({ gameId: "game_1" });
await toffee.payments.complete({ id: "pay_123" });
await toffee.payments.cancel({ id: "pay_123" });
```

--------------------------------

### GET /v1/accounts/{id}

Source: https://docs.toffeepay.com/api-reference/accounts/get

Retrieves account details by its unique identifier. Returns the account's ID, linked game users, currency, and balance.

```APIDOC
## GET /v1/accounts/{id}

### Description
Returns account details by its id.

### Method
GET

### Endpoint
/v1/accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the account.
- **users** (array of wallet.v1.GameUser) - All game users linked to this account.
  - **game_id** (string) - The game identifier.
  - **user_id** (string) - The user identifier.
- **currency** (string) - The account currency. Enum: USD, GBP, EUR.
- **balance** (wallet.v1.Balance) - The account balance.
  - **real** (integer) - The real money balance.
  - **bonus** (integer) - The bonus balance.

#### Response Example
{
  "id": "string",
  "users": [
    {
      "game_id": "string",
      "user_id": "string"
    }
  ],
  "currency": "USD",
  "balance": {
    "real": 0,
    "bonus": 0
  }
}
```

--------------------------------

### Get a deposit (Go)

Source: https://docs.toffeepay.com/wallet

Retrieves a deposit by ID using the Go SDK. The request is &sdk.GetDepositRequest{Id: "dep_xyz789"} and the response returns the deposit.

```go
resp, err := toffee.Deposits.Get(ctx, &sdk.GetDepositRequest{Id: "dep_xyz789"})
deposit := resp.GetDeposit()
```

--------------------------------

### Refund Object Response

Source: https://docs.toffeepay.com/refunds

Example response object returned when creating a refund. The status is initially "pending".

```json
{
  "id": "ref_xyz789",
  "payment_id": "pay_xyz789",
  "status": "pending",
  "reason": "Customer request",
  "created_at": "2023-06-01T12:00:00Z"
}
```

--------------------------------

### Get Session (Full Details) - Go

Source: https://docs.toffeepay.com/payments

Use this to fetch full session details in Go. The response includes the session object with fields like id, url, status, user_id, game_id, item, tax, and timestamps.

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

--------------------------------

### List deposits (API)

Source: https://docs.toffeepay.com/wallet

Lists deposits via the HTTP API using GET /v1/deposits with account_id, limit, and offset query parameters.

```http
GET /v1/deposits?account_id=acc_xyz123&limit=100&offset=0
Authorization: Bearer <your_access_token>
```

--------------------------------

### Configure SDK

Source: https://docs.toffeepay.com/sdks/go

Initialize the SDK client with your access token.

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

toffee := sdk.New(sdk.Config{
    AccessToken: "your-access-token",
})
```

--------------------------------

### OpenAPI spec for GET /v1alpha1/offers

Source: https://docs.toffeepay.com/api-reference/offers/list

OpenAPI 3.1.0 specification for the GET /v1alpha1/offers endpoint. It defines the ListOffers operation (OfferService_ListOffers) with required game_id query parameter, optional user_id, countries, currencies, limit (default 100, max 250), offset, from, and to parameters. The 200 response returns an array of hub.v1alpha1.Offer objects, and the schema includes the Offer and OfferItem definitions.

```yaml
openapi: 3.1.0
info:
  title: ToffeePay API
  description: Public API for game partners
  version: 0.2.0
servers:
  - url: https://api.toffeepay.com
    description: Production
  - url: https://api.sandbox.toffeepay.com
    description: Sandbox
security:
  - BearerAuth: []
paths:
  /v1alpha1/offers:
    get:
      summary: ListOffers
      description: List hub offers
      operationId: OfferService_ListOffers
      parameters:
        - name: game_id
          in: query
          required: true
          schema:
            type: string
            title: game_id
        - name: user_id
          in: query
          schema:
            type: string
            title: user_id
        - name: countries
          in: query
          description: 'ISO 3166-1 alpha-2: "US", "GB", "DE"'
          schema:
            type: array
            items:
              type: string
              maxLength: 2
              minLength: 2
              pattern: ^[A-Z]{2}$
            title: countries
        - name: currencies
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - USD
                - GBP
                - EUR
            title: currencies
        - name: limit
          in: query
          description: 'default: 100'
          schema:
            exclusiveMinimum: 0
            type: integer
            title: limit
            maximum: 250
            format: int32
        - name: offset
          in: query
          schema:
            type: integer
            title: offset
            minimum: 0
            format: int32
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/hub.v1alpha1.Offer'
                title: offers
components:
  schemas:
    hub.v1alpha1.Offer:
      type: object
      properties:
        id:
          type: string
          title: id
        game_id:
          type: string
          title: game_id
        user_id:
          type:
            - string
            - 'null'
          title: user_id
        reference:
          type:
            - string
            - 'null'
          title: reference
        title:
          type: string
          title: title
        description:
          type:
            - string
            - 'null'
          title: description
        image:
          type: string
          title: image
          pattern: ^(https?://|data:)
        category:
          type: string
          title: category
        label:
          type:
            - string
            - 'null'
          title: label
        status:
          type: string
          title: status
          enum:
            - inactive
            - active
        items:
          type: array
          items:
            $ref: '#/components/schemas/hub.v1alpha1.OfferItem'
          title: items
          minItems: 1
        price:
          exclusiveMinimum: 0
          type: integer
          title: price
          format: int32
        currency:
          type: string
          title: currency
          enum:
            - USD
            - GBP
            - EUR
        stock:
          exclusiveMinimum: 0
          type:
            - integer
            - 'null'
          title: stock
          format: int32
        country:
          type: string
          title: country
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          description: 'ISO 3166-1 alpha-2: "US", "GB", "DE"'
        return_url:
          type: string
          title: return_url
          format: uri
        wallet_enabled:
          type: boolean
          title: wallet_enabled
        created_at:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
        updated_at:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: updated_at
      title: Offer
      required:
        - id
        - game_id
        - title
        - image
        - category
        - status
        - items
        - price
        - currency
        - country
        - wallet_enabled
        - created_at
        - updated_at
      additionalProperties: false
    hub.v1alpha1.OfferItem:
      type: object
      properties:
        id:
          type: string
          title: id
        icon:
```

--------------------------------

### Generate unique idempotency key with UUID

Source: https://docs.toffeepay.com/idempotency

TypeScript example using the uuid library to generate a unique idempotency key. This is recommended to avoid collisions.

```typescript
import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4(); // e.g., "550e8400-e29b-41d4-a716-446655440000"
```

--------------------------------

### List Sessions - JSON Response

Source: https://docs.toffeepay.com/payments

Example JSON response for the list sessions operation, showing an array of session objects with item and tax details.

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

--------------------------------

### GET /v1alpha1/bonuses/{id_or_key}

Source: https://docs.toffeepay.com/api-reference/bonuses/get

Retrieves bonus information by ID or external key. The response contains the bonus details including amount, currency, and associated account.

```APIDOC
## GET /v1alpha1/bonuses/{id_or_key}

### Description
Get bonus info by id or external key.

### Method
GET

### Endpoint
/v1alpha1/bonuses/{id_or_key}

### Parameters
#### Path Parameters
- **id_or_key** (string) - Required - The bonus ID or external key.

### Response
#### Success Response (200)
- **id** (string) - Bonus ID.
- **key** (string|null) - External key.
- **account_id** (string) - Account ID associated with the bonus.
- **amount** (integer) - Bonus amount (minimum 0).
- **currency** (string) - Currency code (USD, GBP, EUR).
- **metadata** (object|null) - Additional metadata.
- **created_at** (string) - Creation timestamp (date-time).

#### Response Example
{
  "id": "string",
  "key": "string",
  "account_id": "string",
  "amount": 0,
  "currency": "USD",
  "metadata": {},
  "created_at": "2023-01-01T00:00:00Z"
}
```

--------------------------------

### GET /v1/sessions

Source: https://docs.toffeepay.com/api-reference/sessions/list

Lists payment sessions. Supports filtering by game_id, user_id, status, date range, and pagination via limit and offset.

```APIDOC
## GET /v1/sessions

### Description
List payments sessions.

### Method
GET

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **game_id** (string) - Required - The game identifier.
- **user_id** (string) - Optional - The user identifier.
- **status** (string) - Optional - Filter by session status. Enum: pending, paid, failed, cancelled, expired.
- **limit** (integer) - Optional - Maximum number of sessions to return. Default: 100. Maximum: 250. Must be greater than 0.
- **offset** (integer) - Optional - Number of sessions to skip. Minimum: 0.
- **from** (string, date-time) - Optional - Start date for filtering sessions.
- **to** (string, date-time) - Optional - End date for filtering sessions.

### Response
#### Success Response (200)
Returns an array of session objects. Each session has the following properties:
- **id** (string) - Required - Session identifier.
- **url** (string) - Required - Payment URL.
- **status** (string) - Required - Session status. Enum: pending, paid, failed, cancelled, expired.
- **payment_id** (string) - Deprecated - Payment identifier.
- **user_id** (string) - Required - User identifier.
- **game_id** (string) - Required - Game identifier.
- **item** (object) - Required - Item details.
  - **title** (string) - Required - Item title.
  - **price** (integer) - Required - Item price.
  - **currency** (string) - Required - Currency. Enum: USD, GBP, EUR.
  - **image** (string) - Optional - Image URL.
  - **country** (string) - Optional - ISO 3166-1 alpha-2 country code.
- **created_at** (string, date-time) - Required - Creation timestamp.
- **paid_at** (string, date-time) - Optional - Payment timestamp.
- **failed_at** (string, date-time) - Optional - Failure timestamp.
- **cancelled_at** (string, date-time) - Optional - Cancellation timestamp.
- **expired_at** (string, date-time) - Optional - Expiration timestamp.
- **tax** (object) - Optional - Sales tax for the session.
- **metadata** (object) - Optional - Session metadata.

#### Response Example
```json
[
  {
    "id": "string",
    "url": "string",
    "status": "pending",
    "payment_id": "string",
    "user_id": "string",
    "game_id": "string",
    "item": {
      "title": "string",
      "price": 0,
      "currency": "USD",
      "image": "string",
      "country": "US"
    },
    "created_at": "2023-01-01T00:00:00Z",
    "paid_at": "2023-01-01T00:00:00Z",
    "failed_at": null,
    "cancelled_at": null,
    "expired_at": null,
    "tax": {},
    "metadata": {}
  }
]
```
```

--------------------------------

### Configure Sandbox Environment

Source: https://docs.toffeepay.com/sdks/go

Initialize the SDK client for the sandbox environment using a sandbox token.

```go
toffee := sdk.New(sdk.Config{
    AccessToken: "your-sandbox-token",
    Environment: sdk.Sandbox,
})
```

--------------------------------

### GET /v1alpha1/offers

Source: https://docs.toffeepay.com/api-reference/offers/list

Retrieves a list of hub offers. Supports filtering by game, user, country, currency, and date range, with pagination via limit and offset.

```APIDOC
## GET /v1alpha1/offers

### Description
List hub offers.

### Method
GET

### Endpoint
/v1alpha1/offers

### Parameters
#### Query Parameters
- **game_id** (string) - Required - The game identifier.
- **user_id** (string) - Optional - The user identifier.
- **countries** (array of string) - Optional - ISO 3166-1 alpha-2 country codes, e.g., "US", "GB", "DE". Each item must be exactly 2 uppercase letters.
- **currencies** (array of string) - Optional - Allowed values: USD, GBP, EUR.
- **limit** (integer) - Optional - Maximum number of offers to return. Default: 100. Maximum: 250.
- **offset** (integer) - Optional - Number of offers to skip. Minimum: 0.
- **from** (string, date-time) - Optional - Start date-time filter.
- **to** (string, date-time) - Optional - End date-time filter.

### Response
#### Success Response (200)
Returns an array of Offer objects. Each Offer contains:
- **id** (string) - Offer ID.
- **game_id** (string) - Game ID.
- **user_id** (string or null) - User ID.
- **reference** (string or null) - Reference.
- **title** (string) - Offer title.
- **description** (string or null) - Offer description.
- **image** (string) - Image URL (must start with http://, https://, or data:).
- **category** (string) - Offer category.
- **label** (string or null) - Offer label.
- **status** (string) - Offer status. Allowed values: inactive, active.
- **items** (array of OfferItem) - Offer items. Minimum 1 item.
- **price** (integer) - Price in minor units. Must be greater than 0.
- **currency** (string) - Currency. Allowed values: USD, GBP, EUR.
- **stock** (integer or null) - Stock count. Must be greater than 0.
- **country** (string) - ISO 3166-1 alpha-2 country code.
- **return_url** (string, uri) - Return URL.
- **wallet_enabled** (boolean) - Whether wallet is enabled.
- **created_at** (Timestamp) - Creation timestamp.
- **updated_at** (Timestamp) - Last update timestamp.

#### Response Example
```json
[
  {
    "id": "offer-123",
    "game_id": "game-456",
    "user_id": null,
    "reference": null,
    "title": "Starter Pack",
    "description": "A starter pack for new players",
    "image": "https://example.com/image.png",
    "category": "starter",
    "label": null,
    "status": "active",
    "items": [
      {
        "id": "item-1",
        "icon": "https://example.com/icon.png"
      }
    ],
    "price": 499,
    "currency": "USD",
    "stock": 100,
    "country": "US",
    "return_url": "https://example.com/return",
    "wallet_enabled": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]
```
```

--------------------------------

### Confirm payment status with toffee.sessions.status

Source: https://docs.toffeepay.com/getting-started

Code examples for confirming payment status after returning to the game. The TypeScript, Python, and Go SDKs use the toffee.sessions.status method, while the API example uses a GET request to /v1/sessions/sess_123/status with an Authorization header. All examples check if the status is "paid" before granting items.

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

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

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

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

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

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

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