Skip to main content
GET
/
v1
/
invoice
/
{paymentId}
/
status
Get Payment Status
curl --request GET \
  --url https://api.example.com/v1/invoice/{paymentId}/status
{
  "paymentId": "<string>",
  "status": "<string>",
  "currentBalance": "<string>",
  "confirmations": 123,
  "requiredAmount": "<string>",
  "currency": "<string>",
  "address": "<string>",
  "expiresAt": "<string>",
  "createdAt": "<string>",
  "completedAt": "<string>"
}

​
Overview

This endpoint retrieves the current status of a payment or invoice, including confirmation count, current balance, and payment state. This is a public endpoint that does not require authentication. Use this endpoint to check if a payment has been received and confirmed.

​
Path Parameters

​
paymentId
string
required
The unique payment or invoice ID Example: "cmh123abc456def"

​
Response

​
paymentId
string
The payment identifier Example: "cmh123abc456def"
​
status
string
Current payment status Options: PENDING, COMPLETED, EXPIRED, FAILED Example: "PENDING"
​
currentBalance
string
Amount received so far in cryptocurrency Example: "29.99"
​
confirmations
number
Number of blockchain confirmations received Example: 3
​
requiredAmount
string
Total amount required for this payment Example: "29.99"
​
currency
string
The cryptocurrency for this payment Example: "USDT_BEP20"
​
address
string
Payment address (if currency has been selected) Example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
​
expiresAt
string
Payment expiration timestamp (ISO 8601) Example: "2024-01-01T12:30:00.000Z"
​
createdAt
string
Payment creation timestamp (ISO 8601) Example: "2024-01-01T12:00:00.000Z"
​
completedAt
string
Payment completion timestamp (ISO 8601, only present if completed) Example: "2024-01-01T12:15:00.000Z"

​
Payment Status Values

StatusDescription
PENDINGWaiting for payment to be received or confirmed
COMPLETEDPayment received and confirmed on blockchain
EXPIREDPayment window expired without receiving full amount
FAILEDPayment failed due to an error

​
Example Request

curl -X GET https://api.inventpay.io/v1/invoice/cmh123abc456def/status

​
Example Response

200 - Pending Payment
{
  "paymentId": "cmh123abc456def",
  "status": "PENDING",
  "currentBalance": "0",
  "confirmations": 0,
  "requiredAmount": "29.99",
  "currency": "USDT_BEP20",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "expiresAt": "2024-01-01T12:30:00.000Z",
  "createdAt": "2024-01-01T12:00:00.000Z"
}
200 - Completed Payment
{
  "paymentId": "cmh123abc456def",
  "status": "COMPLETED",
  "currentBalance": "29.99",
  "confirmations": 12,
  "requiredAmount": "29.99",
  "currency": "USDT_BEP20",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "expiresAt": "2024-01-01T12:30:00.000Z",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "completedAt": "2024-01-01T12:15:00.000Z"
}
200 - Expired Payment
{
  "paymentId": "cmh123abc456def",
  "status": "EXPIRED",
  "currentBalance": "0",
  "confirmations": 0,
  "requiredAmount": "29.99",
  "currency": "USDT_BEP20",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "expiresAt": "2024-01-01T12:30:00.000Z",
  "createdAt": "2024-01-01T12:00:00.000Z"
}
404 - Payment Not Found
{
  "success": false,
  "error": "Payment not found",
  "statusCode": 404
}

​
Confirmation Requirements

Different cryptocurrencies require different numbers of confirmations:
CryptocurrencyRequired Confirmations
BTC3 confirmations
ETH12 confirmations
LTC6 confirmations
USDT (ERC20)12 confirmations
USDT (BEP20)15 confirmations
Payments are marked as COMPLETED once they receive the required number of confirmations for their respective blockchain.

​
Polling Best Practices

If you’re not using webhooks, you can poll this endpoint to check payment status:
  • Recommended interval: 30-60 seconds
  • Stop polling when: Status becomes COMPLETED, EXPIRED, or FAILED
  • Better alternative: Use webhooks for real-time notifications
Polling too frequently may result in rate limiting. We strongly recommend using webhooks instead of polling.

​
Error Codes

Status CodeDescription
200Status retrieved successfully
404Payment not found
429Rate limit exceeded
500Internal server error