View Payment Request Status

Overview

Once you've created a payment request, you can retrieve its current status, payment history, and details using several endpoints. There are different endpoints depending on whether you're viewing as the merchant (authenticated) or as a customer (public).

Merchant Endpoints (Authenticated)

These endpoints require API key authentication and the view_payments permission.

Get Single Payment Request

Retrieve detailed information about a specific payment request for your merchant account.

GET /api/payment-requests/{public_id}

Parameters:

• public_id (path): The payment request's public UUID

Example:

curl -H "X-API-Key: unter_YOUR_API_KEY_HERE" \
  https://api.unter.tech/api/payment-requests/550e8400-e29b-41d4-a716-446655440000

Response Format

{
  "data": {
    "public_id": "550e8400-e29b-41d4-a716-446655440000",
    "shortcode": "A4B2C8XZ",
    "amount": {
      "raw": "5000000",
      "formatted": "5.00",
      "decimals": 6
    },
    "token": {
      "id": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "contract_address": "0xA0b86a33E6441b8bE791C6611e17F9eA7e5Db0e8",
      "logo_url": "https://cryptologos.cc/logos/usd-coin-usdc-logo.png",
      "is_native": false,
      "is_stablecoin": true
    },
    "chain": {
      "id": 1,
      "slug": "ethereum",
      "name": "Ethereum",
      "symbol": "ETH",
      "chain_id": 1,
      "type": "evm"
    },
    "recipient_address": "0x742C4B8C2515Ad1D8e1C71e8e24c8D5F9A1a8B5A",
    "status": "active",
    "description": "Pro Plan Subscription - Monthly",
    "external_id": "invoice_789",
    "payment_url": "https://pay.unter.tech/pay/A4B2C8XZ",
    "redirect_url": "https://myapp.com/success?order=789",
    "cancel_url": "https://myapp.com/cancelled?order=789",
    "paid_amount": {
      "raw": "2500000",
      "formatted": "2.50",
      "decimals": 6
    },
    "remaining_amount": {
      "raw": "2500000",
      "formatted": "2.50",
      "decimals": 6
    },
    "payment_attempts": 1,
    "expires_at": "2024-08-15T18:00:00.000Z",
    "created_at": "2024-08-14T12:30:00.000Z",
    "completed_at": null,
    "metadata": {
      "customer_id": "cust_abc123",
      "plan": "pro",
      "billing_cycle": "monthly"
    },
    "payments": [
      {
        "id": "pay_1234567890",
        "transaction_hash": "0xabcd1234...",
        "status": "completed",
        "source_amount": {
          "raw": "2500000",
          "formatted": "2.50",
          "decimals": 6
        },
        "received_amount": {
          "raw": "2500000",
          "formatted": "2.50",
          "decimals": 6
        },
        "actual_fee": {
          "raw": "0",
          "formatted": "0.00",
          "decimals": 6
        },
        "created_at": "2024-08-14T13:45:00.000Z",
        "confirmed_at": "2024-08-14T13:47:00.000Z"
      }
    ]
  }
}

Understanding Payment Status

Status	Description
active	Payment request is open and accepting payments
completed	Full payment amount has been received
expired	Payment request has passed its expiration date
cancelled	Payment request was manually cancelled

Payment Progress Tracking

For partial payments, track these fields:

• amount: Total amount requested

• paid_amount: Amount received so far

• remaining_amount: Amount still needed