Get Payment Status

POST

/payments/status/

Retrieves detailed information about a specific payment by its transaction ID. This is also the way to get a single payment's full details, since the API does not expose a GET /payments/{id}/ endpoint.

Authentication

Requires OAuth 2.0 authentication with read and write scopes.

Request Body

Parameter	Type	Required	Description
`transaction_id` required	string (UUID)	Yes	The unique identifier of the payment to retrieve

Example Request

curl -X POST {{BASE_URL}}/payments/status/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

Success Response (200 OK)

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "blockchain": "TRX",
  "currency": "USDTTRC20",
  "status": "completed",
  "amount_usd": "100.00",
  "amount_crypto": "100.050000",
  "address": "TYN2WuEqttM5JjGk4ynGkxcnMRR9SZcvVx",
  "token": "USDT",
  "transaction_hash": "abc123def456...",
  "order_id": "ORDER-12345",
  "order_description": "Premium subscription",
  "callback_url": "https://your-site.com/webhook/payment",
  "expiry_time": "2026-01-15T10:30:00Z",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:20:00Z",
  "is_fixed_rate": true,
  "is_fee_paid_by_user": false
}

Response Fields (TransactionDetailSerializer)

Field	Type	Description
`transaction_id`	uuid	Unique payment identifier
`blockchain`	string	Blockchain network (e.g., "TRX", "ETH")
`currency`	string	Combined currency code (e.g., "USDTTRC20")
`status`	string	Current payment status (see Status Values below)
`amount_usd`	decimal	Amount in price currency (USD)
`amount_crypto`	string	Computed cryptocurrency amount
`address`	string	Blockchain address for the payment
`token`	string	Token symbol (e.g., "USDT", "USDC")
`transaction_hash`	string	Blockchain transaction hash (null until payment is detected on-chain)
`order_id`	string	Your order identifier
`order_description`	string	Payment description
`callback_url`	string	Webhook URL for status notifications
`expiry_time`	datetime	ISO 8601 timestamp when payment expires
`created_at`	datetime	ISO 8601 creation timestamp
`updated_at`	datetime	ISO 8601 last update timestamp
`is_fixed_rate`	boolean	Whether a fixed exchange rate was used
`is_fee_paid_by_user`	boolean	Whether the customer pays network fees

Status Values

Status	Description
`waiting`	Waiting for payment from customer
`confirming`	Payment received, waiting for blockchain confirmations
`confirmed`	Payment confirmed on blockchain
`sending`	Processing payment to merchant wallet
`completed`	Payment successfully completed
`expired`	Payment window expired without payment
`failed`	Payment failed

Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid or missing transaction_id"
  }
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Transaction with the specified ID was not found",
    "details": {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Notes

This endpoint serves as the way to retrieve a single payment's full details. There is no separate GET /payments/{id}/ endpoint.
The transaction_hash field is only populated once a transaction has been identified on the blockchain.
For real-time status updates, implement a webhook handler instead of polling this endpoint.
The wallet_id and customer_email fields may also be included in the response when they were provided during payment creation.