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

# Check Subscription Payment Status

> Use this POST endpoint to retrieve the latest status of a specific subscription payment transaction.

Use the internal FastFlowPe `subscription_id` and `transaction_id`.

Both values must be valid UUIDs.

Use the API key in the `x-api-key` header. Do not send it in the `Authorization` header.

<Tip>
  **Quick Reference**

  **Required:** `subscription_id`, `transaction_id`

  **Returns:** `payment_status`, `payment_type`, `payment_amount`, `utr`

  **Method:** `POST`
</Tip>

## Endpoint Details

| Field | Value |
| - | - |
| Method | `POST` |
| Payload | `JSON` |
| URL | `https://api.fastflowpe.com/merchant/recurring/subscription/payment/status` |

## Request Headers

<ParamField header="x-api-key" type="string" required>
  Your secret merchant API key issued by FastFlowPe.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request Body

<ParamField body="subscription_id" type="string" required>
  Internal FastFlowPe subscription UUID.

  This must be a valid UUID.

  Example:

  `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField body="transaction_id" type="string" required>
  Internal FastFlowPe transaction UUID associated with the subscription.

  This must be a valid UUID.

  Example:

  `7c9e6679-7425-40de-944b-e07fc1f90ae7`
</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={"dark"}
  curl --request POST 'https://api.fastflowpe.com/merchant/recurring/subscription/payment/status' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_MERCHANT_X_API_KEY' \
    --data-raw '{
      "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
      "transaction_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }'
  ```
</RequestExample>

## Response

A successful request returns the current payment status for the specified subscription transaction.

<ResponseExample>
  ```json Success theme={"dark"}
  {
    "status": "success",
    "status_code": 200,
    "message": "Subscription payment status fetched successfully",
    "detail": null,
    "data": {
      "transaction_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "payment_status": "SUCCESS",
      "payment_type": "CHARGE",
      "payment_amount": 1000,
      "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
      "utr": "123456789012"
    },
    "meta": null
  }
  ```

  ```json Subscription Not Found theme={"dark"}
  {
    "status": "error",
    "status_code": 404,
    "message": "Subscription not found",
    "detail": null,
    "data": null,
    "meta": null
  }
  ```

  ```json Transaction Not Found theme={"dark"}
  {
    "status": "error",
    "status_code": 404,
    "message": "Transaction not found",
    "detail": null,
    "data": null,
    "meta": null
  }
  ```

  ```json PSP Transaction ID Missing theme={"dark"}
  {
    "status": "error",
    "status_code": 400,
    "message": "PSP transaction ID not available for this transaction",
    "detail": null,
    "data": null,
    "meta": null
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="status" type="string">
  Indicates whether the API request succeeded or failed.
</ResponseField>

<ResponseField name="status_code" type="integer">
  HTTP-style status code associated with the response.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result of the payment status request.
</ResponseField>

<ResponseField name="detail" type="object">
  Additional response details when available.

  This may be `null`.
</ResponseField>

<ResponseField name="data.transaction_id" type="string">
  Internal FastFlowPe transaction UUID.
</ResponseField>

<ResponseField name="data.payment_status" type="string">
  Current status of the subscription payment.

  Possible values may include:

  * `SUCCESS`
  * `FAILED`
  * `PENDING`
</ResponseField>

<ResponseField name="data.payment_type" type="string">
  Identifies the purpose of the payment.

  Example: `CHARGE`
</ResponseField>

<ResponseField name="data.payment_amount" type="number">
  Amount associated with the subscription payment transaction.
</ResponseField>

<ResponseField name="data.subscription_id" type="string">
  Internal FastFlowPe subscription UUID associated with the transaction.
</ResponseField>

<ResponseField name="data.utr" type="string">
  UTR or payment reference returned for the payment.

  This field may be `null`.
</ResponseField>

<ResponseField name="meta" type="object">
  Optional response metadata.

  This may be `null`.
</ResponseField>

## Payment Status Values

| Status | Meaning |
| - | - |
| `SUCCESS` | Subscription payment completed successfully. |
| `FAILED` | Subscription payment failed. |
| `PENDING` | Subscription payment is still awaiting a final status. |

## Common Errors

### Subscription Not Found

Returned when the supplied `subscription_id` does not exist or does not belong to the authenticated merchant.

HTTP `404`:

```json theme={"dark"}
{
  "status": "error",
  "status_code": 404,
  "message": "Subscription not found",
  "detail": null,
  "data": null,
  "meta": null
}
```

### Transaction Not Found

Returned when the supplied transaction does not exist for the specified subscription.

HTTP `404`:

```json theme={"dark"}
{
  "status": "error",
  "status_code": 404,
  "message": "Transaction not found",
  "detail": null,
  "data": null,
  "meta": null
}
```

### PSP Transaction ID Not Available

Returned when the FastFlowPe transaction exists but does not have the PSP transaction identifier required to perform a payment status check.

HTTP `400`:

```json theme={"dark"}
{
  "status": "error",
  "status_code": 400,
  "message": "PSP transaction ID not available for this transaction",
  "detail": null,
  "data": null,
  "meta": null
}
```

<Note>
  The `transaction_id` must belong to the specified `subscription_id`.

  Use the internal FastFlowPe transaction ID, not a PSP transaction ID.
</Note>

<Tip>
  You can retrieve subscription transaction IDs from the subscription transactions API and then use this endpoint to check the latest payment status for a specific transaction.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.