> ## 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.
# Get Transaction
> Returns the full state and metadata of a payment transaction.
`amount_minor` is expressed in XAF. XAF has no sub-unit — `amount_minor: 5000` means exactly 5 000 XAF.
Use this endpoint to poll transaction state when you don't have a `callback_url` set, or to debug a specific transaction. For normal operations, prefer [webhooks](/api-reference/webhooks) — they push results to you the moment the payment settles.
See [State Machine](/api-reference/state-machine) for the full list of possible `state` values and valid transitions.
## OpenAPI
````yaml GET /api/v1/transactions/{winam_tx_id}
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/transactions/{winam_tx_id}:
get:
tags:
- transactions
summary: Get transaction state
description: Returns the full state of a payment transaction.
operationId: get_transaction_api_v1_transactions__winam_tx_id__get
parameters:
- name: winam_tx_id
in: path
required: true
schema:
type: string
format: uuid
title: Winam Tx Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionStateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
TransactionStateResponse:
properties:
winam_tx_id:
type: string
format: uuid
title: Winam Tx Id
description: Winam internal transaction UUID
idempotency_key:
type: string
title: Idempotency Key
description: Your original `reference` value
direction:
type: string
title: Direction
description: '`"deposit"` or `"withdrawal"`'
operator:
type: string
title: Operator
description: '`"mtn"` or `"orange"`'
provider:
type: string
title: Provider
description: Internal provider used for this transaction
examples:
- sim_gateway_mtn
msisdn:
type: string
title: Msisdn
description: Player Mobile Money number in E.164 format
amount_minor:
type: integer
title: Amount Minor
description: >-
Amount in XAF. Equal to `amount_xaf` from the request — XAF has no
sub-unit (1 XAF = 1 unit).
examples:
- 5000
state:
type: string
title: State
description: >-
Current transaction state. See the [state
machine](/api-reference/state-machine) for the full transition
diagram.
examples:
- succeeded
state_reason:
anyOf:
- type: string
- type: 'null'
title: State Reason
description: Human-readable reason for the last state transition
state_updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: State Updated At
description: Timestamp of the last state change
requires_human_approval:
type: boolean
title: Requires Human Approval
description: True for withdrawals awaiting operator approval
provider_tx_id:
anyOf:
- type: string
- type: 'null'
title: Provider Tx Id
description: >-
Provider-side reference (e.g. MTN transaction ID). Available once
acknowledged.
examples:
- MTN2025010112345
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: >-
Confirmation deadline for deposits. Null once the transaction is in
a terminal state.
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
- idempotency_key
- direction
- operator
- provider
- msisdn
- amount_minor
- state
- state_updated_at
- requires_human_approval
- provider_tx_id
- expires_at
- created_at
- updated_at
title: TransactionStateResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
````