> ## Documentation Index > Fetch the complete documentation index at: https://docs.palpluss.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Transaction > Retrieve the full details of a single transaction by its ID. Retrieve a transaction by ID. Use this to confirm status, display details, or reconcile payments. Use webhooks as your primary mechanism for receiving payment results. Poll this endpoint only when webhook delivery has failed. ## When to use this endpoint * Confirm final status when webhooks are unavailable * Display transaction details in your application * Reconcile payments against internal records ## Response fields | Field | Type | Description | | ---------------------- | -------------- | --------------------------------------------------------------------------------------------------- | | `transaction_id` | string | Transaction UUID | | `type` | string | `STK` or `B2C` | | `status` | string | Current status — see [transaction lifecycle](/guides/transaction-lifecycle) | | `amount` | number | Transaction amount in KES | | `currency` | string | Always `"KES"` | | `phone_number` | string | Normalised phone (`254XXXXXXXXX`) | | `external_reference` | string \| null | Your `accountReference` or `reference` | | `transaction_fee` | number | Service wallet fee charged. Returned for `PENDING` and `SUCCESS` only — `0` for all other statuses. | | `provider_request_id` | string \| null | Provider request reference | | `provider_checkout_id` | string \| null | Provider checkout / conversation ID | | `result_code` | string \| null | Provider result code | | `result_desc` | string \| null | Provider result description | | `created_at` | string | ISO 8601 timestamp | | `updated_at` | string | ISO 8601 timestamp | ## Polling strategy After initiating an STK Push: 1. Wait 15 seconds — most customers respond within this window. 2. Poll every 10 seconds while status is `PENDING` or `PROCESSING`. 3. Stop when a terminal state is reached: `SUCCESS`, `FAILED`, `CANCELLED`, or `REVERSED`. 4. After 5 minutes without a terminal state, treat the transaction as likely failed. Excessive polling consumes your rate limit. For real-time results, use [webhooks](/guides/webhooks). ## OpenAPI ````yaml GET /transactions/{id} openapi: 3.1.0 info: title: PalPluss API version: '1.0' summary: >- Payment infrastructure for Kenya — STK Push, B2C payouts, and wallet management. description: > The PalPluss API gives developers programmatic access to M-Pesa STK Push collections, B2C payouts, service wallet top-ups, and payment channel management. **Base URL:** `https://api.palpluss.com/v1` All requests must be authenticated with an API key using HTTP Basic Auth. All responses are wrapped in a standard envelope. See [Errors](#tag/errors) for error codes. Amounts are in **KES (Kenyan Shillings)** unless stated otherwise. Phone numbers are normalized to the `254XXXXXXXXX` format internally. contact: name: PalPluss Developer Support email: developer@palpluss.com url: https://palpluss.com/developers servers: - url: https://api.palpluss.com/v1 description: Production - url: https://sandbox.palpluss.com/v1 description: Sandbox security: - BasicAuth: [] tags: - name: STK Push description: > Initiate M-Pesa STK Push payment prompts. The customer receives a PIN prompt on their phone and confirms payment. PalPluss delivers the result asynchronously to your webhook URL. - name: Transactions description: >- Query the status of any transaction by ID, or list all transactions with filters. - name: B2C Payouts description: > Send money directly to a customer's M-Pesa number. Requires KYC approval and sufficient B2C wallet balance. Payouts are processed asynchronously. - name: Service Wallet description: > The service wallet holds pre-funded tokens used to pay PalPluss transaction fees. Top up via STK Push. Balance is deducted with each API call. - name: Payment Channels description: > Payment channels represent the M-Pesa shortcodes (Paybill / Till) associated with your account. Channels are used to route STK Push requests to a specific shortcode. paths: /transactions/{id}: get: tags: - Transactions summary: Get transaction description: > Returns the full details of a single transaction. Use this to poll for the terminal status of an STK Push or B2C payout if you are not using webhooks. operationId: getTransaction parameters: - name: id in: path required: true description: The transaction ID returned when the payment was initiated. schema: type: string format: uuid responses: '200': description: Transaction details. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/Transaction' examples: success: value: success: true data: transactionId: fa98a577-95ea-4a8f-8467-1fbe74f5d6f4 tenantId: b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d type: STK status: SUCCESS amount: 1000 currency: KES phone: '254712345678' channelId: null accountReference: INV-2024-001 transactionDesc: 'Payment for invoice #2024-001' provider: m-pesa providerRequestId: 29115-34620561-1 providerCheckoutId: ws_CO_191220191020363925 resultCode: '0' resultDesc: The service request is processed successfully. createdAt: '2026-03-01T08:00:00.000Z' updatedAt: '2026-03-01T08:01:30.000Z' requestId: c1b2a3d4-0000-0000-0000-000000000000 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: schemas: SuccessEnvelope: type: object required: - success - data - requestId properties: success: type: boolean example: true data: type: object description: Response payload. Shape varies by endpoint. requestId: type: string format: uuid description: Unique identifier for this API request. Include in support tickets. example: c1b2a3d4-e5f6-7890-abcd-ef1234567890 Transaction: type: object properties: transactionId: type: string format: uuid description: Unique transaction identifier. tenantId: type: string format: uuid type: $ref: '#/components/schemas/TransactionType' status: $ref: '#/components/schemas/TransactionStatus' amount: type: number format: decimal description: Transaction amount in KES. example: 1000 currency: type: string example: KES phone: type: string description: Customer phone in `254XXXXXXXXX` format. example: '254712345678' channelId: type: string format: uuid nullable: true accountReference: type: string nullable: true description: Reference you supplied (STK) or external reference (B2C). example: INV-2024-001 transactionDesc: type: string nullable: true example: 'Payment for invoice #2024-001' provider: type: string nullable: true example: m-pesa providerRequestId: type: string nullable: true example: 29115-34620561-1 providerCheckoutId: type: string nullable: true example: ws_CO_191220191020363925 resultCode: type: string nullable: true description: M-Pesa result code. `"0"` = success. example: '0' resultDesc: type: string nullable: true example: The service request is processed successfully. createdAt: type: string format: date-time updatedAt: type: string format: date-time TransactionType: type: string enum: - STK - B2C description: | - `STK` — M-Pesa STK Push collection - `B2C` — Business to Customer payout TransactionStatus: type: string enum: - PENDING - PROCESSING - SUCCESS - FAILED - REVERSED - CANCELLED description: | - `PENDING` — Awaiting customer action or provider response - `PROCESSING` — Provider accepted; waiting for final confirmation - `SUCCESS` — Completed successfully - `FAILED` — Transaction failed (provider declined or timeout) - `REVERSED` — Successfully reversed (wallet credited back) - `CANCELLED` — Cancelled before processing ErrorEnvelope: type: object required: - success - error - requestId properties: success: type: boolean example: false error: type: object required: - message - code properties: message: type: string description: Human-readable error description. example: Invalid API key code: type: string description: Machine-readable error code. example: INVALID_API_KEY details: type: object description: Optional structured details about the error. requestId: type: string format: uuid example: c1b2a3d4-e5f6-7890-abcd-ef1234567890 responses: Unauthorized: description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_key: value: success: false error: message: Invalid or revoked API key. code: INVALID_API_KEY details: {} requestId: a1b2c3d4-0000-0000-0000-000000000000 NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: not_found: value: success: false error: message: Transaction not found. code: TRANSACTION_NOT_FOUND details: {} requestId: a1b2c3d4-0000-0000-0000-000000000000 RateLimited: description: Rate limit exceeded — 60 requests per minute per API key. headers: x-ratelimit-limit: schema: type: integer description: Maximum requests per minute. x-ratelimit-remaining: schema: type: integer description: Remaining requests in the current window. x-ratelimit-reset: schema: type: integer description: Unix timestamp when the window resets. Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: value: success: false error: message: Rate limit exceeded. Try again in 12 seconds. code: RATE_LIMIT_EXCEEDED details: limit: 60 remaining: 0 resetInSeconds: 12 requestId: a1b2c3d4-0000-0000-0000-000000000000 securitySchemes: BasicAuth: type: http scheme: basic description: > Paste your PalPluss API key in the **username** field and leave the **password** field empty — it is ignored. Get your key from **console → Settings → API Keys** (starts with `pk_live_` or `pk_test_`). In your own code, send the key directly: `Authorization: Basic YOUR_API_KEY` ````