Skip to main content
GET
/
payments
/
status
/
{id}
Get Payment Status
curl --request GET \
  --url https://api.example.com/payments/status/{id}
{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Payment not found"
    }
  ]
}

​
Endpoint

GET https://api.digitzs.com/payments/status/{id}

​
Overview

Use this lightweight endpoint to quickly check the status of a payment transaction without retrieving all transaction details.
This endpoint returns less data than GET /payments/, making it ideal for status polling or when you only need to know if a payment succeeded.

​
Authentication

HeaderValueRequired
x-api-keyYour API keyYes
AuthorizationBearer {appToken}Yes
appIdYour application IDYes

​
Path Parameters

​
id
string
required
The unique payment transaction ID

​
Response

​
Success Response (200 OK)

{
  "links": {
    "self": "https://api.digitzs.com/payments/status/pay_abc123xyz"
  },
  "data": {
    "type": "payments",
    "id": "pay_abc123xyz",
    "attributes": {
      "status": "completed",
      "paymentType": "card",
      "amount": "2500",
      "currency": "USD",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:05Z"
    }
  }
}
​
data.attributes.status
string
Current payment status: pending, completed, failed, refunded, voided, or partial_refund
​
data.attributes.amount
string
Transaction amount in cents
​
data.attributes.createdAt
string
ISO 8601 timestamp of payment creation
​
data.attributes.updatedAt
string
ISO 8601 timestamp of last status update

​
Code Examples

curl -X GET https://api.digitzs.com/payments/status/pay_abc123xyz \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-app-token" \
  -H "appId: your-app-id"

​
Status Values

StatusDescriptionNext Actions
pendingPayment processing (typical for ACH)Wait for settlement
completedSuccessfully processedNo action needed
failedPayment failed or declinedReview error, retry with different payment method
refundedFully refundedNo further refunds possible
voidedTransaction cancelled same-dayNo action needed
partial_refundPartially refundedAdditional refunds possible up to remaining amount

​
Polling Best Practices

Frequency: Check every 30-60 minutes during business hoursDuration: ACH payments take 3-5 business days to settleBetter Alternative: Implement webhooks for real-time status updates
Frequency: Check once immediately after creation, then hourly if neededDuration: Card payments typically complete within secondsTimeout: If pending after 5 minutes, likely an issue - investigate
For repeated status checks:
  1. First check: Immediate
  2. Second check: 30 seconds
  3. Third check: 1 minute
  4. Fourth check: 2 minutes
  5. Continue doubling up to maximum interval

​
Error Responses

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Payment not found"
    }
  ]
}

​
Common Use Cases

  1. Status Polling: Regularly check ACH payment status until settled
  2. Payment Confirmation: Verify payment completed before fulfilling orders
  3. Dashboard Updates: Display real-time payment status in admin interfaces
  4. Webhook Verification: Confirm status received via webhook matches current state

​
Performance Considerations

Lighter Payload: This endpoint returns significantly less data than GET /payments/, making it faster and more efficient for status checks.
Rate Limiting: Avoid excessive polling. Implement reasonable intervals or use webhooks instead.

​
Next Steps

Get Full Payment Details

Retrieve complete payment information including fees and splits

List Payments

View all payments for a merchant