> For the complete documentation index, see [llms.txt](https://docs.payram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payram.com/api-integration/payments-api/payment-status.md).

# Payment Status

<figure><img src="/files/nIgN9SFp2cuA8CncwM3g" alt=""><figcaption></figcaption></figure>

***

## URL Details

<table><thead><tr><th width="157.99609375">Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>BASE_URL</td><td>Your PayRam Site URL — find it under <strong>Settings → Site URL</strong> in your dashboard. Include the port if you installed on one.</td><td><code>https://pay.example.com</code></td></tr><tr><td>API Endpoint</td><td>Endpoint to fetch the current status of a payment.</td><td><code>/api/v1/payment/reference/{reference_id}</code></td></tr></tbody></table>

## Headers

<table><thead><tr><th width="129.0859375">Header</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API-Key</td><td>Your unique PayRam API key generated from your dashboard.</td><td>811b12035f0dfa8ffd62296df3c98b27</td></tr><tr><td>Content-Type</td><td>Format of the request data.</td><td>application/json</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:$warning;">**Note**</mark> <mark style="color:$success;">**: You can generate a unique API key for each project directly from the PayRam dashboard. This helps you manage and track payouts separately for every project.**</mark>
{% endhint %}

## curl request

Before running the command, replace the placeholders with your actual details:

* ${BASE\_URL} → Your PayRam server URL
* \<your\_api\_key> → Your PayRam API key

```bash
curl --location '<BASE_URL>/api/v1/payment/reference/<reference_id>' \
--header 'API-Key: <API_KEY>' \
--data ''
```

## curl response

You’ll receive the payment record, including:

* Identifiers – the reference ID, invoice ID, and your customer ID
* Amount – the requested amount in USD
* State – the current `paymentState` (see the table below)

```
{
  "invoiceID": "0dec6a8c-9cbc-4086-8680-10d45319a8d1",
  "customerID": "0",
  "amountInUSD": "1",
  "paymentState": "OPEN",
  "merchantName": "Payout",
  "referenceID": "0dec6a8c-9cbc-4086-8680-10d45319a8d1",
  "createdAt": "2025-11-07T11:37:59.012304Z",
  ...
}
```

{% hint style="info" %} <mark style="color:$warning;">**Note :**</mark> <mark style="color:$success;">**Check the paymentState field in the response to track the payment status.**</mark>
{% endhint %}

| STATUS            | DESCRIPTION                                       |
| ----------------- | ------------------------------------------------- |
| OPEN              | The payment has not been processed yet.           |
| CANCELLED         | The payment link has expired.                     |
| FILLED            | The user has paid the full requested amount.      |
| PARTIALLY\_FILLED | The user has paid less than the requested amount. |
| OVER\_FILLED      | The user has paid more than the requested amount. |