Get Payment Details
GET
/payments/:paymentId
Retrieves detailed information about a specific payment by its ID. This endpoint automatically checks for updates from the payment processor for pending or processing payments before responding.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| paymentId required | string | The unique identifier of the payment to retrieve |
Example Request
GET /payments/550e8400-e29b-41d4-a716-446655440000
X-API-Key: your_api_key_here
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| payment_id | string | Unique identifier for the payment |
| status | string | Current status of the payment (pending, processing, completed, failed, expired) |
| amount_usd | number | The payment amount in USD |
| amount_crypto | number | The payment amount in cryptocurrency |
| blockchain | string | The blockchain network used for the payment |
| token | string | The cryptocurrency token used for payment |
| address | string | The cryptocurrency address for the payment |
| tx_hash | string | The blockchain transaction hash (if payment is processing or completed) |
| created_at | string | ISO 8601 timestamp of when the payment was created |
| updated_at | string | ISO 8601 timestamp of when the payment was last updated |
| expiry_time | string | ISO 8601 timestamp of when the payment request expires |
| custom_id | string | Your custom identifier for the payment (if provided) |
| customer_email | string | Email address of the customer (if provided) |
| callback_url | string | URL for callback notifications (if provided) |
| callback_sent | boolean | Indicates whether a callback notification has been sent |
| notes | string | Additional notes about the payment (if provided) |
Example Response
{
"payment_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"amount_usd": 100.00,
"amount_crypto": 0.05,
"blockchain": "ETH",
"token": "USDT",
"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
"tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"created_at": "2025-04-16T13:30:25.123Z",
"updated_at": "2025-04-16T14:45:30.456Z",
"expiry_time": "2025-04-16T14:30:25.123Z",
"custom_id": "ORDER-12345",
"customer_email": "customer@example.com",
"callback_url": "https://your-site.com/payment/callback",
"callback_sent": true,
"notes": null
}
Status Values
| Status | Description |
|---|---|
| pending | Payment has been created but no transaction has been detected yet |
| processing | A transaction has been detected but not yet fully confirmed on the blockchain |
| completed | Payment has been fully confirmed and processed |
| failed | Payment failed or was canceled |
| expired | Payment request expired before completion |
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 401 | authentication_failed | Authentication failed. Check your API key or JWT token |
| 403 | insufficient_permissions | Your API key does not have permission to view this payment |
| 404 | payment_not_found | Payment with the specified ID was not found |
| 429 | rate_limit_exceeded | You have exceeded the rate limit for this endpoint |
| 500 | payment_provider_error | An error occurred when checking the payment status with the payment processor |
Notes
- When checking a payment with status
pendingorprocessing, this endpoint will automatically check for updates from the payment processor before responding. - The
tx_hashfield is only populated once a transaction has been identified on the blockchain. - For
completedpayments, you can view the blockchain transaction details directly using a blockchain explorer by following thetx_hash. - Payments typically remain in the system for at least 30 days after completion or expiration.