> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winampay.de/llms.txt
> Use this file to discover all available pages before exploring further.
# List Player Transactions
> Returns paginated transaction history for a player, sorted newest first.
Results are ordered by `created_at` descending. Use `page` and `limit` to paginate. Filter by `status` and `direction` to narrow results.
| Filter | Example values |
| ----------- | ---------------------------------------------------- |
| `status` | `pending`, `succeeded`, `failed`, `pending_approval` |
| `direction` | `deposit`, `withdrawal` |
The `player_id` must match the value passed in your original `POST /deposits` or `POST /withdrawals` request.
## OpenAPI
````yaml GET /api/v1/players/{player_id}/transactions
openapi: 3.1.0
info:
title: Winam Payments API
description: >
## winam-payments — Mobile Money API
Payment abstraction layer between your **sportsbook or frontend platform**
and Mobile Money providers in Cameroon (MTN MoMo, Orange Money).
### Deposit flow
1. Your platform calls `POST /api/v1/deposits` with a unique `reference`
2. winam-payments triggers a USSD collection on the merchant SIM
3. The player receives a notification on their phone and confirms with their
PIN
4. The confirmation SMS is received → transaction `succeeded`
5. Webhook sent to your `callback_url`
### Withdrawal flow
1. Your platform calls `POST /api/v1/withdrawals`
2. A Winam operator approves manually
3. winam-payments sends the USSD transfer
4. Result webhook sent to your `callback_url`
### Authentication
All requests to `/deposits` and `/withdrawals` must include the header:
```
X-API-Key:
```
In development (`SPORTSBOOK_API_KEY` empty), authentication is disabled.
### Full documentation
See [docs.winampay.de](https://docs.winampay.de) for the complete public
documentation with guides, examples, and interactive playground.
contact:
name: Eins Innovativ
email: support@eins-innovativ.de
version: 0.1.0
servers: []
security: []
tags:
- name: deposits
description: >-
Initiate Mobile Money deposits. The player receives a USSD notification on
their phone to confirm payment.
- name: withdrawals
description: >-
Initiate Mobile Money withdrawals. Requires manual approval from a Winam
operator before execution.
- name: transactions
description: >-
Query and manage existing transactions. Use for status polling or incident
recovery.
- name: providers
description: >-
List available providers and detect the operator from an MSISDN. Use to
populate payment options in your player interface.
- name: security
description: >-
Public key endpoint for verifying JWT signatures on outbound webhooks.
Fetch this key once and cache it.
paths:
/api/v1/players/{player_id}/transactions:
get:
tags:
- transactions
summary: List transactions for a player
description: >-
Returns a paginated list of transactions for the given player.
Optionally filter by `status` and/or `direction`. Results are ordered by
creation date descending (newest first).
operationId: list_player_transactions_api_v1_players__player_id__transactions_get
parameters:
- name: player_id
in: path
required: true
schema:
type: string
format: uuid
title: Player Id
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by state (e.g. pending, succeeded, failed,
pending_approval)
title: Status
description: Filter by state (e.g. pending, succeeded, failed, pending_approval)
- name: direction
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Filter by direction: deposit | withdrawal'
title: Direction
description: 'Filter by direction: deposit | withdrawal'
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
description: Page number (1-based)
default: 1
title: Page
description: Page number (1-based)
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Items per page (max 100)
default: 20
title: Limit
description: Items per page (max 100)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTransactions'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
PaginatedTransactions:
properties:
items:
items:
$ref: '#/components/schemas/TransactionListItem'
type: array
title: Items
total:
type: integer
title: Total
description: Total matching transactions (before pagination)
page:
type: integer
title: Page
limit:
type: integer
title: Limit
pages:
type: integer
title: Pages
description: Total number of pages
type: object
required:
- items
- total
- page
- limit
- pages
title: PaginatedTransactions
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TransactionListItem:
properties:
winam_tx_id:
type: string
format: uuid
title: Winam Tx Id
description: Winam internal transaction UUID
reference:
type: string
title: Reference
description: Your idempotency key, echoed from the request
direction:
type: string
title: Direction
description: '`"deposit"` or `"withdrawal"`'
examples:
- deposit
operator:
type: string
title: Operator
description: 'MoMo operator: `"mtn"` or `"orange"`'
examples:
- mtn
msisdn:
anyOf:
- type: string
- type: 'null'
title: Msisdn
description: >-
Player MSISDN (E.164). Renseigné par l'API interne ; null sur l'API
publique.
examples:
- '+237670000000'
amount_xaf:
type: integer
title: Amount Xaf
description: Amount in XAF (no sub-unit)
examples:
- 5000
state:
type: string
title: State
description: >-
Current state. Possible values: `pending` | `provider_acknowledged`
| `succeeded` | `failed` | `expired` | `pending_approval` |
`approved` | `provider_submitted` | `requires_manual_resolution`
examples:
- succeeded
provider_tx_id:
anyOf:
- type: string
- type: 'null'
title: Provider Tx Id
description: >-
Provider-side transaction reference. Available once the provider
acknowledges.
examples:
- MTN2025010112345
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- winam_tx_id
- reference
- direction
- operator
- amount_xaf
- state
- provider_tx_id
- created_at
- updated_at
title: TransactionListItem
description: Single transaction in a list response. Fields common to both APIs.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
````