> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pesahub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Payment Status

> Retrieves the current status and details of a payment using its transaction ID.

## Endpoint

```http theme={null}
GET /v1/payments/{transaction_id}
```

## Authentication

Requires a Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer {{api_key}}
```

## Request Headers

| Header         | Value              |
| -------------- | ------------------ |
| `Accept`       | `application/json` |
| `Content-Type` | `application/json` |

## Path Parameters

<ParamField path="transaction_id" type="string" required>
  Unique identifier of the payment transaction.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://pesahub.test/api/v1/payments/f19605f6-f67e-4230-8152-30b35740a024 \
    -H "Authorization: Bearer {{api_key}}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://pesahub.test/api/v1/payments/f19605f6-f67e-4230-8152-30b35740a024',
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://pesahub.test/api/v1/payments/f19605f6-f67e-4230-8152-30b35740a024',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Accept': 'application/json',
          'Content-Type': 'application/json',
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable response message.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status (`pending`, `completed`, `failed`, or `cancelled`).
</ResponseField>

<ResponseField name="payment.transaction_id" type="string">
  Unique identifier of the payment transaction.
</ResponseField>

<ResponseField name="payment.transaction_mode" type="string">
  Payment transaction mode (for example, `ussd`).
</ResponseField>

<ResponseField name="payment.transaction_currency" type="string">
  Currency used for the transaction.
</ResponseField>

<ResponseField name="payment.channel" type="object">
  Payment channel information.
</ResponseField>

<ResponseField name="payment.customer" type="object">
  Customer information associated with the payment.
</ResponseField>

<ResponseField name="payment.metadata" type="object">
  Additional metadata attached to the transaction.
</ResponseField>

<ResponseField name="payment.amount.value" type="string">
  Payment amount.
</ResponseField>

<ResponseField name="payment.event" type="string">
  Latest payment event (for example, `payment.pending`).
</ResponseField>

<ResponseField name="payment.created_at" type="string">
  ISO 8601 timestamp when the payment was created.
</ResponseField>

<ResponseField name="payment.updated_at" type="string">
  ISO 8601 timestamp when the payment was last updated.
</ResponseField>

<ResponseField name="payment.timestamp" type="string">
  Timestamp of the latest payment status update.
</ResponseField>

## Example Response

```json theme={null}
{
  "success": true,
  "message": "Payment status retrieved successfully",
  "status": "pending",
  "payment": {
    "transaction_id": "f19605f6-f67e-4230-8152-30b35740a024",
    "transaction_mode": "ussd",
    "transaction_currency": "TZS",
    "channel": {
      "name": "AIRTEL-MONEY",
      "reference": null
    },
    "customer": {
      "full_name": null,
      "phone_number": null
    },
    "metadata": {
      "order_id": "12345",
      "customer_note": "Test payment"
    },
    "amount": {
      "value": "500.00"
    },
    "created_at": "2026-05-01T18:08:15.000000Z",
    "updated_at": "2026-05-01T09:57:23.000000Z",
    "timestamp": "2026-07-12T19:12:33.795106Z",
    "event": "payment.pending"
  }
}
```

<Note>
  Poll this endpoint using the transaction ID to monitor payment progress until the transaction reaches a final state.
</Note>